zenstack-migrate-from-prisma

Prisma から ZenStack V3 への移行

ZenStack V3 は Prisma からのスムーズなアップグレードパスとして設計されており、Prisma 互換のクエリ API と、Prisma スキーマのスーパーセットであるスキーマ言語（ZModel）を備えています。ほとんどのアプリでは機械的な変更だけで移行でき、クエリを書き換える必要はありません。対応データベース：PostgreSQL、MySQL、SQLite。

一般的なセットアップ／CLI の詳細については zenstack-project-setup、クライアント／ダイアレクトについては zenstack-querying、スキーマ構文については zenstack-schema-modeling を参照してください。

概要

Prisma	ZenStack V3
prisma、@prisma/client	@zenstackhq/cli（開発用）、@zenstackhq/schema、@zenstackhq/orm
schema.prisma	zenstack/schema.zmodel（Prisma スキーマは有効な ZModel です）
prisma generate	zen generate
prisma db push / migrate dev / migrate deploy	zen db push / zen migrate dev / zen migrate deploy
new PrismaClient()	new ZenStackClient(schema, { dialect })
バンドルされた DB エンジン	DB ドライバーをインストールします（pg / mysql2 / better-sqlite3）

ステップ 1 — 依存関係を入れ替える

npm uninstall prisma @prisma/client
npm install @zenstackhq/schema @zenstackhq/orm
npm install --save-dev @zenstackhq/cli

ZenStack には DB エンジンがバンドルされていないため、使用するデータベースのドライバーをインストールしてください。

データベース	インストール
PostgreSQL	npm install pg + npm install -D @types/pg
MySQL	npm install mysql2
SQLite	npm install better-sqlite3 + npm install -D @types/better-sqlite3

@zenstackhq/cli は prisma に対するピア依存関係があります。マイグレーションコマンドで必要な場合は自動的にインストールされます （ZenStack のマイグレーションコマンドは Prisma Migrate をラップしています）。

ステップ 2 — スキーマを移動して名前を変更する

schema.prisma → zenstack/schema.zmodel に移動します。編集は不要です — 有効な Prisma スキーマはすべて有効な ZModel です。任意で整理する場合：

• generator client { ... } ブロックを削除します（ZenStack では効果がありません — コード生成は zen generate によって実行されます）。
• datasource ブロックはそのまま残します。url はマイグレーションエンジンで使用されます（ORM ランタイムは ドライバー／ダイアレクトから接続情報を取得します）。
• Prisma の複数ファイル／複数スキーマ機能を使用していた場合は、ZModel の import 文を使ってファイルを統合します。

次に進む前に、zen check を実行して、変換後のスキーマが有効であること（構文とセマンティクス）を確認してください。

移動後は、Prisma にない ZenStack 専用機能を追加できます — アクセスポリシー （zenstack-access-control）、@@delegate によるポリモーフィズム、型付き JSON、ミックスイン、計算フィールド （zenstack-schema-modeling）。

ステップ 3 — 生成スクリプトを更新する

{ "scripts": { "generate": "zen generate" } }

スキーマを変更するたびに、クライアントを使用する前に zen generate を実行してください。

ステップ 4 — クライアントを置き換える

new PrismaClient() を new ZenStackClient(schema, { dialect }) に置き換え、使用するドライバー向けの Kysely ダイアレクトを指定します（すべてのダイアレクトについては zenstack-querying を参照してください）。PostgreSQL の例：

import { ZenStackClient } from '@zenstackhq/orm';
import { PostgresDialect } from '@zenstackhq/orm/dialects/postgres';
import { schema } from './zenstack/schema';
import { Pool } from 'pg';

export const db = new ZenStackClient(schema, {
    dialect: new PostgresDialect({
        pool: new Pool({ connectionString: process.env.DATABASE_URL }),
    }),
});

既存の findMany／create／update などの呼び出しはそのまま動作します — ORM API は Prisma と互換性があります。

ステップ 5 — 型参照を更新する

• モデル型（例：User）— 生成された models からインポートします。
• 入力／引数の型（例：UserCreateArgs）— 生成された input からインポートします。

ほとんどのコードでは型が推論されるため、明示的なインポートは不要です。

ステップ 6 — マイグレーションスクリプトを更新する

{
  "scripts": {
    "db:push": "zen db push",
    "migrate:dev": "zen migrate dev",
    "migrate:deploy": "zen migrate deploy"
  }
}

既存のマイグレーション履歴を prisma/migrations から zenstack/migrations に移動します（ZenStack のデフォルトの場所で、zenstack/schema.zmodel と同じ場所です）。ZenStack のマイグレーションは Prisma Migrate をラップしているため、変更せずに引き続き動作します。マイグレーションのワークフロー全体については、zenstack-db-migration スキルを参照してください。

特殊なケース — Prisma カスタムジェネレーター

schema.prisma を読み込む Prisma カスタムジェネレーター（例：zod、ERD、型ジェネレーター）に依存している場合は、@core/prisma プラグインを使って引き続き出力し、コマンドを連結してください。

plugin prisma {
    provider = '@core/prisma'
    output = './schema.prisma'
}

{ "scripts": { "generate": "zen generate && prisma generate --schema=zenstack/schema.prisma" } }

Prisma Client 拡張機能の対応表

Prisma 拡張機能	ZenStack での対応
Query 拡張機能（呼び出しをインターセプト）	onQuery フックを備えた db.$use(...) によるランタイムプラグイン
Result 拡張機能（計算フィールド）	ZModel の @computed フィールドと、ZenStackClient の computedFields オプション（zenstack-schema-modeling を参照）

移行後

次の手順で確認します：zen generate → 型チェック → テストスイート／アプリの実行。その後、ZenStack の付加価値機能（アクセス制御、クエリビルダーのエスケープハッチ、zenstack-crud-server による自動 CRUD API）を段階的に導入します。

すでに ZenStack V2 をお使いですか？ まずはこちらから始めてください（V2 は Prisma ベースです）。その後、zenstack-project-setup の V2→V3 の変更点（パッケージ名の変更、ポリシープラグイン、post-update／before()、型とミックスイン、グループ化されたフック）を適用します。

リファレンスドキュメント

このトピックに関する ZenStack のドキュメント全文は references/ に含まれています。

• migrate-prisma.md — 公式の「Prisma からの移行」ガイド