How do you manage database schema migrations in a GitOps workflow?

Database schema migrations are inherently imperative and ordered — they run once, in sequence, and must complete successfully before the application starts. This sits awkwardly with GitOps's declarative, continuously-reconciled model. Three patterns handle this well.

1. Argo CD PreSync hook with a Kubernetes Job: Annotate a migration Job with argocd.argoproj.io/hook: PreSync. Argo CD runs the Job before applying any other resources in the sync. If the Job fails, the sync aborts and the application is not updated. Set hook-delete-policy: BeforeHookCreation to clean up the previous Job before creating a new one.

apiVersion: batch/v1
kind: Job
metadata:
  name: db-migration
  annotations:
    argocd.argoproj.io/hook: PreSync
    argocd.argoproj.io/hook-delete-policy: BeforeHookCreation
spec:
  template:
    spec:
      containers:
        - name: migrate
          image: registry.example.com/my-app:v1.5.2
          command: ["./migrate", "--run"]
      restartPolicy: Never

2. Sync waves: If you don't want a PreSync hook, use argocd.argoproj.io/sync-wave: "1" on the migration Job and sync-wave: "2" on the Deployment. Argo CD waits for wave 1 to succeed before starting wave 2. The Job must complete (not just start) for the wave transition to occur.

3. Flyway / Liquibase as an init container: Embed migration logic directly in the application Pod as an init container. The init container runs flyway migrate or liquibase update against the database before the main container starts. Migration SQL files are packaged inside the application image. No separate Job needed — migrations run atomically with Pod startup. Downside: the application image must always include all historical migrations.

Invest now in Acorns!!! 🚀
Join Acorns and get your $5 bonus!

Acorns is a micro-investing app that automatically invests your "spare change" from daily purchases into diversified, expert-built portfolios of ETFs. It is designed for beginners, allowing you to start investing with as little as $5. The service automates saving and investing. Disclosure: I may receive a referral bonus.

Invest now!!! Get Free equity stock (US, UK only)!

Use Robinhood app to invest in stocks. It is safe and secure. Use the Referral link to claim your free stock when you sign up!.

The Robinhood app makes it easy to trade stocks, crypto and more.

Webull! Receive free stock by signing up using the link: Webull signup.