A Database Migration pre-upgrade Job
Annotating a Job to run before the rollout.
A Database Migration pre-upgrade Job is a free Helm Academy lesson on CoddyKit — lesson 2 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Helm Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
A Real Use Case
Before new app code rolls out, your database schema often needs migrating. A pre-upgrade hook is the perfect spot to run that migration safely.
Why Before the Rollout
Running it as pre-upgrade means the schema is ready before the new pods start. The fresh code never talks to an old, mismatched database.
"helm.sh/hook": pre-upgradeStart With a Job
The migration runs once and then exits, so model it as a Kubernetes Job. Helm will wait for the Job to finish before continuing the upgrade.
apiVersion: batch/v1
kind: Job
metadata:
name: db-migrateAdd the Hook Annotation
Mark the Job as a hook in its metadata. The helm.sh/hook annotation set to pre-upgrade is what turns this ordinary Job into a hook.
metadata:
annotations:
"helm.sh/hook": pre-upgradeRun the Migration Command
The Job's container runs your migration tool. Point it at the same database the app uses so the schema changes land where they belong.
spec:
containers:
- name: migrate
image: myapp:1.4
command: ["./migrate", "up"]Never Restart on Failure
Set the Job's restartPolicy to Never or OnFailure. A migration that loops forever would block your upgrade and never let Helm proceed.
spec:
template:
spec:
restartPolicy: NeverTemplating the Image Tag
Keep the migrator in sync with the app by templating its tag. Reuse the same .Values.image.tag the deployment reads so versions match.
image: "myapp:{{ .Values.image.tag }}"Helm Blocks Until Done
Because it is a pre-upgrade hook, Helm pauses the upgrade until the Job reports success. If migration fails, the rollout never happens. 🛑
Clean Up After Success
Old migration Jobs pile up otherwise. Pair the hook with a hook-delete-policy so a successful Job is removed instead of cluttering the namespace.
"helm.sh/hook-delete-policy": hook-succeededUnique Names Help
Hook Jobs are immutable once created, so a fixed name can collide on the next upgrade. Including the .Release.Revision in the name keeps each run distinct.
name: db-migrate-{{ .Release.Revision }}Test It With a Dry Run
Before a real upgrade, render the chart to confirm the hook looks right. A dry-run shows the Job manifest Helm would create without touching the cluster.
helm upgrade myapp ./mychart --dry-runQuick Check
You need a schema migration to run before new app pods start during an upgrade.
Recap
You modeled a migration as a pre-upgrade Job, set restartPolicy to Never, and let Helm block until it succeeds before rolling out new code. 🗄️
Frequently asked questions
Is the “A Database Migration pre-upgrade Job” lesson free?
Yes — the full text of “A Database Migration pre-upgrade Job” is free to read here on the web, and the Helm Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Helm Academy course, upgrade to CoddyKit PRO.
What will I learn in “A Database Migration pre-upgrade Job”?
Annotating a Job to run before the rollout. You practise Helm Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start Helm Academy?
No prior experience is required. Helm Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 2 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “A Database Migration pre-upgrade Job” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this Helm Academy lesson?
Yes. Every Helm Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.
All lessons in this course
- What Hooks Are and When They Fire
- A Database Migration pre-upgrade Job
- Hook Weights and Ordering
- Hook Deletion Policies