Alembic
Database migration tool for SQLAlchemy. Generates and applies schema migration scripts to evolve database schema over time. Creates versioned migration files with upgrade/downgrade functions. Detects schema differences between SQLAlchemy models and current database state (autogenerate). The standard migration tool for SQLAlchemy-based Python applications.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
MIT licensed. Database credentials in connection URL — use environment variables, never hardcode. Migration scripts contain schema-sensitive SQL — treat migration files as sensitive code.
⚡ Reliability
Best When
You're using SQLAlchemy for your Python database models and need version-controlled, reversible database schema migrations.
Avoid When
You're using Django (use Django migrations) or a non-SQLAlchemy stack. For simple SQLite scripts, manual migrations may be simpler.
Use Cases
- • Manage database schema evolution in production agent systems with tracked, reversible migrations
- • Autogenerate migration scripts by comparing SQLAlchemy model definitions to current database schema
- • Apply schema migrations as part of agent service deployment pipeline with alembic upgrade head
- • Roll back schema changes in agent development or production with alembic downgrade
- • Maintain migration history for auditing and reproducing exact database schema states
Not For
- • Non-SQLAlchemy ORMs — Alembic is specifically for SQLAlchemy; use Django migrations for Django, Flyway for Java, Prisma migrations for Node.js
- • Data migrations (moving data between columns) — Alembic handles schema changes; complex data migrations require custom op.execute() SQL in migration scripts
- • Non-SQL databases — Alembic is SQL-only
Interface
Authentication
Local CLI tool — no authentication required. MIT licensed. Database authentication configured via connection URL.
Pricing
MIT licensed. Zero cost.
Agent Metadata
Known Gotchas
- ⚠ Autogenerate has limitations — it detects column adds/removes but NOT renames (interpreted as drop+add, losing data); manually write rename migrations using op.alter_column()
- ⚠ alembic.ini contains the database URL — do NOT hardcode in alembic.ini; override in env.py using environment variables: context.configure(url=os.environ['DATABASE_URL'])
- ⚠ Migration files are Python scripts — must be committed to version control; migration file history is the schema audit log
- ⚠ Running migrations in production: always test against a staging database first; migrations that add NOT NULL columns without defaults will fail on existing data
- ⚠ Multiple databases or schemas: use --name option or configure multiple script locations; Alembic supports branch migrations for feature branches
- ⚠ alembic upgrade head runs all pending migrations; alembic upgrade +1 applies exactly one — use +1 for incremental testing, head for deployment
Alternatives
Full Evaluation Report
Detailed scoring breakdown, competitive positioning, security analysis, and improvement recommendations for Alembic.
Scores are editorial opinions as of 2026-03-06.