Skip to content
Tutorials Center
My learning

Topics

Lesson 33 of 36 ยท Testing and Deployment

Deploying Prisma Apps

Deploy a Prisma application safely - run migrate deploy in CI, generate the client at build time, use Docker and serverless correctly, and apply zero-downtime migration rules.

Deploying an app that uses Prisma adds three jobs beyond shipping code: generate the client, apply migrations to the production database, and provide the right environment variables. Done in the wrong order or by the wrong command, these cause outages. This lesson gives a reliable recipe and a checklist.

All commands and config below are read-only. The TryIt is a labelled stand-in: a "preflight" check that compares migration folders with the history table, the idea behind migrate status.

The deployment sequence

flowchart LR
  A["npm ci"] --> B["prisma generate"]
  B --> C["build app (tsc / bundler)"]
  C --> D["prisma migrate deploy"]
  D --> E["start new app version"]

Generate and build happen before release; migrate deploy runs once, before the new code starts serving.

  1. Install dependencies with a lockfile (npm ci). prisma (the CLI) must be available at build time; @prisma/client and your adapter at runtime.
  2. Generate the client: npx prisma generate. In Prisma 7 the client is generated into your own folder (the output path in the generator block), so it must exist before TypeScript compiles. Many teams run it in a postinstall script or an explicit build step.
  3. Build your app.
  4. Migrate: npx prisma migrate deploy, using the production DATABASE_URL. It applies pending migrations and is safe to run repeatedly.
  5. Start the new version.

Never run migrate dev, migrate reset or db push against production.

Configuration

Prisma 7 reads CLI settings from prisma.config.ts, and the app reads DATABASE_URL from the environment. Keep secrets out of Git: use your platform's secret store, not committed .env files.

TypeScript
// prisma.config.ts
import 'dotenv/config';
import { defineConfig, env } from 'prisma/config';

export default defineConfig({
  schema: 'prisma/schema.prisma',
  migrations: { path: 'prisma/migrations' },
  datasource: { url: env('DATABASE_URL') },
});

If you use a pooler at runtime, give the migrate step a direct URL (for example a second variable DIRECT_URL read in the config) as described in connection pooling.

CI/CD with GitHub Actions

YAML
name: ci
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:17
        env: { POSTGRES_PASSWORD: test, POSTGRES_DB: app_test }
        ports: ['5432:5432']
        options: >-
          --health-cmd "pg_isready -U postgres" --health-interval 5s --health-retries 10
    env:
      DATABASE_URL: postgresql://postgres:test@localhost:5432/app_test
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 24, cache: npm }
      - run: npm ci
      - run: npx prisma generate
      - run: npx prisma migrate deploy      # proves the history applies to an empty database
      - run: npm test

Running migrate deploy on an empty database in CI is a cheap, powerful check: it fails if any migration is broken or out of order. Add npx prisma migrate diff --exit-code --from-migrations prisma/migrations --to-schema prisma/schema.prisma (with the shadow database URL configured) to fail the build when someone changed schema.prisma but forgot to commit a migration.

Docker

DOCKERFILE
FROM node:24-slim AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npx prisma generate && npm run build

FROM node:24-slim
WORKDIR /app
ENV NODE_ENV=production
COPY --from=build /app/package*.json ./
COPY --from=build /app/node_modules ./node_modules
COPY --from=build /app/dist ./dist
COPY --from=build /app/prisma ./prisma
COPY --from=build /app/prisma.config.ts ./
CMD ["node", "dist/server.js"]

Run migrations as a separate release step (docker run image npx prisma migrate deploy, a Kubernetes Job, or your platform's release command) rather than in the container's start command. If ten replicas start at once, each trying to migrate, Prisma uses a database advisory lock so only one proceeds, but a dedicated step is clearer and keeps failures visible. If you do migrate at start, expect a slower first boot.

Serverless and edge

  • Generate the client during the build, and make sure your bundler includes the generated folder (and any native files the adapter needs).
  • Use an adapter and pooling built for serverless (see connection pooling).
  • Do not run migrate deploy inside a function. Run it from CI or a release job.
  • Edge runtimes (Cloudflare Workers, Vercel Edge) need an HTTP-based or edge-compatible adapter and have no TCP sockets in many cases.

Zero-downtime migration rules

During a deploy, old and new app versions run side by side against one database. Every migration must work for both (see the expand and contract pattern in migration files and drift):

  • Add columns as nullable or with defaults; never add a required column without a default in one step.
  • Do not rename or drop a column in the same release that stops using it. Drop it in a later release.
  • Create large indexes with CREATE INDEX CONCURRENTLY (PostgreSQL) in a hand-edited migration; a plain CREATE INDEX locks writes.
  • Keep migrations short; long locks block your app. Set a lock_timeout so a migration fails fast instead of queueing everything behind it.
  • Back up (or snapshot) before risky changes, and know the rollback plan: Prisma has no automatic down migrations, so roll forward with a new migration.

Preflight check stand-in

Node.js Stand-in: preflight check of migrations vs history

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Production checklist

  • migrate deploy is the only migration command used.
  • A separate, direct database URL for migrations; least-privilege runtime user.
  • Backups verified before schema changes.
  • Query logging off or sanitized, slow-query alerting on.
  • Health endpoint that runs SELECT 1; graceful shutdown calls prisma.$disconnect().
  • Pool size times instance count fits the database limit.
TypeScript
process.on('SIGTERM', async () => {
  await server.close();
  await prisma.$disconnect();
  process.exit(0);
});

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command applies migrations in production?

    migrate deploy applies only pending migrations and never resets or creates new ones.
  2. 2. Why run migrate deploy as a release step rather than inside every serverless function?

    Migrations belong to the release process, not to each short-lived runtime instance.
  3. 3. What is the safest way to remove a column during zero-downtime deploys?

    The previous app version may still read the column while the new one rolls out.
  4. 4. How do you roll back a bad migration with Prisma?

    Prisma has no automatic down migrations; you add a corrective migration.

Summary

  • Deploy sequence: install, prisma generate, build, prisma migrate deploy, start.
  • CI should run migrate deploy on an empty database and fail when the schema has no migration.
  • Run migrations as a release step with a direct URL; never use dev, reset or push in production.
  • Docker and serverless need the generated client in the artifact and sensible pooling.
  • Write migrations that work for old and new code, and roll forward rather than back.

Next: Project: A Blog API