Where database migrations should run in a deploy.

A deploy has three places where you can put migrate. Only one of them runs exactly once, at the right moment.

It is tempting because the build already has DATABASE_URL and it is one line: npm run build && npx prisma migrate deploy. The problem is ordering. The build finishes, the new version starts, and only then do you learn whether it boots. If it doesn’t, the schema has moved and the code that matches it is not running. Rolling back to the previous commit now means old code against a new schema.

Previews make it worse. On most platforms, Canner included, a pull-request preview builds with the same database as production unless you split it out. A migration in the build means opening a pull request changes production.

Docker images have the same trap from the other side: a RUN step that migrates inside the image build needs database credentials at image-build time and runs once per image, not once per deploy.

npx prisma migrate deploy && node server.js works, and Canner’s start command accepts it. But it runs every time the process starts. On Canner that includes crash restarts and, on Starter, every wake after the 3-hour sleep, so the first visitor after a quiet night waits for the migration check as well as the boot.

It also eats your health-check budget. Canner gives a new version 30 seconds to answer on its health-check path. A migration that rewrites a large table inside the start command can use that up, the deploy is marked failed, and the migration may have half-finished. On platforms with several instances, every instance runs it at once, and you are relying entirely on the tool’s lock.

A release step runs once per deploy, but two deploys can still overlap: a push lands while the previous release is running, or someone runs the command by hand. Most tools take a Postgres advisory lock so the second run waits. Heroku’s release-phase docs tell you to take one yourself if your tool doesn’t.

Advisory locks belong to a database session. Behind a transaction-mode pooler such as PgBouncer, consecutive statements can land on different server connections and the lock does nothing, which is why Rails documents turning advisory_locks off behind PgBouncer. On Canner both DATABASE_URL and the migration login are session connections, so leave the locks on.

• Prisma: migrate deploy takes an advisory lock with a 10-second timeout that cannot be changed. If it times out, run it again. Since 5.3.0 PRISMA_SCHEMA_DISABLE_ADVISORY_LOCK turns it off; don’t, unless nothing else can run Migrate at the same time.
• Rails: Active Record uses advisory locks on Postgres by default.
• Laravel: php artisan migrate --isolated takes an atomic lock through your cache driver, so every server must share the same cache store. A second run that finds the lock held exits successfully without migrating.
• Django: migrate takes no lock of its own. Rely on the release step running once, or wrap it with pg_advisory_lock yourself.

A migration tool records what it applied in a ledger table (_prisma_migrations, schema_migrations, django_migrations, migrations) and skips those next time, so running the command twice is fine. What breaks reruns is a migration that half-applied.

Postgres can roll back schema changes inside a transaction. Django runs migrations in a transaction on Postgres by default, and Rails wraps each migration in one. Keep that on. The exceptions are statements Postgres refuses inside a transaction, such as CREATE INDEX CONCURRENTLY; those need atomic = False in Django or disable_ddl_transaction! in Rails, and should sit in a migration of their own so a failure leaves nothing else half-done.

Seed data belongs in the release step too, written as upserts (INSERT … ON CONFLICT DO NOTHING) so the second run changes nothing.

The login that can ALTER TABLE is the login an attacker wants. Give the running app a role that can read and write rows but not change the schema, and keep the owner for migrations.

On Canner’s dedicated instance, canner db least-privilege (see the CLI) does this in one step: the app gets a read-write role as DATABASE_URL, every well-known migration ledger stays read-only for it, and the owner is handed to the release command alone as DATABASE_URL_MIGRATE. Builds and the running app never see it. Point your tool at it in the release command:

# Prisma (schema.prisma: url = env("DATABASE_URL"))
DATABASE_URL=$DATABASE_URL_MIGRATE npx prisma migrate deploy

# Django, Rails, Laravel: same idea
DATABASE_URL=$DATABASE_URL_MIGRATE python manage.py migrate --noinput

Prisma and Drizzle need their CLI at release time. If prisma or drizzle-kit is in devDependencies and your install prunes them, the release command fails with command not found; move the CLI to dependencies. Prisma’s newest docs replace migrate deploy with db migrate; the rule is the same, it goes in the release command.

Drizzle `push` or `migrate`? drizzle-kit push applies the schema diff directly with no SQL files. Drizzle calls it the best approach for rapid prototyping, and says some teams use it in production. It also asks before data-loss statements unless you pass --force, which a deploy can’t answer. For a shared production database, generate plus migrate gives you SQL you can read in review before it runs.

Rails 8 on Canner: with no release command set, Canner runs bundle exec rails db:prepare before each new version starts, which also sets up the Solid Cache, Queue and Cable databases. See Rails hosting.

A release step changes the database while the previous version is still serving. That holds on every platform with a release phase. For a moment, and for longer if you roll back, old code meets the new schema.

So each deploy’s migration has to work with the code before it. Adding a nullable column or a new table is safe. Dropping or renaming a column the old code reads is not: requests fail until the new version is up, and a rollback to the old commit fails outright.

• Rename in steps: add the new column, write to both, backfill, switch reads, stop writing the old one, drop it in a later deploy.
• Drop in two deploys: first ship code that no longer reads the column (Rails: ignored_columns), then drop it.
• NOT NULL on an existing column: add it nullable, backfill, then add the constraint.
• Indexes on big tables: CREATE INDEX CONCURRENTLY, in its own non-transactional migration.