alembic

Alembic Migration Rules

Command Usage

Standard Commands

Use python manage.py or make for all database tasks:

# Create migration
make makemigration m="add foo"
# or
python manage.py makemigration -m "add foo"

# Apply migrations
make migrate
# or
python manage.py migrate

# Reset DB (dev only!)
make reset
# or
python manage.py reset

# Seed DB
make seed
# or
python manage.py seed

Migration Best Practices

Autogenerate Migrations

• Autogenerate always works (all models imported in env.py)
• Review autogenerated migrations before applying
• Never auto-generate without review
• Manual migration review ensures correctness

Database Configuration

• DB URL is always read from app config, not alembic.ini
• Use environment variables for database URLs
• Different URLs for different environments

Migration Management

• Alembic revision every PR - Create migrations for each pull request
• Never auto-generate without review - Always review generated migrations
• Manual migration review ensures correctness

Migration Workflow

1. Make schema changes in SQLAlchemy models
2. Generate migration: python manage.py makemigration -m "description"
3. Review migration file - Check generated SQL
4. Test migration: Apply to development database
5. Commit migration with code changes

Common Patterns

Adding a Column

# Migration file
def upgrade():
    op.add_column('users', sa.Column('email', sa.String(), nullable=True))

def downgrade():
    op.drop_column('users', 'email')

Creating a Table

def upgrade():
    op.create_table(
        'users',
        sa.Column('id', sa.Integer(), nullable=False),
        sa.Column('name', sa.String(), nullable=False),
        sa.PrimaryKeyConstraint('id')
    )

def downgrade():
    op.drop_table('users')

Best Practices

1. Review all migrations before applying
2. Test migrations on development database first
3. Keep migrations small and focused
4. Never edit existing migrations (create new ones)
5. Document migrations with clear descriptions