Alembic in Practice: Structure, Revisions, and the Traps SQLite Sets
What those hex filenames mean, why migrations silently applied to the wrong database for two months, and how to widen a CHECK constraint without quietly breaking it. Alembic is the migration tool for SQLAlchemy. Most tutorials get you as far as alembic revision --autogenerate and stop, which leaves you unprepared for the two things that actually go wrong: SQLite's refusal to alter constraints,…
Alembic is the migration tool for SQLAlchemy. Most tutorials only cover alembic revision --autogenerate, leaving users unprepared for two common issues: SQLite's refusal to alter constraints and configuration pointing migrations at a different database than the application uses. This post covers both using the FinOps Sentinel example, which had four migrations, one of which took three attempts to get right.
Alembic uses hex filenames to represent revision IDs, generated by alembic revision. The filename combines the revision ID and a message slugified into Python format. Inside each file, there are two important fields: revision and down_revision, forming a linked list. This design prevents filename-based conflicts and makes branch detection possible.
The source of truth for the database URL is config.py, which is used by both the application and Alembic. In FinOps Sentinel, both the application and Alembic initially built the URL independently, leading to a configuration trap that caused two months of silent issues. The fix was to create a single source of truth for the database URL, ensuring consistency between the application and Alembic.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — it may contain errors, so check the original before relying on it.
