zenstack-db-migration — Claude Code skill for database migrations
The zenstack-db-migration Claude Code skill manages database schema migrations in ZenStack V3. It activates for migration work, schema prototyping, or introspecting an existing database.
MIT 551 installs ★ 3 updated 2026-10-28
npx skills add zenstackhq/skills --skill zenstack-db-migration -a claude-codeWhat zenstack-db-migration does
The skill guides ZenStack V3 migration work: create and apply changes with zen migrate dev and zen migrate deploy, inspect migration status, or repair migration history. For local experiments, zen db push syncs the schema without recording a migration. zen db pull reads an existing database schema into ZModel; the experimental command can overwrite the schema file.
Use --create-only to produce a migration file without applying it, then edit its SQL manually, including for database views. zen migrate reset drops tables and replays migrations, so it is limited to development and testing, never production. Run zen generate after schema edits to refresh generated types.
The ZenStack project must already be set up. @zenstackhq/cli has a peer dependency on prisma and installs it automatically when needed.
What it helps with
- create and apply a migration from ZModel changes
- sync a database to the schema without recording migration history
- check which migrations are pending
- load an existing database schema into ZModel
- prepare migration commands for a deployment pipeline
Example prompts for the agent
- Create a migration named
add_published_flagfor the ZenStack schema changes. - Show which migrations have been applied and which are pending.
- Read the existing database schema into the ZModel file.
How to install zenstack-db-migration
1Skills CLI (Vercel)
npx skills add zenstackhq/skills --skill zenstack-db-migration -a claude-code2Manually: put the files in place
~/.claude/skills/zenstack-db-migration/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/zenstack-db-migration/
1Skills CLI (Vercel)
npx skills add zenstackhq/skills --skill zenstack-db-migration -a codex2Manually: put the files in place
.agents/skills/zenstack-db-migration/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add zenstackhq/skills --skill zenstack-db-migration -a cursor2Manually: put the files in place
.cursor/skills/zenstack-db-migration/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install zenstackhq/skills skills/zenstack-db-migration2Manually: put the files in place
.github/skills/zenstack-db-migration/SKILL.md1Skills CLI (Vercel)
npx skills add zenstackhq/skills --skill zenstack-db-migration -a gemini-cli2Platform CLI
gemini skills install https://github.com/zenstackhq/skills --path skills/zenstack-db-migrationManually: put the files in place
.devin/skills/zenstack-db-migration/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add zenstackhq/skills --skill zenstack-db-migration -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about zenstack-db-migration
How do I install zenstack-db-migration in Claude Code?
Run npx skills add zenstackhq/skills --skill zenstack-db-migration -a claude-code. The skill file is installed at ~/.claude/skills/zenstack-db-migration/SKILL.md.
What does zenstack-db-migration do?
It guides ZenStack V3 migration tasks, including creating and applying changes, checking migration status, and syncing a model with an existing database. It also covers migration workflows for deployment pipelines.
What does zenstack-db-migration need to work?
The ZenStack project must already be set up. @zenstackhq/cli uses prisma as a peer dependency and installs it automatically when needed.
Source text
SKILL.md · MIT
---
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](https://www.prisma.io/docs/orm/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).
```bash
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.
```bash
zen migrate deploy
```
### `zen migrate status` — inspect migration state
Shows which migrations are applied vs. pending. Useful in CI before deploying.
```bash
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.
```bash
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**.
```bash
zen migrate reset --force # --force skips the confirmation prompt
```
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.
```bash
zen db push
zen db push --accept-data-loss # proceed despite data-loss warnings
zen db push --force-reset # reset the DB before pushing
```
### `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).
```bash
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`:
```json
{ "zenstack": { "seed": "tsx ./zenstack/seed.ts" } }
```
```bash
zen db seed
zen db seed -- --users 10 # args after -- are forwarded to the seed script
```
## Workflows
**Development**
1. Edit `zenstack/schema.zmodel`.
2. `zen db push` to try it instantly while iterating (optionally `zen db seed`).
3. When the shape is final, `zen migrate dev --name <change>` to create the migration.
4. Review the SQL, commit the migration file.
**Production / CI deployment**
```bash
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/`](references/):
- [migration.md](references/migration.md) — migration concepts and workflows
- [introspection.md](references/introspection.md) — `zen db pull` introspection
- [cli-reference.md](references/cli-reference.md) — complete `migrate`/`db` command + option reference
© zenstackhq · MIT · zenstackhq/skills