Prisma migrate deploy in production: when and where to run your migrations with Docker
Prisma migrations in production with Docker or Coolify: what migrate deploy does, where to run it and how to change the schema without taking the app down.
This blog belongs to CREA.MBA, a Next.js boilerplate with auth, payments and an admin panel already set up. See what's included
Locally, Prisma migrations are one command: prisma migrate dev, done. In production you run into questions the docs answer in bits and pieces. Do they run during the build or at startup? What happens with two containers? And what if the migration renames a column the previous version of the app is still reading?
That's what this post is about, with Prisma 7, PostgreSQL and a Next.js app deployed in Docker. The platform examples are from Coolify because that's what we use, but the reasoning holds for Railway, Fly.io or a hand-written docker compose.
migrate dev locally, migrate deploy in production
The Prisma docs leave no room for doubt: migrate dev is a development command and must never be used in production. It creates new migrations, uses a "shadow" database and, if it finds your database out of sync with the history, offers to reset it.
In production you use prisma migrate deploy, which is much more modest:
- It applies pending migrations from
prisma/migrations/, in order. - It warns if an already-applied migration has been modified.
- It does not generate new migrations, does not reset anything and does not use a shadow database.
- It does not detect drift: if someone changed the database by hand, it won't notice.
- It does not generate the Prisma client.
That last point is easy to forget. The client is generated at build time (prisma generate), and migrations are applied against the real database. Two separate steps that happen at different moments.
First things first: migrations belong in git
Sounds obvious, but we've seen it break a deploy: a .gitignore inherited from some template with prisma/migrations in it. Locally everything works because the migrations are on your disk; on the server, migrate deploy finds nothing to apply and the app starts against tables that don't exist.
Before your first deploy, check .gitignore:
grep -n -i -E "prisma|migrations" .gitignoreWhat you do ignore is the generated client (in Prisma 7, whatever folder you set as output, typically src/generated/), .env files and local databases.
Prisma 7: the URL lives in prisma.config.ts
Prisma 7 changes a few pieces that affect deployment. The connection URL leaves the schema's datasource block and moves to prisma.config.ts, and environment variables are no longer loaded automatically. This is how the CREA.MBA boilerplate handles it:
// prisma.config.ts
import dotenv from 'dotenv';
import { existsSync } from 'fs';
import { defineConfig, env } from 'prisma/config';
if (existsSync('.env.local')) {
dotenv.config({ path: '.env.local' });
} else {
dotenv.config();
}
export default defineConfig({
schema: 'prisma/schema.prisma',
migrations: { path: 'prisma/migrations', seed: 'bun prisma/seed.ts' },
datasource: { url: env('DATABASE_URL') },
});There's no .env in the container, so dotenv loads nothing and env('DATABASE_URL') reads the variable the platform injects. Two other version 7 changes worth keeping in mind: migrate dev no longer runs generate on its own, and the seed no longer runs automatically after migrate dev or migrate reset.
The build doesn't need the database
prisma generate doesn't connect to anything: it reads the schema and writes code. But if your prisma.config.ts requires DATABASE_URL, the build fails on a platform that doesn't expose the variable at build time. The boilerplate solves it with a placeholder used only for that step:
"build": "DATABASE_URL=${DATABASE_URL:-postgresql://placeholder:placeholder@localhost:5432/placeholder} prisma generate && next build"What you shouldn't do is apply migrations during the build (a RUN prisma migrate deploy in the Dockerfile). The image would then depend on the production database being reachable from the build environment, and building the image would modify production even if you never deploy it.
Three options for running it
That leaves three reasonable places. Each one has a price.
1. When the container starts
The start command applies migrations and then boots the app:
bunx prisma migrate deploy && bun startIt's the simplest option and works well with a single instance. If the migration fails, the app doesn't start; with a healthcheck configured in Coolify, the new deployment fails the check and the previous version keeps serving.
With several replicas, they all try to migrate at once. Prisma handles this with a PostgreSQL advisory lock: only one runs the migrations and the rest wait. The wait is 10 seconds and isn't configurable, according to the docs. If a migration takes longer (an index on a large table, say), the other replicas fail to start and have to be retried.
A packaging detail: in many projects prisma (the CLI) sits in devDependencies. If your production image only installs production dependencies, the command won't exist in the container. Either move it to dependencies or run the migration from a different image.
2. As a separate step before deploying
This is what Prisma recommends: migrate deploy inside a CI/CD pipeline, against the production database, and the new version only ships if it succeeds. In GitHub Actions, that's a preceding job with DATABASE_URL as a secret.
The cost is that the database has to be reachable from wherever the pipeline runs. With Postgres on your VPS and no public port (the norm in Coolify), that means opening a tunnel or a port, and it's not always worth it.
3. Coolify's pre- and post-deployment commands
Coolify has two fields for this, and its docs explain a difference that changes the choice:
- The pre-deployment command runs in the current container, before it's replaced. That is, with the code and the
prisma/migrationsfolder of the previous version. The new migrations aren't there yet. On top of that, on the first deploy there's no current container and Coolify skips it. - The post-deployment command runs in the new container, but once the deployment has already been marked as complete. If it fails, it shows up in the log and the deployment stays marked as successful.
Neither is a great fit for migrate deploy. Pre-deployment can't see the new migrations, and post-deployment leaves the new app serving for a few seconds against the old schema, without stopping anything if the migration fails. That's why, on a single-instance server, we prefer option 1.
Changing the schema without taking the app down
Whichever option you pick, there's a window where the old version of the app and the new schema coexist (or the other way round). With a migration that only adds a table or an optional column, it doesn't matter. With one that drops or renames, it does.
Prisma, for instance, generates a column rename as DROP + ADD unless you edit it by hand, so you lose the data. And even if you write a RENAME COLUMN, the previous instance keeps looking for the old name until it's replaced.
The pattern that avoids nasty surprises is called expand and contract: destructive changes are spread over several deploys.
- Expand. Add the new column, optional or with a default. The app writes to both and reads from the old one.
- Migrate data. Copy existing data to the new column, with a script or in the SQL migration itself.
- Switch reads. The app reads from the new one.
- Contract. In a later deploy, drop the old column.
For a SaaS with few users it can sound like ceremony. But it only takes one NOT NULL added to a table with rows for the migration to fail in production halfway through a deploy, and then you'll wish you'd done it in two steps.
Before every deploy that includes migrations, read the SQL Prisma generated in prisma/migrations/_/migration.sql. It's the only way to see whether an innocent-looking schema change turned into a DROP.
When a migration fails halfway
If migrate deploy fails, Prisma marks the migration as failed in the _prisma_migrations table and won't apply any more until you resolve it. The steps:
- Look at the error and the actual state of the database: which parts of the migration got applied.
- Fix things by hand as needed (undo what was applied or finish it).
- Mark the migration with
prisma migrate resolve --rolled-backif you're going to rerun it, or--appliedif you finished it by hand. - Run
migrate deployagain.
To get there calmly, take a database backup before every deploy with destructive migrations. In Coolify, scheduled Postgres backups are enabled from the resource settings and can be triggered by hand before deploying.
Keep the seed away from production
A tempting move when setting up a new environment is running the seed to get some data. Check what it does first: demo seeds usually start with deleteMany() to leave the database clean, and many starters' seeds (CREA.MBA's included) work that way. Against a production database, that means deleting everything.
For data you need in production (plans, categories, an admin user), write a separate, idempotent script using upsert that you can run twice without consequences.
Takeaways
migrate devlocally;migrate deployin production, always.- Migrations go in git. The generated client doesn't.
- The build generates the client; migrations are applied outside the build.
- With one instance, migrating at startup is the simplest. With several, mind the advisory lock and its 10 seconds.
- In Coolify, pre-deployment runs with the old code: it won't work for new migrations.
- Destructive changes, across several deploys.
If you're setting up the server, we cover the infrastructure side in Hetzner + Coolify as a Vercel alternative, and why we chose this ORM in Prisma + PostgreSQL for SaaS. CREA.MBA ships Prisma 7 configured with prisma.config.ts, the PostgreSQL adapter and a build set up so it doesn't need the database.
Where do you run your migrations: at startup, in the pipeline or by hand over SSH?
Enjoyed this article?
Subscribe for more tutorials and tips on building products with AI