Migrations

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:

cd my-api
alembic init alembic

Edit alembic.ini to set your database URL:

sqlalchemy.url = postgresql://postgres:test@localhost/postgres

Edit alembic/env.py to point at BackAnt’s Base:

from startup.Alchemy import Base
target_metadata = Base.metadata

Also ensure all models are imported before Base.metadata is referenced:

import models.Users_model
import models.Orders_model
# ... all your models

Generating a migration

After changing a model (e.g. adding a phone column to Users), generate a migration:

alembic revision --autogenerate -m "add phone to users"

Alembic compares your SQLAlchemy models against the current database schema and generates an upgrade() / downgrade() script in alembic/versions/.

Applying migrations

alembic upgrade head

Rolling back

alembic downgrade -1   # one step back
alembic downgrade base  # all the way 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:

CLEAR_DB=True

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

CLI Reference

Architecture

The Basics

Security

Database

External APIs

How tables are created

When you need Alembic

Setting up Alembic

Generating a migration

Applying migrations

Rolling back

CLEAR_DB in development

Migration checklist