Helm Academy · Lesson

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. This is 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, and your progress syncs across the web and the CoddyKit app. The Helm Academy course includes 4 lessons in total.

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-upgrade

Start 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-migrate

Add 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-upgrade

Run 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: Never

Templating 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-succeeded

Unique 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-run

Quick 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. 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. The Helm Academy course includes 4 lessons in total.

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, so you can start here or from the beginning and move at your own pace. This is lesson 2 of 4.

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

← Back to Helm Academy