Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add zenstackhq/skills --skill zenstack-db-migration -a claude-code
Open on GitHub

What 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_flag for 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-code

2Manually: put the files in place

~/.claude/skills/zenstack-db-migration/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/zenstack-db-migration/

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

Similar skills

All skills for DevOps and infrastructure →

From the same set9

zenstack-access-control The zenstack-access-control Claude Code skill helps define access policies in a ZenStack V3 schema. It activates for @@allow, @@deny, auth(), and post-update rules. CX Codex +1 556installs zenstack-crud-server zenstack-crud-server — a skill for Claude Code that turns ZenStack V3 models into REST or RPC CRUD APIs. It covers server routes, per-request access control, OpenAPI specs, and client calls. CX Codex +1 548installs zenstack-plugin-dev The zenstack-plugin-dev Claude Code skill guides development of ZenStack V3 plugins. It applies to ZModel extensions, CLI code generation, and ORM client plugins. CX Codex +1 521installs zenstack-migrate-from-prisma The zenstack-migrate-from-prisma Claude Code skill guides a project migration from Prisma to ZenStack V3. It covers schema, client, generation, and migration updates. CX Codex +1 520installs zenstack-migrate-from-v2 The zenstack-migrate-from-v2 skill for Claude Code guides a ZenStack project upgrade from V2 to V3. It covers schema, access policies, server adapters, and client hooks. CX Codex +1 515installs zenstack-project-setup The zenstack-project-setup Claude Code skill sets up ZenStack V3 projects, scaffolds new ones, and runs zen CLI tasks. It activates for ZenStack installation, project creation, or CLI use. CX Codex +1 510installs zenstack-querying The zenstack-querying Claude Code skill explains how to query and change data with the ZenStack V3 client. It covers ORM operations, relations, and SQL-shaped queries built with Kysely. CX Codex +1 494installs zenstack-schema-modeling The zenstack-schema-modeling Claude Code skill helps write and revise ZModel schemas for ZenStack V3. It activates for work on models, fields, relations, enums, and typed JSON fields. CX Codex +1 470installs

Project sponsors

Companies that keep this analytics open