This directory contains SQL migration files for database schema changes. The migration system uses SHA256 checksums to ensure migration immutability and consistency across environments.

Migration File Naming

Format: NNN_description.sql

NNN: Sequential number (e.g., 001, 002, 003)
description: Brief description in snake_case

Example: 017_add_gemini_tier_id.sql

Migration File Structure

-- +goose Up
-- +goose StatementBegin
-- Your forward migration SQL here
-- +goose StatementEnd

-- +goose Down
-- +goose StatementBegin
-- Your rollback migration SQL here
-- +goose StatementEnd

Important Rules

⚠️ Immutability Principle

Once a migration is applied to ANY environment (dev, staging, production), it MUST NOT be modified.

Why?

Each migration has a SHA256 checksum stored in the schema_migrations table
Modifying an applied migration causes checksum mismatch errors
Different environments would have inconsistent database states
Breaks audit trail and reproducibility

✅ Correct Workflow

Create new migration

# Create new file with next sequential number
touch migrations/018_your_change.sql

Write Up and Down migrations
- Up: Apply the change
- Down: Revert the change (should be symmetric with Up)

Test locally

# Apply migration
make migrate-up

# Test rollback
make migrate-down

Commit and deploy

git add migrations/018_your_change.sql
git commit -m "feat(db): add your change"

❌ What NOT to Do

❌ Modify an already-applied migration file
❌ Delete migration files
❌ Change migration file names
❌ Reorder migration numbers

🔧 If You Accidentally Modified an Applied Migration

Error message:

migration 017_add_gemini_tier_id.sql checksum mismatch (db=abc123... file=def456...)

Solution:

# 1. Find the original version
git log --oneline -- migrations/017_add_gemini_tier_id.sql

# 2. Revert to the commit when it was first applied
git checkout <commit-hash> -- migrations/017_add_gemini_tier_id.sql

# 3. Create a NEW migration for your changes
touch migrations/018_your_new_change.sql

Migration System Details

Checksum Algorithm: SHA256 of trimmed file content
Tracking Table: schema_migrations (filename, checksum, applied_at)
Runner: internal/repository/migrations_runner.go
Auto-run: Migrations run automatically on service startup

Best Practices

Keep migrations small and focused
- One logical change per migration
- Easier to review and rollback
Write reversible migrations
- Always provide a working Down migration
- Test rollback before committing
Use transactions
- Wrap DDL statements in transactions when possible
- Ensures atomicity
Add comments
- Explain WHY the change is needed
- Document any special considerations
Test in development first
- Apply migration locally
- Verify data integrity
- Test rollback

Example Migration

-- +goose Up
-- +goose StatementBegin
-- Add tier_id field to Gemini OAuth accounts for quota tracking
UPDATE accounts
SET credentials = jsonb_set(
    credentials,
    '{tier_id}',
    '"LEGACY"',
    true
)
WHERE platform = 'gemini'
  AND type = 'oauth'
  AND credentials->>'tier_id' IS NULL;
-- +goose StatementEnd

-- +goose Down
-- +goose StatementBegin
-- Remove tier_id field
UPDATE accounts
SET credentials = credentials - 'tier_id'
WHERE platform = 'gemini'
  AND type = 'oauth'
  AND credentials->>'tier_id' = 'LEGACY';
-- +goose StatementEnd

Troubleshooting

Checksum Mismatch

See "If You Accidentally Modified an Applied Migration" above.

Migration Failed

# Check migration status
psql -d sub2api -c "SELECT * FROM schema_migrations ORDER BY applied_at DESC;"

# Manually rollback if needed (use with caution)
# Better to fix the migration and create a new one

Need to Skip a Migration (Emergency Only)

-- DANGEROUS: Only use in development or with extreme caution
INSERT INTO schema_migrations (filename, checksum, applied_at)
VALUES ('NNN_migration.sql', 'calculated_checksum', NOW());

References

Migration runner: internal/repository/migrations_runner.go
Goose syntax: https://github.com/pressly/goose
PostgreSQL docs: https://www.postgresql.org/docs/