go-goose

go-goose

CLI または Go ライブラリを使ってデータベースマイグレーションを作成、実行するための pressly/goose の専門ガイダンスです。

トリガーするタイミング

• ユーザーが goose、pressly/goose、Go でのデータベースマイグレーションに言及した場合、または SQL／Go マイグレーションの実行方法を尋ねた場合。
• タスクに goose を使ったマイグレーションの埋め込み、Provider API の使用、CI ワークフローが含まれる場合。

基本ルール

• まず、リポジトリに既存のマイグレーションの配置、方言、命名規則に従ってください。
• データベースドライバーと goose の方言が一致していることを確認してください（例：postgres ドライバーには postgres 方言）。
• スキーマ変更には SQL マイグレーションを優先し、複雑なデータのバックフィルやコード駆動の手順には Go マイグレーションを使用してください。
• goose のルールに従い、マイグレーションを決定的かつ冪等にしてください（Up は 1 つ、Down は任意）。

ワークフロー

1. コンテキストを確認する：対象の DB／方言、ドライバー、マイグレーションディレクトリ、SQL と Go のどちらのマイグレーションが必要か、実行したいコマンド（create／up／down／status など）を確認します。
2. インターフェースを選ぶ：
   • CLI：その場での実行や CI/CD に使用します。
   • ライブラリ／Provider：Go サービスやテスト内でマイグレーションを実行する場合に使用します。
3. マイグレーションを作成する：
   • SQL：goose のアノテーションとステートメントのルールを使用します（references/sql-annotations.md を参照）。
   • Go：init でマイグレーションを登録し、カスタムバイナリまたは Provider に組み込みます（references/go-migrations.md を参照）。
4. マイグレーションを実行する：
   • CLI の使い方、コマンド、環境変数は references/cli.md を参照してください。
   • ライブラリ／Provider のパターンは references/library.md を参照してください。
5. バージョン管理と順序：
   • 開発時はハイブリッドバージョニングを使用し、本番環境での順序付けが必要な場合は fix を使用します（references/versioning.md を参照）。

出力に関する期待事項

• ユーザーの方言と環境に合った、正確なコマンドまたはコードスニペットを提示してください。
• ロールバックが必要なのに Down マイグレーションがない場合は警告してください。
• 特別な解析や非トランザクション実行が必要なマイグレーションの場合は、その旨を明示してください。

参考資料

• CLI の使い方と環境変数：references/cli.md
• SQL アノテーションと解析ルール：references/sql-annotations.md
• Go マイグレーションの登録パターン：references/go-migrations.md
• ライブラリと Provider API の使い方：references/library.md
• バージョン管理と順序：references/versioning.md