feat: Add comprehensive database migration tooling

[elmorem]

Summary

• Adds comprehensive database migration management tooling
• Creates Python scripts for migration operations and database initialization
• Provides detailed documentation with examples and best practices
• Updates Makefile with convenient migration commands

What's Included

Migration Management Script

• scripts/db_migrate.py: Unified CLI for all migration operations
  • Create migrations (autogenerate from models or empty)
  • Upgrade/downgrade to any revision
  • Show current revision, history, and heads
  • Stamp database without running migrations
  • Clean, user-friendly interface with help examples

Database Initialization Script

• scripts/db_init.py: Automated database setup
  • Creates database if it doesn't exist
  • Installs required PostgreSQL extensions (uuid-ossp, pgcrypto)
  • Verifies database connectivity
  • Provides clear success/failure messages

Comprehensive Documentation

• docs/DATABASE_MIGRATIONS.md: 600+ line migration guide
  • Quick start instructions
  • Migration creation patterns (autogenerate, empty, data migrations)
  • Common operations (upgrade, downgrade, history)
  • Migration file structure explained
  • Common migration patterns with code examples
  • Production deployment guide with zero-downtime strategies
  • Troubleshooting section
  • Best practices and security considerations

Updated Makefile Commands

• make db-init: Initialize database and extensions
• make db-create MESSAGE="...": Create new migration with autogeneration
• make db-upgrade [REV=...]: Upgrade to latest or specific revision
• make db-downgrade REV=...: Downgrade to specific revision
• make db-current: Show current database revision
• make db-history: Show migration history
• make db-reset: Reset database (downgrade to base, upgrade to head)
• Legacy commands maintained for backward compatibility with deprecation warnings

Usage Examples

Initialize New Database

# Create database and install extensions
make db-init

# Run all migrations
make db-upgrade

Create New Migration

# Autogenerate from model changes
make db-create MESSAGE="add user profile fields"

# Create empty migration for custom logic
python scripts/db_migrate.py create "migrate user data" --no-autogenerate

Upgrade Database

# Upgrade to latest
make db-upgrade

# Upgrade to specific revision
make db-upgrade REV=abc123

View Migration Status

# Show current version
make db-current

# Show migration history
make db-history

# Show verbose history
python scripts/db_migrate.py history --verbose

Rollback Changes

# Downgrade one revision
make db-downgrade REV=-1

# Downgrade to specific revision
make db-downgrade REV=xyz789

Documentation Highlights

The guide includes:

• Quick Start: Get up and running in 3 commands
• Migration Patterns: Examples for columns, indexes, foreign keys, data migrations
• Production Guide: Zero-downtime deployment strategies
• Troubleshooting: Solutions for common issues (multiple heads, failed migrations, etc.)
• Best Practices: Review process, testing, transaction handling, etc.

Scripts Features

db_migrate.py

• Simple CLI with subcommands
• Comprehensive help with examples
• Delegates to Alembic with better UX
• Clear output formatting

db_init.py

• Async database operations
• Checks if database exists before creating
• Installs required extensions automatically
• Verifies connectivity
• Clear success/failure reporting

Test Plan

• db_migrate.py script created with all commands
• db_init.py script created with database initialization
• Scripts made executable (chmod +x)
• Documentation covers all use cases
• Makefile updated with new commands
• Legacy commands maintained with deprecation warnings
• Code formatted with black
• Type checking passed with mypy
• All files committed and pushed

Migration Path

Existing Makefile commands continue to work with deprecation warnings:

• make db-migrate → Use make db-upgrade instead
• make db-revision MSG="..." → Use make db-create MESSAGE="..." instead

This ensures backward compatibility while encouraging adoption of the new, clearer command names.

🤖 Generated with Claude Code