Skip to main content
skill CX Codex

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

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

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

2Manually: put the files in place

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

Copy the whole skill folder; for one project use .claude/skills/zenstack-migrate-from-v2/

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

Similar skills

All skills for Backend and APIs →
agent-platform-migrate-from-ai-studio official google agent-platform-migrate-from-ai-studio is a Claude Code skill that guides an agent moving a Gemini app from AI Studio to Agent Platform, covering IAM, authentication, and API activation. CX Codex +1 7,934installs pulumi-migrate-from-discovered-stack pulumi pulumi-migrate-from-discovered-stack — a skill that imports CloudFormation or ARM stacks already discovered by Pulumi Cloud's Discovery feature into Pulumi. Works only with stacks already scanned and visible in the discovered-stacks API. CX Codex +1 219installs migrate-from-react-router TanStack migrate-from-react-router is a Claude Code skill with a step-by-step checklist for moving from React Router v7 to TanStack Router, covering routes, navigation, and search params. CX Codex +1 188installs nemo-relay-migrate-from-flow NVIDIA Corporation and Affiliates nemo-relay-migrate-from-flow — a skill that automates code, documentation, and config migration from NeMo Flow to NeMo Relay. Handles Python, Rust, Node.js, Go, C FFI, CLI, and observability surfaces. CX Codex +1 171installs migrate-from-legacy haabe migrate-from-legacy is a Claude Code skill that moves a Mycelium project from legacy installation to plugin form while preserving project state. CX Codex +1 ★ 54repo stars prisma-cli prisma prisma-cli is a Claude Code skill with a Prisma ORM 7 reference for migrations, client generation, and database workflows that prevent accidental data loss. CX Codex +1 438,300installs

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-db-migration 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. CX Codex +1 551installs 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-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