mcpField
S
serverpod-migrations

serverpod-migrations

github.com/serverpodデータ・データベース3.3k43 回インストール1 日前に更新
リポジトリ

serverpod-migrations について

serverpod-migrationsは、Serverpodのデータベース移行の作成、適用、修復を支援するスキルです。移行が必要なスキーマ変更と、生成された移行ファイルを安全に扱う方法を説明します。

主な機能

  1. 01移行が必要なスキーマ変更の判定
  2. 02Serverpod MCPでの移行作成と適用
  3. 03MCPが使えない場合のコマンドライン利用
  4. 04修復移行の作成と適用
  5. 05移行SQLの安全な編集方法の説明

活用シーン

  1. 01テーブルモデルやインデックスの変更の移行
  2. 02不整合が生じたデータベーススキーマの修復
  3. 03移行へのデータ変換処理の追加

MCP 対応

serverpod startの実行中にserverpod MCPが利用できる場合、create_migration、apply_migrations、修復移行ツールを使うよう案内します。MCPサーバーに接続できない場合は、コマンドラインを代替手段として示します。

インストール

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

$npx skills add https://github.com/serverpod/serverpod --skill serverpod-migrations

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

詳細

Serverpod のマイグレーション

Serverpod には、.spy.yaml で table が指定されたモデルの変更に対する SQL を生成するマイグレーションシステムがあります。マイグレーションは次の場合に適用されます。

  • serverpod MCP 経由で apply_migrations ツールが呼び出されたとき。通常は、開発中に serverpod start を実行している場合です。
  • dart run bin/main.dart --apply-migrations フラグを付けてサーバーを起動したとき。通常は、本番環境でサーバーを実行する場合です。

マイグレーションが必要な場合

  • .spy.yaml の table モデルまたはフィールドを追加、削除、名前変更した場合。
  • 生成される外部キーに影響するリレーションフィールドを変更した場合。
  • インデックスを追加、削除、変更した場合。

プロジェクトにデータベースが設定されていない場合（例：config/<runMode>.yaml に database セクションがない場合）、マイグレーションは必要ありません。

標準的な手順

serverpod start を実行している場合、マイグレーションの作成と適用は簡単になります。

serverpod start と MCP サーバーを実行している場合

serverpod start でサーバーを実行している場合は、serverpod MCP を使用して次の操作を行います。

  1. create_migration ツールを使用してマイグレーションを作成します。
  2. apply_migrations ツールを使用してマイグレーションを適用します。

MCP サーバーが利用可能な場合は、必ず使用してください。

MCP サーバーへの接続に失敗した場合のみ

serverpod start でサーバーを実行していない場合は、CLI コマンドを使用して次の操作を行います。

  1. serverpod generate を実行して、コードが生成されていることを確認します。
  2. serverpod create-migration コマンドを使用してマイグレーションを作成します。

生成されたマイグレーションの編集

マイグレーションディレクトリには、migration.sql、definition.sql、および definition.json、definition_project.json、migration.json ファイルが含まれます。

作成後に migration.sql を手動で編集してもかまいません。よくある理由は次の 2 つです。

  • データ変換を追加して、スキーマとともに既存の行も移行するため。
  • 中間手順を経て同じ最終状態にすることで、破壊的な変更を非破壊的な変更にするため。たとえば、列を削除して作り直す代わりに、新しい列を追加し、古い列のデータを埋め戻してから、古い列を削除します。

ディレクトリ内のその他のファイルは編集しないでください。definition.sql は完全なスキーマであり、*.json ファイルは次回の serverpod create-migration で差分を取るために使用されるため、これらを変更すると、その後に作成されるすべてのマイグレーションが破損します。

マイグレーションの適用方法から、次の 2 つのルールが導かれます。

  • マイグレーションがインストールされていないデータベースは、最新の definition.sql のみから作成され、migration.sql は実行されません。既存のデータベースには、新しい migration.sql が順番に適用されます。そのため、編集した migration.sql の適用後のスキーマは definition.sql と同一でなければならず、その中のデータ変換が影響するのは、そのバージョンを経由してアップグレードするデータベースのみです。
  • すでに適用されたマイグレーションを編集しても、そのマイグレーションを適用済みのデータベースには反映されません。そのようなデータベースには、新しいマイグレーションを作成してください。

クライアント側（database: client または database: all が指定されたモデル）では、バージョンの migration.dart 内にあるマイグレーション SQL にも同じことが当てはまります。定義 SQL と JSON ファイルも同様に編集してはいけません。

修復マイグレーション

データベースが不整合な状態にある場合、修復マイグレーションによって整合性のある状態に戻します。ライブスキーマを読み取り、対象のマイグレーションバージョンと比較して差分を取ることで作成するため、データベースに接続できる必要があります。

serverpod start と MCP サーバーを実行している場合
  1. create_repair_migration ツールを使用して修復マイグレーションを作成します。省略可能な引数は version（対象のマイグレーションバージョン。既定値は最新）、tag、force（破壊的な変更がある場合、またはドリフトが検出されない場合に必要）です。
  2. apply_migrations ツールを使用して適用します。このツールは、サーバーを再起動せずに、保留中のマイグレーションと修復マイグレーションの両方を適用します。

MCP サーバーが利用可能な場合は、必ず使用してください。

MCP サーバーへの接続に失敗した場合のみ
# Use the `--mode` flag to specify the run mode
# Use the `--version` flag to specify the target version
# Use the `--force` flag to create a migration with destructive changes
# Use the `--tag` flag to name the migration
serverpod create-repair-migration [--mode production] [--version <name>] [--force] [--tag <tag>]

dart run bin/main.dart --apply-repair-migration を実行してサーバーを再起動し、修復マイグレーションを適用します。このコマンドを実行するようユーザーに依頼してください。

コメント

Markdown 対応