Generate and apply a schema migration
Local development
Neon · Const
Prisma migrate
Neon’s Prisma Migrate workflow uses a pooled connection for application runtime and a direct connection for Prisma CLI schema changes. Generate and test migrations with migrate dev; apply committed migrations in production with migrate deploy.
How it works
Prisma Migrate uses a direct Neon connection for schema operations because pooled connections through PgBouncer are unsuitable for DDL. During development, change the Prisma schema and run migrate dev to generate, review, and apply SQL migration files; in production, run migrate deploy to apply only migrations already created.
Syntax
npx prisma migrate dev --name <descriptive-name>
npx prisma migrate deployParameters
| Name | Type | Description |
|---|---|---|
--name | option | A descriptive label for the migration being generated. |
Returns
Development commands generate and apply migration files; production deploy applies pending migration files.
Key points
- Use the pooled Neon URL for normal application queries.
- Use the direct Neon URL for Prisma CLI commands that inspect or change schema.
- Schema changes begin by editing the Prisma model definition.
- Give each development migration a descriptive name when generating it.
- Inspect the generated SQL before treating a schema change as ready.
- Run local application checks after applying a development migration.
- Production deployment consumes pending migration files rather than creating them.
Common mistakes
- Configure Prisma CLI migrations with the unpooled Neon connection, not the pooled runtime connection.
- Do not use migrate dev in production; deploy applies existing pending migrations without generating new ones.
Example: Run Prisma migrations
npx prisma migrate dev --name init
npx prisma migrate deployCreate and apply a development migration, then apply pending migrations in production.
When to use it
Apply committed pending migrations
Production release
Inspect generated SQL before deployment
Schema review
Test changed models locally
Application verification
Interview questions
QWhy does Neon require two connection strings for Prisma?
Use the pooled connection for application runtime and the direct, unpooled connection for Prisma CLI schema operations. Prisma Migrate needs the direct connection so DDL does not pass through PgBouncer.
Follow-up: Why should production use migrate deploy? It applies pending migration files without creating new ones, making deployment behavior repeatable.
QWhat is the normal development workflow?
Run prisma migrate dev --name descriptive-name after changing schema.prisma. Prisma generates SQL under prisma/migrations, applies it to the development database, and supports reviewing and testing the result.
Follow-up: What is the production counterpart? prisma migrate deploy applies the committed pending migrations without generating additional migration files.
QHow do migrate dev and migrate deploy differ?
migrate dev is intended to generate and apply migrations during development, while migrate deploy is intended to apply already-generated migrations in production. The latter does not generate new migrations.
Follow-up: What should be checked before deployment? Review the generated SQL, test the application, and then deploy the migration artifacts.
Related
prisma/schema.prismaprisma/migrations/DATABASE_URLDATABASE_URL_UNPOOLEDprisma migrate devprisma migrate deploy