zenstack-migrate-from-v2 — скилл для Claude Code: миграция
Скилл zenstack-migrate-from-v2 для Claude Code переводит проект ZenStack с V2 на V3. Помогает обновить схему, политики доступа, серверные адаптеры и клиентские хуки.
MIT 515 установок ★ 3 обновлён 2026-10-28
npx skills add zenstackhq/skills --skill zenstack-migrate-from-v2 -a claude-codeЧто делает zenstack-migrate-from-v2
Скилл проводит миграцию проекта ZenStack с V2 на V3: сначала предлагает выполнить общий переход с Prisma, затем разбирает изменения ZenStack. Он помогает заменить пакеты, перенести контроль доступа в плагин политик и обновить правила future() до post-update с before().
Дальше скилл объясняет замену абстрактных моделей на типы с миксинами, переход адаптеров с getPrisma на getClient и перенос TanStack Query-хуков к клиенту, который отражает ORM. Для проверки миграции нужно выполнить zen generate, проверку типов и тесты приложения. Поддержка SWR в V3 прекращена.
Какие задачи решает
- перевести пакеты ZenStack с V2 на V3
- перенести правила доступа на плагин политик
- обновить post-update-политики и модели
- заменить серверные адаптеры и хуки TanStack Query
Примеры запросов агенту
- Помоги мигрировать мой проект ZenStack с V2 на V3.
- Обнови правила доступа с
future()для ZenStack V3. - Переведи серверный адаптер и хуки TanStack Query проекта на API ZenStack V3.
Как установить zenstack-migrate-from-v2
1Через Skills CLI (Vercel)
npx skills add zenstackhq/skills --skill zenstack-migrate-from-v2 -a claude-code2Вручную: положить файлы
~/.claude/skills/zenstack-migrate-from-v2/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/zenstack-migrate-from-v2/
1Через Skills CLI (Vercel)
npx skills add zenstackhq/skills --skill zenstack-migrate-from-v2 -a codex2Вручную: положить файлы
.agents/skills/zenstack-migrate-from-v2/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add zenstackhq/skills --skill zenstack-migrate-from-v2 -a cursor2Вручную: положить файлы
.cursor/skills/zenstack-migrate-from-v2/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install zenstackhq/skills skills/zenstack-migrate-from-v22Вручную: положить файлы
.github/skills/zenstack-migrate-from-v2/SKILL.md1Через Skills CLI (Vercel)
npx skills add zenstackhq/skills --skill zenstack-migrate-from-v2 -a gemini-cli2Командой платформы
gemini skills install https://github.com/zenstackhq/skills --path skills/zenstack-migrate-from-v2Вручную: положить файлы
.devin/skills/zenstack-migrate-from-v2/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add zenstackhq/skills --skill zenstack-migrate-from-v2 -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы о zenstack-migrate-from-v2
Как установить zenstack-migrate-from-v2 в Claude Code?
Выполните npx skills add zenstackhq/skills --skill zenstack-migrate-from-v2 -a claude-code. Файл скилла появится по пути ~/.claude/skills/zenstack-migrate-from-v2/SKILL.md.
Что делает zenstack-migrate-from-v2?
Скилл помогает перенести ZenStack-проект с V2 на V3: обновить пакеты и схему, перенести контроль доступа в плагин, а также изменить серверные адаптеры и клиентские хуки.
Поддерживает ли ZenStack V3 SWR?
Нет, поддержка SWR в V3 прекращена. В разделе о клиентских хуках скилл описывает переход на TanStack Query.
Исходный текст
SKILL.md · MIT
---
name: zenstack-migrate-from-v2
description: Upgrade an existing ZenStack V2 project to V3. Use when renaming V2 packages (zenstack, @zenstackhq/runtime), moving access control to the policy plugin, converting future() to post-update/before(), replacing abstract models with types+mixins, updating server adapters (getPrisma → getClient), and migrating client-side TanStack Query hooks.
---
# Migrating from ZenStack V2 to V3
ZenStack V3 is a major rewrite: the Prisma ORM engine is replaced with ZenStack's own engine built
on [Kysely](https://kysely.dev), while the ZModel schema stays largely compatible and the query API
stays PrismaClient-compatible. Supported databases: **PostgreSQL, MySQL, SQLite**.
Because V2 was Prisma-based, the migration has two layers: the generic Prisma→ZenStack changes, then
the V2-specific deltas below. For general setup/CLI see `zenstack-project-setup`.
## Step 1 — Do the Prisma migration first
V2 ran on Prisma, so start with the **`zenstack-migrate-from-prisma`** skill (swap deps, move the
schema to `zenstack/schema.zmodel`, replace the client with `ZenStackClient`, update generate/migrate
scripts). Then apply the V2-specific steps below.
## Step 2 — Rename ZenStack packages
```bash
npm uninstall zenstack @zenstackhq/runtime
npm install @zenstackhq/schema @zenstackhq/orm
npm install --save-dev @zenstackhq/cli
```
| V2 | V3 |
| -- | -- |
| `zenstack` (CLI) | `@zenstackhq/cli` |
| `@zenstackhq/runtime` | `@zenstackhq/orm` |
| — | `@zenstackhq/schema` (new) |
The CLI command moves from `zenstack <cmd>` to `zen <cmd>` (e.g. `zen generate`).
## Step 3 — Access control is now a plugin
In V2 access control was built into the runtime (`enhance(prisma)`). In V3 it's an opt-in plugin.
1. Install it: `npm install @zenstackhq/plugin-policy`
2. Declare it in the schema:
```zmodel
plugin policy {
provider = '@zenstackhq/plugin-policy'
}
```
3. Wrap the client and bind the user per request:
```ts
import { ZenStackClient } from '@zenstackhq/orm';
import { PolicyPlugin } from '@zenstackhq/plugin-policy';
export const db = new ZenStackClient(schema, { dialect });
export const authDb = db.$use(new PolicyPlugin()); // was: enhance(prisma, { user })
// per request:
const userDb = authDb.$setAuth(user); // was: passing { user } to enhance()
```
See `zenstack-access-control` for the full policy/runtime model.
## Step 4 — Post-update policies: `future()` → `post-update` + `before()`
V2 expressed post-update conditions with `future()` inside an `update` rule. V3 uses a dedicated
`post-update` operation, where bare field references mean the **new** values and `before()` reads the
**old** ones.
```zmodel
// V2
@@deny('update', future().ownerId != ownerId)
// V3
@@deny('post-update', ownerId != before().ownerId)
```
## Step 5 — Abstract models → types + mixins
V2's `abstract model` + `extends` becomes a `type` applied with `with` (see
`zenstack-schema-modeling`).
```zmodel
// V2
abstract model Timestamped {
createdAt DateTime @default(now())
updatedAt DateTime @updatedAt
}
model Post extends Timestamped { title String }
// V3
type Timestamped {
createdAt DateTime @default(now())
updatedAt DateTime @updatedAt
}
model Post with Timestamped { title String }
```
(Note: `extends` still exists in V3, but for **polymorphism** via `@@delegate`, which is a different
feature — don't use it as a plain mixin replacement.)
## Step 6 — Server adapters
V3 requires you to pass an explicit `apiHandler` (`RPCApiHandler` or `RestApiHandler`), and the
client-supplying callback is renamed `getPrisma` → `getClient`:
```ts
// V2
ZenStackMiddleware({ getPrisma: (req) => enhance(prisma, { user: getUser(req) }) });
// V3
ZenStackMiddleware({
apiHandler: new RPCApiHandler({ schema }),
getClient: (req) => authDb.$setAuth(getUser(req)),
});
```
See `zenstack-crud-server` for all frameworks and both API styles.
## Step 7 — Client-side hooks (TanStack Query)
Flat hook names are replaced by hooks grouped under a client that mirrors the ORM:
```ts
// V2
import { useFindManyUser } from '~/hooks';
const { data } = useFindManyUser({ where: { ... } });
// V3
import { useClientQueries } from '@zenstackhq/tanstack-query/react';
import { schema } from '~/zenstack/schema';
const client = useClientQueries(schema);
const { data } = client.user.useFindMany({ where: { ... } });
```
**SWR support was dropped** in V3. See `zenstack-crud-server` for the full TanStack Query setup.
## Step 8 — Other plugin/utility migrations
- **Zod**: now a utility rather than a plugin (see the zod utility docs).
- **OpenAPI**: folded into the automatic CRUD API handlers — generate a spec via
`apiHandler.generateSpec()` (see `zenstack-crud-server`).
- **Custom plugins**: the V3 plugin system is revised; consult the current plugin docs.
## After upgrading
Run `zen generate`, typecheck, and exercise your test suite / app. Confirm access control behaves as
expected now that it's an explicit `$use(new PolicyPlugin())` + `$setAuth()` flow rather than V2's
implicit `enhance()`.
## Reference docs
Full ZenStack documentation for this topic is bundled under [`references/`](references/):
- [migrate-v2.md](references/migrate-v2.md) — official "Migrating from ZenStack v2" guide
© zenstackhq · MIT · zenstackhq/skills