BackAnt includes Alembic (alembic~=1.12.0) in requirements.txt for database migrations.
How tables are created
In development, BackAnt takes a code-first approach: Base.metadata.create_all(engine) in init_db() creates any tables that don’t yet exist on every startup.
This means for new routes, you don’t need a migration — just run docker-compose up --build and the table is created automatically.
When you need Alembic
Alembic is needed when you make changes to existing tables — adding columns, renaming columns, changing types, adding indexes. create_all() does not modify tables that already exist.
Setting up Alembic
Initialize Alembic from the project root:
Edit alembic.ini to set your database URL:
Edit alembic/env.py to point at BackAnt’s Base:
Also ensure all models are imported before Base.metadata is referenced:
Generating a migration
After changing a model (e.g. adding a phone column to Users), generate a migration:
Alembic compares your SQLAlchemy models against the current database schema and generates an upgrade() / downgrade() script in alembic/versions/.
Applying migrations
Rolling back
CLEAR_DB in development
For rapid iteration during development, CLEAR_DB=True in your .env drops all tables and recreates them from scratch on every restart. This is faster than running Alembic but destroys all data:
Never use CLEAR_DB=True in production. Always use Alembic migrations for production schema changes.
Migration checklist
- Modify the SQLAlchemy model in
api/models/
- Run
alembic revision --autogenerate -m "description"
- Review the generated migration in
alembic/versions/
- Run
alembic upgrade head
- Rebuild your Docker image for deployment
