Alembic
lastmod 2026-07-14created 2026-04-123 edits
Database Migration Tool
A library used to change and manage database schemas (table structures, etc.) when using SQLAlchemy, Python's leading ORM. It is easiest to think of it as a version control system for databases (a role similar to Git).
Why use Alembic?
- How to use Alembic (python data migrations) :: Magpie's Daily Notes
- Development usually involves creating and using multiple DBs.
- When the Dev and Prod DBs must match for operations, as in the flow below, it is a tool that consolidates the work in Alembic instead of having a person do it manually, so that anyone gets an environment in the same condition.
- It is similar to flyway in the Spring ecosystem. The difference is that flyway records all change information in each table, while alembic records only the hash of the last migrated version.
- Alembic DB migrations make it easy to track what was done in each version using the version hash.
- Migrations usually happen in the cases below. With 10 DB instances, each would have to be repeated 10 times, but with alembic a single change and deployment is enough.
- When moving cloud instances and a DB must be newly created
- A change request for a specific Entity
- When a Table Schema changes
Troubleshooting
ERROR [alembic.util.messaging] Can't locate revision identified by 'XXX'
Reset alembic_version entirely and re-set it with stamp:
The following error occurs:
INFO [alembic.runtime.migration] Context impl PostgresqlImpl.
INFO [alembic.runtime.migration] Will assume transactional DDL.
ERROR [alembic.util.messaging] Can't locate revision identified by 'b9c0d1e2f3a4'
FAILED: Can't locate revision identified by 'b9c0d1e2f3a4'
--purge clears the table without resolving the current value, then records the new revision:
Output:
INFO [alembic.runtime.migration] Context impl PostgresqlImpl.
INFO [alembic.runtime.migration] Will assume transactional DDL.
INFO [alembic.runtime.migration] Running stamp_revision -> a8b9c0d1e2f3