db-migration

データベースマイグレーションのワークフロー

データベーススキーマとマイグレーションの変更に関するワークフローです。

前提条件

• ブランチ、コミット、PR のワークフローには git-workflow Skill を使用してください。
• HCL スキーマのルール（SSOT）については .claude/rules/hcl.md を参照してください。
• SQL クエリのルール（SSOT）については .claude/rules/sql.md を参照してください。

対象ファイル

パス	説明
tools/atlas/schemas/{db_dialect}/*.hcl	HCL スキーマ定義（信頼できる唯一の情報源）
tools/sqlc/queries/{db_dialect}/*.sql	SQLC クエリ定義

ワークフロー

1. スキーマを変更する（HCL）

tools/atlas/schemas/{db_dialect}/ 内の HCL ファイルを編集します。

方言ごとのディレクトリ：

• tools/atlas/schemas/postgres/*.hcl
• tools/atlas/schemas/mysql/*.hcl

2. HCL を検証する（rules/hcl.md を参照）

make atlas-fmt && make atlas-lint

3. すべての成果物を再生成する

HCL スキーマを変更した後、3 つすべてのターゲットを実行します。

# Regenerate migrations, extract SQLC schemas, and generate Go code for PostgreSQL
make regenerate-all-from-atlas

# Regenerate for MySQL
make regenerate-all-from-atlas-mysql

# Convert PostgreSQL schemas to SQLite and generate Go code for SQLite
make regenerate-all-from-atlas-sqlite

各ターゲットは、Atlas マイグレーション → Docker DB のリセット → SQLC スキーマの抽出 → SQLC コード生成を処理します。

4. マイグレーションファイルを検証する

再生成ターゲットの実行後、各 DB 方言にマイグレーション SQL ファイルがちょうど 1 つあることを確認します。

• tools/atlas/migrations/postgres/{db-name}/*.sql ← ファイル 1 つ、更新済み
• tools/atlas/migrations/mysql/{db-name}/*.sql ← ファイル 1 つ、更新済み

DB 名：keygen、sign、watch

5. Go コードを検証する

make check-build && make go-test

セルフレビューのチェックリスト

• HCL のフォーマット／Lint が通る
• make regenerate-all-from-atlas が成功する（postgres）
• make regenerate-all-from-atlas-mysql が成功する（mysql）
• make regenerate-all-from-atlas-sqlite が成功する（sqlite）
• 各 tools/atlas/migrations/{postgres,mysql}/{db-name}/ に .sql ファイルがちょうど 1 つあり、更新されている
• SQLC が正しくコードを生成する
• Go のビルドが通る

関連項目

• .claude/rules/hcl.md - HCL のルール（SSOT）
• .claude/rules/sql.md - SQL のルール（SSOT）
• go-development - SQLC 生成後の Go の検証
• git-workflow - ブランチ、コミット、PR のワークフロー