migrate

Overview ¶

Command migrate applies the database migrations.

It is a program of its own rather than a step in the server's startup, and that is the whole point of it: with several replicas, a migration at startup means one migrator per pod and no order between them. Here it runs once - as a Compose service the application waits for, and as a Helm pre-upgrade hook (deployment.md §2).

Two properties matter more than anything else it does:

• Only one migrator at a time. A PostgreSQL advisory lock held for the length of the run, so a second one waits rather than interleaves. A retried hook, a rollout started twice, an operator running it by hand during a deploy - all of them wait.
• Forward only. goose applies what has not been applied; there is no down. Recovery from a bad deploy is a restore, not a reversal (rule 12, ADR-0003).

The migrations travel inside the binary, so the schema a version brings and the code that reads it cannot come apart.