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

zenstack-migrate-from-v2 — скилл для Claude Code: миграция

Скилл zenstack-migrate-from-v2 для Claude Code переводит проект ZenStack с V2 на V3. Помогает обновить схему, политики доступа, серверные адаптеры и клиентские хуки.

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

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

Что делает 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-code

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

~/.claude/skills/zenstack-migrate-from-v2/SKILL.md

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

По шагам, с командами для каждой платформы: Как установить скилл в 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

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

Все скиллы по теме «Бэкенд и API» →
agent-platform-migrate-from-ai-studio официальный google Скилл agent-platform-migrate-from-ai-studio для Claude Code, Gemini CLI и Codex, который ведёт агента через миграцию приложения с Gemini API в Google AI Studio на Agent Platform (бывший Vertex AI). CX Codex +1 7 934установок pulumi-migrate-from-discovered-stack pulumi Скилл pulumi-migrate-from-discovered-stack переносит CloudFormation- и ARM-стеки, обнаруженные Pulumi Cloud через Discovery и видимые в discovered-stacks API, под управление Pulumi. CX Codex +1 219установок migrate-from-react-router TanStack Скилл migrate-from-react-router для Claude Code ведёт по шагам переезда с React Router v7 на TanStack Router: от конвертации маршрутов до навигации и search-параметров. CX Codex +1 188установок nemo-relay-migrate-from-flow NVIDIA Corporation and Affiliates Скилл nemo-relay-migrate-from-flow для механической миграции кода, документации и конфигов с NeMo Flow на NeMo Relay. Работает с Python, Rust, Node.js, Go, C FFI, CLI и параметрами наблюдаемости. CX Codex +1 171установок migrate-from-legacy haabe Скилл migrate-from-legacy для Claude Code переводит проект Mycelium с legacy-установки на плагинную форму, сохраняя состояние проекта. CX Codex +1 ★ 54звёзд репо prisma-cli prisma Скилл prisma-cli для Claude Code даёт справочник по Prisma ORM 7: миграции, генерация клиента и безопасная работа с базой без случайного сброса данных. CX Codex +1 438 300установок

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

zenstack-access-control Скилл zenstack-access-control для Claude Code помогает задавать правила доступа в схеме ZenStack V3. Подключается при работе с @@allow, @@deny, auth() и проверками после обновления. CX Codex +1 556установок zenstack-db-migration Скилл zenstack-db-migration для Claude Code управляет миграциями схемы базы данных в ZenStack V3. Вызывается при создании и применении миграций, синхронизации схемы или работе с существующей базой. CX Codex +1 551установок 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-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установок

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

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