Database Migration Workflow

Workflow for database schema and migration changes.

Prerequisites

• Use git-workflow Skill for branch, commit, and PR workflow.
• Refer to .claude/rules/hcl.md for HCL schema rules (SSOT).
• Refer to .claude/rules/sql.md for SQL query rules (SSOT).

Applicable Files

Path	Description
tools/atlas/schemas/{db_dialect}/*.hcl	HCL schema definitions (source of truth)
tools/sqlc/queries/{db_dialect}/*.sql	SQLC query definitions

Workflow

1. Modify Schema (HCL)

Edit HCL files in tools/atlas/schemas/{db_dialect}/.

Dialect directories:

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

2. Verify HCL (from rules/hcl.md)

make atlas-fmt && make atlas-lint

3. Regenerate All Artifacts

Run all three targets after modifying HCL schemas:

# 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

Each target handles: Atlas migrations → Docker DB reset → SQLC schema extraction → SQLC code generation.

4. Verify Migration Files

After running the regenerate targets, confirm each DB dialect has exactly one migration SQL file:

• tools/atlas/migrations/postgres/{db-name}/*.sql ← one file, updated
• tools/atlas/migrations/mysql/{db-name}/*.sql ← one file, updated

DB names: keygen, sign, watch

5. Verify Go Code

make check-build && make go-test

Self-Review Checklist

• HCL format/lint passes
• make regenerate-all-from-atlas succeeds (postgres)
• make regenerate-all-from-atlas-mysql succeeds (mysql)
• make regenerate-all-from-atlas-sqlite succeeds (sqlite)
• Each tools/atlas/migrations/{postgres,mysql}/{db-name}/ has exactly one .sql file and it is updated
• SQLC generates correctly
• Go build passes

Related

• .claude/rules/hcl.md - HCL rules (SSOT)
• .claude/rules/sql.md - SQL rules (SSOT)
• go-development - Go verification after SQLC generation
• git-workflow - Branch, commit, PR workflow