# alembic/versions/2024_01_17_1400_update_fees_status.py
"""update_fees_status_values
Revision ID: jkl012
Revises: ghi789
Create Date: 2024-01-17 14:00:00.000000
"""
from alembic import op
from sqlalchemy import text
def upgrade() -> None:
# 更新现有记录
op.execute(
text("UPDATE fees SET status = 'pending' WHERE status = 'unpaid'")
)
def downgrade() -> None:
# 恢复状态值
op.execute(
text("UPDATE fees SET status = 'unpaid' WHERE status = 'pending'")
)
示例：枚举迁移
def upgrade() -> None:
# 添加新的枚举类型
op.execute("CREATE TYPE fee_status_new AS ENUM ('pending', 'paid', 'overdue', 'waived')")
# 将数据复制到新类型
op.execute("ALTER TABLE fees ALTER COLUMN status TYPE fee_status_new USING status::text::fee_status_new")
# 删除旧类型
op.execute("DROP TYPE fee_status_old")
def downgrade() -> None:
# 反转该过程
op.execute("ALTER TABLE fees ALTER COLUMN status TYPE VARCHAR(20)")
op.execute("DROP TYPE fee_status_new")
# alembic/env.py
from logging.config import fileConfig
from sqlalchemy import pool
from sqlalchemy.engine import Connection
from alembic.runtime.migration import MigrationContext
from sqlmodel import SQLModel, create_engine
from myapp.models import * # Import all SQLModel classes
config = context.config
config.set_main_option("sqlalchemy.url", "postgresql://user:pass@localhost/dbname")
target_metadata = SQLModel.metadata
def run_migrations_offline() -> None:
"""Run migrations in 'offline' mode."""
url = config.get_main_option("sqlalchemy.url")
context.configure(
url=url,
target_metadata=target_metadata,
literal_binds=True,
dialect_opts={"paramstyle": "named"},
)
with context.begin_transaction():
context.run_migrations()
def run_migrations_online() -> None:
"""Run migrations in 'online' mode."""
connectable = create_engine(
config.get_main_option("sqlalchemy.url"),
poolclass=pool.NullPool,
)
with connectable.connect() as connection:
context.configure(
connection=connection,
target_metadata=target_metadata,
)
with context.begin_transaction():
context.run_migrations()
if context.is_offline_mode():
run_migrations_offline()
else:
run_migrations_online()
Generating Migrations
Auto-Generate from Model Changes
# Generate migration automatically based on model diffs
alembic revision --autogenerate -m "add_fees_table"
# With specific revision range
alembic revision --autogenerate -m "add_user_email" --rev-id=abc123
# Upgrade to latest revision
alembic upgrade head
# Upgrade one step at a time
alembic upgrade +1
# Upgrade to specific revision
alembic upgrade abc123
Dry Run (Check What Would Happen)
# Show pending migrations without applying
alembic show heads
alembic history --verbose
Rollback (Downgrade)
# Rollback one migration
alembic downgrade -1
# Rollback to specific revision
alembic downgrade abc123
# Rollback all migrations (empty database)
alembic downgrade base
Safe Downgrade Pattern
def downgrade() -> None:
# Always drop indexes before table
op.drop_index('ix_fees_status', table_name='fees')
op.drop_index('ix_fees_student_id', table_name='fees')
# Drop foreign keys before table
op.drop_constraint('fees_student_id_fkey', 'fees', type_='foreignkey')
op.drop_table('fees')
Data Migrations
Example: Data Migration with Batch Update
# alembic/versions/2024_01_17_1400_update_fees_status.py
"""update_fees_status_values
Revision ID: jkl012
Revises: ghi789
Create Date: 2024-01-17 14:00:00.000000
"""
from alembic import op
from sqlalchemy import text
def upgrade() -> None:
# Update existing records
op.execute(
text("UPDATE fees SET status = 'pending' WHERE status = 'unpaid'")
)
def downgrade() -> None:
# Revert status values
op.execute(
text("UPDATE fees SET status = 'unpaid' WHERE status = 'pending'")
)
Example: Enum Migration
def upgrade() -> None:
# Add new enum type
op.execute("CREATE TYPE fee_status_new AS ENUM ('pending', 'paid', 'overdue', 'waived')")
# Copy data to new type
op.execute("ALTER TABLE fees ALTER COLUMN status TYPE fee_status_new USING status::text::fee_status_new")
# Drop old type
op.execute("DROP TYPE fee_status_old")
def downgrade() -> None:
# Reverse the process
op.execute("ALTER TABLE fees ALTER COLUMN status TYPE VARCHAR(20)")
op.execute("DROP TYPE fee_status_new")
Quality Checklist
Data migrations : Handle existing data when modifying columns/tables
Test migrations : Run alembic upgrade then alembic downgrade in test
Idempotent operations : up() and down() can run multiple times safely
No data loss : Use DROP TABLE IF EXISTS, DROP COLUMN IF EXISTS
Indexes created : Include index creation in upgrade, drop in downgrade
Foreign keys : Handle constraint ordering (create before, drop after)
Backwards compatible : Don't break existing application during migration
Integration with Other Skills
Skill
Integration Point
@sqlmodel-crud
Model changes trigger migrations
@fastapi-app
Migrations run at startup or via CLI
@jwt-auth
May need to handle auth during migrations
Migration Best Practices
1. Always Generate Before Manual Edit
alembic revision --autogenerate -m "describe_change"
# Then review and edit the generated file
2. Review Generated Migrations
# Check that:
# - Column types match SQLModel definitions
# - Foreign key constraints are correct
# - Indexes are appropriate
# - Default values are set
3. Test Migration Cycle
# In test environment
alembic downgrade base
alembic upgrade head
# Verify all data is intact
4. Handle Long-Running Migrations
# For large tables, use batch updates
def upgrade():
op.execute("""
UPDATE fees SET status = 'pending'
WHERE status IS NULL
LIMIT 10000
""")
