mcpField
Z
zenstack-db-migration

zenstack-db-migration

github.com/zenstackhqデータ・データベース3457 回インストール2 日前に更新
リポジトリ

zenstack-db-migration について

Prisma Migrateを基盤とする`zen`コマンドラインで、データベースをZModelのスキーマに同期するZenStack V3向けスキルです。開発時の試行、履歴管理付きマイグレーション、デプロイ、状態確認、データベースのイントロスペクションを扱います。

主な機能

  1. 01`zen db push`によるスキーマ変更の試行
  2. 02履歴管理付きマイグレーションの作成と適用
  3. 03未適用マイグレーションのデプロイ
  4. 04マイグレーション状態の確認と履歴の修正
  5. 05`zen db pull`によるデータベースの調査

活用シーン

  1. 01開発中のスキーマ反復
  2. 02レビュー可能なSQLマイグレーションの記録
  3. 03CIや本番デプロイでのマイグレーション適用
  4. 04既存データベースへのZenStack導入

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/zenstackhq/skills --skill zenstack-db-migration

インストール後、Claude Code で/zenstack-db-migrationを入力して読み込まれたか確認します。

詳細

ZenStack V3 — データベースのマイグレーション

ZenStack は、データベースのスキーマを ZModel のデータモデルと同期させます。マイグレーションは Prisma Migrate を基盤としており、zen CLI は内部で ZModel から Prisma スキーマを生成し、対応する Prisma コマンドをラップします。Prisma Migrate を使ったことがあれば、ワークフローは同じです。prisma を zen に置き換えるだけです。既存のマイグレーション履歴は、ZenStack のレイアウト（prisma/migrations → zenstack/migrations、デフォルトの場所は zenstack/schema.zmodel と同じ階層）に移動すれば、引き続き機能します。

このスキルは、プロジェクトがすでにセットアップされていることを前提としています（zenstack-project-setup を参照）。スキーマの作成については zenstack-schema-modeling を参照してください。@zenstackhq/cli は prisma へのピア依存関係を持ち、必要に応じて自動的にインストールされます。

スキーマを変更した後は zen generate を実行して生成型を更新してください。マイグレーションコマンドは、生成されたクライアントとは独立してスキーマを操作します。

スキーマを変更する 2 つの方法

アプローチコマンドタイミング
スキーマのプロトタイピングzen db pushローカル開発／試行 — マイグレーションファイルを作成せずにデータベースをスキーマと同期します。高速ですが、履歴は失われます。本番環境では絶対に使用しないでください。
追跡可能なマイグレーションzen migrate dev → zen migrate deployリリースするものすべて — レビュー可能でコミット済みの SQL マイグレーションファイルを生成し、環境間で一貫して適用します。

一般的な流れ：変更を繰り返す間は db push でプロトタイピングし、スキーマの形が固まったら migrate dev でマイグレーションを作成します。

コマンド

すべてのマイグレーション／データベースコマンドは --schema <file>（デフォルトは zenstack/schema.zmodel）と --migrations <path>（migrations/ を含むディレクトリ）を受け付けます。

zen migrate dev — マイグレーションの作成と適用（開発環境）

スキーマとマイグレーション履歴を比較し、新しいタイムスタンプ付きマイグレーションファイルを生成して、 開発用データベースに適用します。完全なリセットが必要な場合（ドリフトなど）は確認を求めます。

zen migrate dev --name add_published_flag
  • -n, --name <name> — マイグレーションに名前を付けます（指定しない場合は入力を求められます）。
  • --create-only — 適用せずにマイグレーションファイルを生成します。SQL を手動で編集する場合や、 マイグレーションエンジンがまだ生成できない機能（データベースビューなど）を実装する場合に使用します。空のマイグレーションを作成して SQL を手動で記述し、後で zen migrate dev で適用します。

ソース管理にコミットする前に、生成された SQL を確認してください。

zen migrate deploy — 未適用のマイグレーションを適用（本番環境）

未適用のマイグレーションをすべて適用します。冪等で、対話的な操作はありません。デプロイパイプラインで使用するコマンドです。 新しいマイグレーションの生成やデータのリセットは行いません。

zen migrate deploy
zen migrate status — マイグレーションの状態を確認

適用済みと未適用のマイグレーションを表示します。デプロイ前の CI で役立ちます。

zen migrate status
zen migrate resolve — スキーマに触れずに履歴を修正

手動での復旧（マイグレーションがコマンド外で適用された場合や、失敗した場合など）のために、マイグレーションを適用済みまたはロールバック済みとして記録します。データベーススキーマは変更しません。

zen migrate resolve --applied 20240101120000_add_users
zen migrate resolve --rolled-back 20240101120000_add_users
zen migrate reset — 初期化して再適用（開発環境）

すべてのテーブルを削除し、すべてのマイグレーションを最初から再実行します。破壊的な操作です。開発／テスト環境専用で、本番環境では絶対に使用しないでください。

zen migrate reset --force   # --force skips the confirmation prompt

シードスクリプトが設定されている場合は、リセット後に実行されます（スキップするには --skip-seed を使用します）。

zen db push — マイグレーションファイルを作成せずにスキーマを同期（開発環境）

スキーマをデータベースに直接プッシュします。迅速なプロトタイピングに最適ですが、履歴は記録されません。

zen db push
zen db push --accept-data-loss   # proceed despite data-loss warnings
zen db push --force-reset        # reset the DB before pushing
zen db pull — 既存のデータベースをイントロスペクションする（v3.4.0+、実験的機能）

データベーススキーマを読み込み、ZModel と比較して、ZModel を一致するように更新します。既存の DB に ZenStack を導入する場合や、データベースに外部から変更を加えた後の再同期に便利です。独自の実装を使用しており、Prisma のイントロスペクションエンジンは使用しません。

zen db pull

オプション：-o, --output <path>、--model-casing <pascal|camel|snake|none>（デフォルトは pascal）、--field-casing <...>（デフォルトは camel）、--always-map（常に @map／@@map を出力）、--quote <double|single>（デフォルトは single）、--indent <number>（デフォルトは 4）。

警告： zen db pull はスキーマファイルを上書きする可能性があります。先にコミットするか、バックアップを作成してください。

zen db seed — データベースにシードデータを投入する

package.json の zenstack.seed で宣言されたシードスクリプトを実行します。

{ "zenstack": { "seed": "tsx ./zenstack/seed.ts" } }

zen db seed
zen db seed -- --users 10   # args after -- are forwarded to the seed script

ワークフロー

開発

  1. zenstack/schema.zmodel を編集します。
  2. 反復作業中にすぐ試すには、zen db push を実行します（必要に応じて zen db seed も実行します）。
  3. スキーマの形が確定したら、zen migrate dev --name <change> を実行してマイグレーションを作成します。
  4. SQL を確認し、マイグレーションファイルをコミットします。

本番環境／CI へのデプロイ

zen migrate deploy

リリースパイプラインで実行します。必要に応じて、先に zen migrate status で確認します。本番環境に対して db push、migrate dev、migrate reset を実行してはいけません。

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

zen init → データソースの url を設定 → zen db pull → スキーマを調整（ポリシー、計算フィールド）→ zen generate。zenstack-project-setup を参照してください。

Prisma からの移行

マイグレーションは Prisma Migrate をラップしているため、既存のマイグレーション履歴は、prisma/migrations ディレクトリを zenstack/migrations（ZenStack のデフォルトの場所で、zenstack/schema.zmodel と同じ階層）に移し、prisma migrate ...／prisma db ... スクリプトを zen の同等コマンドに置き換えれば、そのまま使用できます。フレームワーク全体の移行については、zenstack-migrate-from-prisma で説明しています。

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

このトピックに関する ZenStack のドキュメント一式は references/ にあります。

  • migration.md — マイグレーションの概念とワークフロー
  • introspection.md — zen db pull によるイントロスペクション
  • cli-reference.md — migrate／db コマンドとオプションの完全なリファレンス

コメント

Markdown 対応