alembic
Database migration tool for SQLAlchemy — provides versioned schema management with upgrade/downgrade scripts. alembic features: alembic init for project setup, alembic revision --autogenerate to detect schema changes, alembic upgrade head to apply migrations, alembic downgrade to revert, migration scripts with op.create_table/add_column/drop_column/create_index/etc., env.py configuration, programmatic MigrationContext for embedding, branch handling for merge conflicts, offline SQL generation (--sql flag), batch operations for SQLite ALTER TABLE limitations, and compare_type for column type changes.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
Database migration tool. Store database credentials in environment variables not alembic.ini. Review migration scripts before applying — autogenerate can generate DROP TABLE statements. Run migrations in transaction where supported. Test downgrade scripts. Backup before production migrations.
⚡ Reliability
Best When
SQLAlchemy-based projects needing versioned schema migrations — alembic is the standard migration tool for SQLAlchemy, maintained by the same team.
Avoid When
Non-SQLAlchemy projects, NoSQL databases, Django (use Django migrations), or simple SQLite scripts without schema versioning needs.
Use Cases
- • Agent migration setup — alembic init alembic; # Edit alembic.ini: sqlalchemy.url = postgresql://user:pass@localhost/db; # Edit alembic/env.py: target_metadata = Base.metadata; alembic revision --autogenerate -m 'add users table'; alembic upgrade head — setup; agent initializes migration infrastructure for SQLAlchemy project
- • Agent programmatic migration — from alembic.config import Config; from alembic import command; alembic_cfg = Config('alembic.ini'); command.upgrade(alembic_cfg, 'head') — programmatic; agent runs migrations from Python code (e.g., at application startup); command.current() to show current version; command.history() to list revisions
- • Agent manual migration — from alembic import op; import sqlalchemy as sa; def upgrade(): op.add_column('users', sa.Column('last_login', sa.DateTime())); op.create_index('ix_users_email', 'users', ['email'], unique=True) — manual migration; agent writes custom migrations for complex changes that autogenerate cannot detect
- • Agent offline SQL generation — alembic upgrade head --sql > migrations.sql — SQL script; agent generates SQL migration script for review or manual application to production database; --sql flag outputs SQL without connecting to database
- • Agent downgrade — alembic downgrade -1 — single step back; alembic downgrade base — back to empty schema; agent reverts migrations for rollback; each revision has downgrade() function; agent code: generate downgrade before running risky migrations
Not For
- • Non-SQLAlchemy projects — alembic integrates tightly with SQLAlchemy; for Django use Django migrations; for other ORMs use dedicated migration tools
- • NoSQL databases — alembic is SQL-only
- • Auto-migration in production — autogenerate can miss changes; always review generated migration scripts before applying to production
Interface
Authentication
No auth — migration tool. Database credentials via alembic.ini or env.py.
Pricing
Alembic is MIT licensed. Free for all use.
Agent Metadata
Known Gotchas
- ⚠ autogenerate cannot detect everything — alembic --autogenerate misses: server defaults, CHECK constraints, sequence changes, custom types, data migrations; agent code: always review generated migration files before committing; add missed changes manually; run alembic upgrade head on test database to verify
- ⚠ env.py must import all models — autogenerate compares target_metadata to database; target_metadata = Base.metadata requires ALL models imported; missing model import = missing table in metadata = autogenerate drops table; agent code: env.py must import all model modules; common pattern: from myapp.models import * or explicit imports
- ⚠ SQLite ALTER TABLE limitations — SQLite does not support DROP COLUMN or ALTER COLUMN; alembic batch operations work around this: with op.batch_alter_table('table_name') as batch_op: batch_op.add_column(...); batch_op.drop_column(...) — recreates table; agent code for SQLite: always use batch_alter_table for any column modification
- ⚠ Multiple heads cause errors — branched migration history creates multiple heads; alembic upgrade head fails; check: alembic heads; merge: alembic merge -m 'merge' head1 head2; creates merge revision; agent code in team environment: pull before generating revision to avoid branches; merge conflicts in migration files are common
- ⚠ Migration scripts are executed in order — revision IDs reference down_revision for ordering; changing order or deleting revisions breaks history; agent code: never delete or reorder migration files; squash with alembic merge for cleanup; alembic history shows ordered list; downgrade before deleting deployment
- ⚠ compare_type must be enabled for type changes — autogenerate by default ignores column type changes (length, precision); enable: context.configure(compare_type=True) in env.py; then column type changes appear in autogenerate; agent code: enable compare_type=True; still review for false positives (dialect-specific types)
Alternatives
Full Evaluation Report
Comprehensive deep-dive: security analysis, reliability audit, agent experience review, cost modeling, competitive positioning, and improvement roadmap for alembic.
AI-powered analysis · PDF + markdown · Delivered within 30 minutes
Package Brief
Quick verdict, integration guide, cost projections, gotchas with workarounds, and alternatives comparison.
Delivered within 10 minutes
Score Monitoring
Get alerted when this package's AF, security, or reliability scores change significantly. Stay ahead of regressions.
Continuous monitoring
Scores are editorial opinions as of 2026-03-06.