zenstack-project-setup

ZenStack V3 — プロジェクトのセットアップとマイグレーション

ZenStack V3 は、Kysely 上に構築された、Prisma 互換の ORM API を備えた TypeScript データベースツールキットです（Rust/WASM は使用しません）。スキーマは、Prisma スキーマ言語のスーパーセットである ZModel（.zmodel）で記述します。このスキルでは、インストール、プロジェクトのスキャフォールディング、CLI、マイグレーションについて説明します。スキーマ構文については zenstack-schema-modeling、クエリについては zenstack-querying、アクセス制御については zenstack-access-control を参照してください。

何か不自然に感じた場合は、正確なパッケージバージョンとコマンドを、最新のドキュメント（ https://zenstack.dev/docs）で必ず確認してください。V3 は急速に進化しています。

前提条件

• Node.js v20+
• TypeScript v5.8.0+
• VSCode 拡張機能：「ZenStack V3」（言語 ID zmodel-v3）。V2 の拡張機能とは別です。

インストール

新しいプロジェクトをスキャフォールディングする（推奨）

npm create zenstack my-project

既存のプロジェクトに ZenStack を初期化する

npx @zenstackhq/cli zen init

次に zenstack/schema.zmodel を作成し、zen generate を実行します。

手動でインストールする

npm install @zenstackhq/schema @zenstackhq/orm
npm install --save-dev @zenstackhq/cli

ZenStack にはデータベースドライバーがバンドルされていません。自分でインストールしてください。

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

アクセス制御が必要な場合に限り、npm install @zenstackhq/plugin-policy を追加してください（zenstack-access-control を参照）。

プロジェクト構成

• スキーマ：zenstack/schema.zmodel（デフォルト。--schema で変更できます）。
• 生成される出力：スキーマと同じ場所に出力されます（--output で変更できます）。import { schema } from './zenstack/schema' としてインポートします。
• 生成された TypeScript はコミットすることも、.gitignore に追加して CI で zen generate を実行することもできます。

zen CLI

CLI は zen（または同等の zenstack）として呼び出します。package.json にスクリプトを追加してください。

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

コマンド	用途
zen check	schema.zmodel の構文エラーと意味上のエラーのみを検証します。再生成は行いません。スキーマが有効かどうかだけを確認したい場合に使用します。
zen generate	schema.zmodel を TypeScript にコンパイルします（データベースクライアントを再生成します）。コンパイル時にスキーマも検証します。クライアントを使用する前に、スキーマを変更するたびに実行してください。フラグ：--schema <path>、--output <path>。
zen db push	マイグレーションファイルを作成せずに、スキーマを DB に反映します。開発・テスト専用です。本番環境では使用しないでください。
zen db pull	既存の DB をイントロスペクトし、ZModel スキーマを更新します（v3.4.0 以降、実験的機能）。スキーマが上書きされる場合があるため、事前にバックアップするか、ソース管理を使用してください。
zen migrate dev	スキーマの変更からマイグレーションを作成し、適用します（開発専用）。--create-only を指定すると、手動で編集するための空のマイグレーションを作成します（ビューなど）。
zen migrate deploy	保留中のマイグレーションをすべて適用します。本番環境へのデプロイパイプラインで使用してください。
zen migrate reset	すべてのテーブルを削除し、マイグレーションを再適用します。開発・テスト専用です。
zen migrate status	適用済みと保留中のマイグレーションを表示します。
zen migrate resolve	スキーマを変更せずに、マイグレーションを適用済みまたはロールバック済みとして記録します（手動での復旧）。

マイグレーションコマンドは Prisma Migrate をラップしています。@zenstackhq/cli は prisma に対するピア依存関係を持ち、必要に応じて自動的にインストールされます。

マイグレーションの詳細（migrate dev／deploy／reset／status／resolve、db push／pull、シード、--create-only、デプロイパイプラインのガイダンス）については、zenstack-db-migration スキルを参照してください。

ワークフロー

開発ループ

1. zenstack/schema.zmodel を編集します。
2. zen generate（型を再生成します）。
3. 移行ファイルを作成せずにローカルで変更を試すには zen db push を実行します。レビューやコミットが可能な移行ファイルを作成するには、zen migrate dev を実行します。
4. 移行 SQL を確認してから、コミットします。

本番環境へのデプロイ

zen migrate deploy

既存のデータベースで ZenStack を導入する

1. zen init
2. zenstack/schema.zmodel でデータソースの url を設定します。
3. zen db pull を実行し、DB からスキーマを生成します。
4. スキーマを調整します（アクセス ポリシーや計算フィールドなどを追加します）。
5. zen generate を実行します。

Prisma からの移行

専用の zenstack-migrate-from-prisma スキルをご覧ください。依存関係の置き換え、schema.prisma の ZModel への変換、PrismaClient の ZenStackClient への置き換え、generate／migrate スクリプトの更新、Prisma カスタムジェネレーターとクライアント拡張機能の対応付けについて説明しています。

ZenStack V2 からの移行

専用の zenstack-migrate-from-v2 スキルをご覧ください。パッケージ名の変更、アクセス制御のポリシープラグインへの移行、future() から post-update／before() への変更、抽象モデルから型とミックスインへの移行、サーバーアダプターの getPrisma から getClient への変更、クライアント側フックの移行について説明しています。

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

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

• prerequisite.md — サポート対象の Node／TypeScript バージョン、IDE のセットアップ
• quick-start.md — スキャフォールディングとインストール方法
• cli.md — zen CLI コマンドの概要
• cli-reference.md — CLI の完全なリファレンス
• migration.md — 開発／本番環境の移行ワークフロー
• introspection.md — 既存のデータベースから zen db pull を実行する方法