zenstack-migrate-from-v2 — Claude Code skill for migration
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.
MIT 515 installs ★ 3 updated 2026-10-28
npx skills add zenstackhq/skills --skill zenstack-migrate-from-v2 -a claude-codeWhat zenstack-migrate-from-v2 does
The skill guides a ZenStack V2-to-V3 migration, starting with the general Prisma transition before covering ZenStack-specific changes. It maps the package updates, moves access control into a policy plugin, and explains how V2 future() rules become post-update rules that use before().
It also covers replacing abstract models with types and mixins, switching server adapters from getPrisma to getClient, and regrouping TanStack Query hooks under a client that mirrors the ORM. Run zen generate, typecheck the project, and exercise its tests after the upgrade. SWR support was dropped in V3.
What it helps with
- upgrade ZenStack packages from V2 to V3
- move access rules into the policy plugin
- rewrite post-update policies and abstract models
- update server adapters and TanStack Query hooks
Example prompts for the agent
- Help me migrate this ZenStack project from V2 to V3.
- Update the access rules that use
future()for ZenStack V3. - Migrate this project's server adapter and TanStack Query hooks to the ZenStack V3 API.
How to install zenstack-migrate-from-v2
1Skills CLI (Vercel)
npx skills add zenstackhq/skills --skill zenstack-migrate-from-v2 -a claude-code2Manually: put the files in place
~/.claude/skills/zenstack-migrate-from-v2/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/zenstack-migrate-from-v2/
1Skills CLI (Vercel)
npx skills add zenstackhq/skills --skill zenstack-migrate-from-v2 -a codex2Manually: put the files in place
.agents/skills/zenstack-migrate-from-v2/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add zenstackhq/skills --skill zenstack-migrate-from-v2 -a cursor2Manually: put the files in place
.cursor/skills/zenstack-migrate-from-v2/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install zenstackhq/skills skills/zenstack-migrate-from-v22Manually: put the files in place
.github/skills/zenstack-migrate-from-v2/SKILL.md1Skills CLI (Vercel)
npx skills add zenstackhq/skills --skill zenstack-migrate-from-v2 -a gemini-cli2Platform CLI
gemini skills install https://github.com/zenstackhq/skills --path skills/zenstack-migrate-from-v2Manually: put the files in place
.devin/skills/zenstack-migrate-from-v2/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add zenstackhq/skills --skill zenstack-migrate-from-v2 -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-migrate-from-v2
How do I install zenstack-migrate-from-v2 in Claude Code?
Run npx skills add zenstackhq/skills --skill zenstack-migrate-from-v2 -a claude-code. The skill file is installed at ~/.claude/skills/zenstack-migrate-from-v2/SKILL.md.
What does zenstack-migrate-from-v2 do?
It guides updates to a ZenStack project moving from V2 to V3, including package changes, access policies, schema patterns, server adapters, and client hooks.
Does ZenStack V3 support SWR?
No. SWR support was removed in V3; the skill describes the TanStack Query hook migration.
Source text
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