| name | zenstack-db-migration |
| description | Manage database schema migrations in ZenStack V3. Use when creating/applying migrations (zen migrate dev/deploy/reset/status/resolve), prototyping with zen db push, introspecting an existing database with zen db pull, seeding, handling unsupported features (views) with --create-only, or wiring migrations into a deployment pipeline. |
ZenStack V3 — Database Migrations
ZenStack keeps your database schema in sync with your ZModel data model. Migration is built on top
of Prisma Migrate: the zen CLI generates a Prisma
schema from your ZModel under the hood and wraps the corresponding Prisma command. If you know Prisma
Migrate, the workflow is identical — just swap prisma for zen. Existing migration history keeps
working once moved into ZenStack's layout (prisma/migrations → zenstack/migrations, the default
location next to zenstack/schema.zmodel).
This skill assumes a project is already set up (see zenstack-project-setup). Schema authoring is in
zenstack-schema-modeling. @zenstackhq/cli carries a peer dependency on prisma, installed
automatically when needed.
Run zen generate after schema changes to refresh generated types; migration commands operate on
the schema independently of the generated client.
Two ways to evolve the schema
| Approach | Command | When |
|---|
| Schema prototyping | zen db push | Local dev/experimentation — syncs the DB to the schema with no migration file. Fast, but loses history. Never in production. |
| Tracked migrations | zen migrate dev → zen migrate deploy | Anything you ship — generates reviewable, committed SQL migration files applied deterministically across environments. |
Typical loop: prototype with db push while iterating, then create a migration with migrate dev
once the shape settles.
Commands
All migration/db commands accept --schema <file> (defaults to zenstack/schema.zmodel) and
--migrations <path> (the directory holding migrations/).
zen migrate dev — create + apply a migration (development)
Diffs the schema against migration history, generates a new timestamped migration file, and applies
it to the dev database. Prompts if a full reset is required (e.g. drift).
zen migrate dev --name add_published_flag
-n, --name <name> — name the migration (otherwise you're prompted).--create-only — generate the migration file without applying it. Use this to hand-edit SQL,
or to implement features the migration engine doesn't generate yet (e.g. database views — create
an empty migration and write the SQL manually), then apply later with zen migrate dev.
Review the generated SQL before committing it to source control.
zen migrate deploy — apply pending migrations (production)
Applies all not-yet-applied migrations. Idempotent and non-interactive — this is the command for
your deployment pipeline. It never generates new migrations or resets data.
zen migrate deploy
zen migrate status — inspect migration state
Shows which migrations are applied vs. pending. Useful in CI before deploying.
zen migrate status
zen migrate resolve — fix history without touching the schema
Marks a migration as applied or rolled back — for manual recovery (e.g. a migration applied
out-of-band, or a failed one). Does not change the database schema.
zen migrate resolve --applied 20240101120000_add_users
zen migrate resolve --rolled-back 20240101120000_add_users
zen migrate reset — wipe and reapply (development)
Drops all tables and replays every migration from scratch. Destructive — dev/testing only, never
production.
zen migrate reset --force
If a seed script is configured, it runs after reset (use --skip-seed to skip).
zen db push — sync schema, no migration file (development)
Pushes the schema straight to the database. Great for rapid prototyping; no history is recorded.
zen db push
zen db push --accept-data-loss
zen db push --force-reset
zen db pull — introspect an existing database (v3.4.0+, experimental)
Loads the database schema, diffs it against your ZModel, and updates the ZModel to match. Useful for
adopting ZenStack on an existing DB, or re-syncing after out-of-band DB changes. This has its own
implementation (not Prisma's introspection engine).
zen db pull
Options: -o, --output <path>, --model-casing <pascal|camel|snake|none> (default pascal),
--field-casing <...> (default camel), --always-map (always emit @map/@@map),
--quote <double|single> (default single), --indent <number> (default 4).
Warning: zen db pull can overwrite your schema file. Commit or back it up first.
zen db seed — seed the database
Runs the seed script declared in package.json under zenstack.seed:
{ "zenstack": { "seed": "tsx ./zenstack/seed.ts" } }
zen db seed
zen db seed -- --users 10
Workflows
Development
- Edit
zenstack/schema.zmodel.
zen db push to try it instantly while iterating (optionally zen db seed).- When the shape is final,
zen migrate dev --name <change> to create the migration.
- Review the SQL, commit the migration file.
Production / CI deployment
zen migrate deploy
Run it in the release pipeline. Optionally gate on zen migrate status first. Do not run
db push, migrate dev, or migrate reset against production.
Adopt an existing database
zen init → set the datasource url → zen db pull → refine the schema (policies, computed
fields) → zen generate. See zenstack-project-setup.
Adopting from Prisma
Because migration wraps Prisma Migrate, your existing migration history keeps working once you move
the prisma/migrations directory to zenstack/migrations (ZenStack's default, next to
zenstack/schema.zmodel) and replace the prisma migrate ... / prisma db ... scripts with the
zen equivalents. Full framework migration is covered by zenstack-migrate-from-prisma.
Reference docs
Full ZenStack documentation for this topic is bundled under references/:
