# How to Integrate Alembic for Database Migrations in FastAPI Boilerplate

> Integrate Alembic for database migrations in FastAPI boilerplate. Learn how to generate and apply changes easily using standard Alembic CLI commands with this pre-configured setup.

- Repository: [Benav Labs/fastapi-boilerplate](https://github.com/benavlabs/fastapi-boilerplate)
- Tags: how-to-guide
- Published: 2026-02-26

---

**The fastapi-boilerplate repository provides a pre-configured Alembic setup in `src/migrations/` that connects to the existing SQLAlchemy engine in [`src/app/core/db/database.py`](https://github.com/benavlabs/fastapi-boilerplate/blob/main/src/app/core/db/database.py), allowing you to generate and apply database migrations using standard Alembic CLI commands.**

The fastapi-boilerplate repository by benavlabs implements a clean, modular architecture that separates database concerns into distinct packages. Integrating Alembic for database migrations ensures your schema evolves safely alongside your SQLAlchemy models defined in `src/app/models/`. This guide walks through connecting Alembic to the existing database configuration, generating migration scripts, and automating schema updates.

## Configure the Alembic Environment

Alembic’s configuration lives in **[`src/migrations/env.py`](https://github.com/benavlabs/fastapi-boilerplate/blob/main/src/migrations/env.py)**. This file must import the existing SQLAlchemy engine so that Alembic knows which database to target, and it must reference the metadata object containing all model definitions.

First, import the application’s database engine and base metadata:

```python

# src/migrations/env.py

from logging.config import fileConfig
from sqlalchemy import engine_from_config, pool
from alembic import context

# Import the app's SQLAlchemy engine

from src.app.core.db.database import engine

# Import the Base metadata

from src.app.core.db.models import Base
target_metadata = Base.metadata

```

**Why this works:** The boilerplate already creates the engine in [`src/app/core/db/database.py`](https://github.com/benavlabs/fastapi-boilerplate/blob/main/src/app/core/db/database.py). Re-using it avoids duplicate connection settings. `Base.metadata` aggregates every model declared in `src/app/models/`, ensuring Alembic can autogenerate migrations for all tables.

## Generate Migration Scripts

Whenever you add or modify an ORM model (for example, adding a column to [`src/app/models/user.py`](https://github.com/benavlabs/fastapi-boilerplate/blob/main/src/app/models/user.py)), generate a migration script using the autogenerate command:

```bash
alembic revision --autogenerate -m "Add email_verified to User"

```

This command reads `target_metadata` from [`env.py`](https://github.com/benavlabs/fastapi-boilerplate/blob/main/env.py), compares it to the current database schema, and writes a new revision file under **`src/migrations/versions/`**.

## Apply and Roll Back Migrations

Run the migration scripts against the configured database to move the schema forward:

```bash
alembic upgrade head

```

The `head` alias points to the latest revision. To roll back the most recent migration:

```bash
alembic downgrade -1

```

## Automate Migrations on Startup (Optional)

You can ensure migrations run automatically when the FastAPI application starts by adding a startup hook in **[`src/app/main.py`](https://github.com/benavlabs/fastapi-boilerplate/blob/main/src/app/main.py)**:

```python

# src/app/main.py

from pathlib import Path
from alembic import command
from alembic.config import Config
from fastapi import FastAPI

app = FastAPI()

def run_migrations() -> None:
    alembic_cfg = Config(str(Path(__file__).parent.parent / "migrations" / "alembic.ini"))
    command.upgrade(alembic_cfg, "head")

@app.on_event("startup")
def on_startup() -> None:
    run_migrations()

```

Because the boilerplate configures the SQLAlchemy engine in [`src/app/core/db/database.py`](https://github.com/benavlabs/fastapi-boilerplate/blob/main/src/app/core/db/database.py), the migration run shares the same connection details defined in your environment.

## Keep Configuration Synchronized

If you change the database URL (for example, switching from SQLite to PostgreSQL), update **[`src/migrations/alembic.ini`](https://github.com/benavlabs/fastapi-boilerplate/blob/main/src/migrations/alembic.ini)**. The `sqlalchemy.url` entry should reference the same environment variable that [`database.py`](https://github.com/benavlabs/fastapi-boilerplate/blob/main/database.py) uses (`DATABASE_URL`).

## Complete Working Example

Here is an end-to-end example of adding a new `Post` model to the database:

**Step 1:** Define the model in [`src/app/models/post.py`](https://github.com/benavlabs/fastapi-boilerplate/blob/main/src/app/models/post.py):

```python

# src/app/models/post.py

from sqlalchemy import Column, Integer, String, ForeignKey
from src.app.core.db.models import Base

class Post(Base):
    __tablename__ = "posts"

    id = Column(Integer, primary_key=True, index=True)
    title = Column(String, nullable=False)
    content = Column(String, nullable=False)
    author_id = Column(Integer, ForeignKey("users.id"))

```

**Step 2:** Generate the migration:

```bash
alembic revision --autogenerate -m "Create posts table"

```

**Step 3:** Apply the migration:

```bash
alembic upgrade head

```

## Summary

- The fastapi-boilerplate ships with a pre-populated **`src/migrations/`** directory, so you can skip the `alembic init` step.
- Configure **[`src/migrations/env.py`](https://github.com/benavlabs/fastapi-boilerplate/blob/main/src/migrations/env.py)** to import `engine` from [`src/app/core/db/database.py`](https://github.com/benavlabs/fastapi-boilerplate/blob/main/src/app/core/db/database.py) and `Base.metadata` from [`src/app/core/db/models.py`](https://github.com/benavlabs/fastapi-boilerplate/blob/main/src/app/core/db/models.py).
- Use **`alembic revision --autogenerate`** to create migration scripts based on model changes in `src/app/models/`.
- Apply changes with **`alembic upgrade head`** and roll back with **`alembic downgrade -1`**.
- Optionally trigger migrations automatically using **`@app.on_event("startup")`** in [`src/app/main.py`](https://github.com/benavlabs/fastapi-boilerplate/blob/main/src/app/main.py).

## Frequently Asked Questions

### How do I connect Alembic to an existing database in the boilerplate?

Import the existing SQLAlchemy engine from [`src/app/core/db/database.py`](https://github.com/benavlabs/fastapi-boilerplate/blob/main/src/app/core/db/database.py) and the `Base` metadata from [`src/app/core/db/models.py`](https://github.com/benavlabs/fastapi-boilerplate/blob/main/src/app/core/db/models.py) inside [`src/migrations/env.py`](https://github.com/benavlabs/fastapi-boilerplate/blob/main/src/migrations/env.py). Set `target_metadata = Base.metadata` so Alembic can read all model definitions and compare them against the current database schema.

### Where are the migration files stored in this project?

Migration scripts are stored in **`src/migrations/versions/`**. The [`env.py`](https://github.com/benavlabs/fastapi-boilerplate/blob/main/env.py) file in `src/migrations/` handles the runtime configuration, while [`alembic.ini`](https://github.com/benavlabs/fastapi-boilerplate/blob/main/alembic.ini) contains the main configuration settings including the database URL.

### Can I run migrations automatically when the app starts?

Yes. Import `alembic.command` and `alembic.config.Config` in [`src/app/main.py`](https://github.com/benavlabs/fastapi-boilerplate/blob/main/src/app/main.py), then create a function that loads [`src/migrations/alembic.ini`](https://github.com/benavlabs/fastapi-boilerplate/blob/main/src/migrations/alembic.ini) and runs `command.upgrade(alembic_cfg, "head")`. Attach this function to the FastAPI startup event using `@app.on_event("startup")`.

### What should I do if I change the database URL environment variable?

Update the `sqlalchemy.url` value in **[`src/migrations/alembic.ini`](https://github.com/benavlabs/fastapi-boilerplate/blob/main/src/migrations/alembic.ini)** to match the new connection string. Ensure it references the same `DATABASE_URL` environment variable used by [`src/app/core/db/database.py`](https://github.com/benavlabs/fastapi-boilerplate/blob/main/src/app/core/db/database.py) to keep the application and migration tool synchronized.