netlify-database-migrations

Migrations

Netlify Database uses a file-based migration system. Migrations live in netlify/database/migrations/ and are applied automatically by Netlify: on every deploy preview before the preview is published, and on production immediately before publish. A failing migration blocks the deploy.

Prefer Drizzle Kit for generating migrations. Manual SQL migration files are an edge case — only hand-write one when Drizzle Kit can't express the change (for example, a Postgres-specific DDL or a targeted DML operation).

Never apply migrations to a hosted database yourself

The platform applies migrations to every Netlify-hosted database (preview branches and production) automatically on deploy. You never run drizzle-kit migrate against NETLIFY_DB_URL from a preview or production context. For local, use netlify database migrations apply — it targets the local development database only.

drizzle-kit push is not used in this workflow at all — always generate a migration file and let the deploy apply it. And never run DDL through netlify database connect, psql, or any other direct connection: schema changes out-of-band cause drift between the migration history and the actual database.

Schema migration workflow

1. Edit db/schema.ts
2. npm run db:generate (runs drizzle-kit generate) — writes a new file into netlify/database/migrations/
3. Review the generated SQL
4. npm run db:migrate (runs netlify database migrations apply) — applies to the local dev DB for testing
5. Commit schema changes and the migration file together
6. Push — Netlify applies the migration to the preview branch, then to production on publish

Recommended package.json scripts:

{
  "scripts": {
    "db:generate": "drizzle-kit generate",
    "db:migrate": "netlify database migrations apply"
  }
}

netlify database migrations apply always targets the local dev DB. Running drizzle-kit migrate directly (especially with NETLIFY_DB_URL pointing at a hosted branch) is the wrong path — that's the deploy's job.