К основному содержанию
скилл CX Codex

zenstack-db-migration — скилл для Claude Code: миграции БД

Скилл zenstack-db-migration для Claude Code управляет миграциями схемы базы данных в ZenStack V3. Вызывается при создании и применении миграций, синхронизации схемы или работе с существующей базой.

MIT 551 установок ★ 3 обновлён 2026-10-28

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add zenstackhq/skills --skill zenstack-db-migration -a claude-code
Открыть на GitHub

Что делает zenstack-db-migration

Скилл помогает вести схему ZenStack V3: создавать и применять миграции командами zen migrate dev и zen migrate deploy, смотреть их статус и исправлять историю. Для локальных экспериментов есть zen db push без файла миграции, а zen db pull считывает схему существующей базы и обновляет ZModel. Последняя команда экспериментальная и может перезаписать файл схемы.

В миграциях можно создать SQL-файл без применения через --create-only, вручную добавить поддержку представлений базы и запустить изменения позже. zen migrate reset удаляет таблицы и повторно применяет миграции, поэтому его используют только в разработке или тестах, не в production. После изменений схемы запускают zen generate для обновления типов.

Проект ZenStack должен быть настроен заранее. CLI @zenstackhq/cli использует prisma как peer dependency и устанавливает её автоматически, когда это нужно.

Какие задачи решает

  • создать и применить миграцию из изменений ZModel
  • синхронизировать базу со схемой без файла миграции
  • проверить, какие миграции уже применены
  • считать схему существующей базы в ZModel
  • подготовить применение миграций в CI или deployment pipeline

Примеры запросов агенту

  • Создай миграцию add_published_flag для изменений в схеме ZenStack.
  • Покажи, какие миграции применены, а какие ожидают запуска.
  • Считай схему существующей базы и обнови модель ZModel.

Как установить zenstack-db-migration

1Через Skills CLI (Vercel)

npx skills add zenstackhq/skills --skill zenstack-db-migration -a claude-code

2Вручную: положить файлы

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

Папка скилла целиком; для одного проекта — .claude/skills/zenstack-db-migration/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о zenstack-db-migration

Как установить zenstack-db-migration в Claude Code?

Выполни npx skills add zenstackhq/skills --skill zenstack-db-migration -a claude-code. Файл скилла устанавливается по пути ~/.claude/skills/zenstack-db-migration/SKILL.md.

Что делает zenstack-db-migration?

Помогает создавать, применять и проверять миграции ZenStack V3, синхронизировать схему с базой и загружать модель из существующей базы. Также описывает подготовку миграций для deployment pipeline.

Что нужно для работы zenstack-db-migration?

Нужен настроенный проект ZenStack. CLI @zenstackhq/cli использует prisma как peer dependency и устанавливает её автоматически, когда это нужно.

Исходный текст

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

Похожие скиллы

Все скиллы по теме «DevOps и инфраструктура» →
migration JuliusBrussee Скилл migration задаёт правила безопасных миграций схем, данных и API с обязательным откатом. Пригодится при изменениях, где нельзя терять данные или ломать совместимость. CX Codex +1 127 700установок database-migration Seth Hobson Скилл database-migration помогает менять схемы и переносить данные через Sequelize, TypeORM и Prisma. Подходит для миграций без остановки приложения и продуманного отката. CX Codex +1 17 549установок d1-migration jezweb Скилл d1-migration для Claude Code ведёт по миграциям Cloudflare D1 через Drizzle ORM: генерирует и проверяет SQL, применяет миграции и исправляет зависшие. CX Codex +1 1 200установок databricks-serverless-migration databricks Скилл databricks-serverless-migration переводит ноутбуки, джобы и пайплайны Databricks с классических кластеров на serverless compute. Проверяет совместимость кода и даёт готовые исправления. CX Codex +1 701установок migration-architect Alireza Rezvani Скилл migration-architect для Claude Code планирует миграции баз данных, сервисов и инфраструктуры с проверкой совместимости и сценариями отката. CX Codex +1 632установок database-migration-management aj-geddes Скилл database-migration-management помогает планировать миграции схем, откаты изменений и трансформацию данных в PostgreSQL и MySQL. Пригодится при версионировании таблиц и создании индексов без блокировок. CX Codex +1 505установок

Из того же набора9

zenstack-access-control Скилл zenstack-access-control для Claude Code помогает задавать правила доступа в схеме ZenStack V3. Подключается при работе с @@allow, @@deny, auth() и проверками после обновления. CX Codex +1 556установок zenstack-crud-server Скилл zenstack-crud-server для Claude Code превращает модели ZenStack V3 в REST- или RPC CRUD API. Подключается при создании серверных маршрутов, настройке доступа к данным или вызове API из клиента. CX Codex +1 548установок zenstack-plugin-dev Скилл zenstack-plugin-dev для Claude Code помогает создавать плагины ZenStack V3. Включается при работе с ZModel, генерацией кода через CLI или расширением ORM-клиента. CX Codex +1 521установок zenstack-migrate-from-prisma Скилл zenstack-migrate-from-prisma для Claude Code переносит проект с Prisma на ZenStack V3. Он помогает заменить схему, клиент и команды миграции, сохранив рабочие вызовы ORM. CX Codex +1 520установок zenstack-migrate-from-v2 Скилл zenstack-migrate-from-v2 для Claude Code переводит проект ZenStack с V2 на V3. Помогает обновить схему, политики доступа, серверные адаптеры и клиентские хуки. CX Codex +1 515установок zenstack-project-setup Скилл zenstack-project-setup для Claude Code настраивает проекты ZenStack V3: устанавливает зависимости, создаёт каркас и запускает команды zen. Активируется при установке ZenStack, создании проекта или работе с CLI. CX Codex +1 510установок zenstack-querying Скилл zenstack-querying для Claude Code помогает работать с данными через клиент ZenStack V3. Он включается при создании запросов, изменении записей и настройке выборок со связями. CX Codex +1 494установок zenstack-schema-modeling Скилл zenstack-schema-modeling для Claude Code помогает создавать и менять схемы данных ZModel для ZenStack V3. Запускается при работе с моделями, полями, связями, перечислениями и типизированными JSON-полями. CX Codex +1 470установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой