Alembic Migrations: A Django Comparison

1. Why We Need Schema Migrations

First, let's briefly formalize the concept. As an application evolves, so does its data model. We might need to add a tags table, add a last_updated column to an existing table, or change a column from nullable to non-nullable. These changes to the database structure are called schema migrations.

Doing this manually is error-prone. A migration tool like Alembic provides a structured, version-controlled way to apply and revert these changes. Think of it like Git for your database schema.

2. Setting Up the Alembic Environment

The first step is to initialize an Alembic "environment" in our project. This is a one-time setup that creates the necessary configuration files and directories.

Analogy to Django: This is similar to the migrations/ directory that Django automatically creates inside an app when you first run makemigrations. With Alembic, we do it explicitly with an init command.

Let's watch a video that walks through the entire setup process, from installing Alembic to initializing the environment and configuring the database connection.

After following the video, your project should have a structure that includes:

• alembic.ini: The main configuration file. This is where you set the database URL.
• migrations/ (or a similar name you chose): The environment directory.
  • env.py: A Python script that is run every time you use the alembic command. We'll configure this next.
  • versions/: This directory will hold all your migration scripts, just like Django's migrations folder.
  • script.py.mako: A template file for generating new migration scripts. You rarely need to touch this.

3. Configuring Alembic for Autogeneration

Out of the box, Alembic doesn't know about your SQLAlchemy models. To enable autogenerate—Alembic's equivalent of Django's model change detection—we must tell it where to find them.

This is a key difference from Django, which automatically discovers models from your INSTALLED_APPS. Alembic requires an explicit configuration step in the env.py file.

The goal is to point Alembic's target_metadata to your declarative Base.metadata.

The video you just watched continues to explain exactly how to do this.

A More Modern Configuration Approach

The method above works perfectly fine. However, in modern Python projects, it's common to manage settings using Pydantic and environment variables, rather than hardcoding values in .ini files.

The following video demonstrates a more advanced setup that aligns with this practice. It configures env.py to:

1. Read the database URL from a Pydantic settings object (which in turn reads from environment variables).
2. Programmatically set the configuration for Alembic, overriding what's in alembic.ini.

You don't have to switch to this method right now, but it's an excellent pattern to be aware of for professional projects.

4. The Migration Workflow: Alembic vs. Django

Now for the main event. Let's compare the commands you know from Django with their Alembic counterparts. The workflow is conceptually identical.

This table is your Rosetta Stone for migrations. Let's break down the key commands.

Generating a Migration (revision)

The alembic revision --autogenerate -m "..." command is the equivalent of makemigrations.

• --autogenerate: Tells Alembic to inspect your models (via target_metadata) and compare them to the current state of the database, generating the changes.
• -m "...": A required short message describing the migration, similar to a Git commit message.

When you run this, Alembic creates a new file in your versions/ directory. It contains an upgrade() function to apply the changes and a downgrade() function to revert them.

Applying and Reverting Migrations (upgrade/downgrade)

• alembic upgrade head: This is the direct equivalent of migrate. It applies all unapplied migrations until the database schema matches the latest revision (head).
• alembic downgrade -1: This reverts the most recent migration by running the downgrade() function from that migration script. You can use -2 to revert two steps, and so on.

The articles below reinforce this comparison perfectly.

5. Practical Example: Evolving Our Note Model

Let's walk through a practical scenario.

Step 1: Create the Initial Migration

Assuming your database is currently empty but your Note model is defined in models.py, let's create the first migration. In your terminal, run:

alembic revision --autogenerate -m "Create initial note table"

Inspect the new file created in your migrations/versions/ directory. You should see op.create_table(...) inside the upgrade() function and op.drop_table(...) in downgrade().

Now, apply it:

alembic upgrade head

Your notes table now exists in the database! Alembic also created a table named alembic_version to track which migrations have been applied.

Step 2: Add a New Field

Now, let's modify your models.py file. Add a new field to the Note model:

# models.py
import datetime
from sqlalchemy import String, Text, DateTime, func
from sqlalchemy.orm import Mapped, mapped_column
from .database import Base

class Note(Base):
    __tablename__ = "notes"

    id: Mapped[int] = mapped_column(primary_key=True)
    title: Mapped[str] = mapped_column(String(100), index=True)
    content: Mapped[str] = mapped_column(Text, nullable=True)
    created_at: Mapped[datetime.datetime] = mapped_column(
        DateTime(timezone=True), server_default=func.now()
    )



    # New field added below!
    is_archived: Mapped[bool] = mapped_column(default=False, server_default='false')

Step 3: Generate the New Migration

With the model updated, run the revision command again:

alembic revision --autogenerate -m "Add is_archived field to Note model"

Check the new migration file. This time, it should contain op.add_column(...) and op.drop_column(...). Alembic correctly detected the change.

Step 4: Apply the New Migration

Finally, bring the database up to date:

alembic upgrade head

Your notes table in the database now has an is_archived column. This workflow allows you to safely and incrementally evolve your database schema as your application grows.

Conclusion

In this lesson, we demystified database migrations in the FastAPI ecosystem. You've seen that while the specific commands are different, the underlying principles and workflow are nearly identical to what you already know from Django.

Key Takeaways:

• Alembic is the standard migration tool for SQLAlchemy.
• The workflow starts with alembic init to create the environment.
• You must configure env.py to point to your model metadata (target_metadata = Base.metadata) to enable autogenerate.
• The core workflow is a two-step process:
  1. alembic revision --autogenerate -m "..." to create a migration script (like makemigrations).
  2. alembic upgrade head to apply it to the database (like migrate).
• Reverting changes is done with alembic downgrade.

Preview of the Next Lesson:

Now that we can manage our database schema, we're ready to explore one of FastAPI's most powerful and defining features: the Dependency Injection system. In the next lesson, we'll explain what it is, how it works, and how it helps you write cleaner, more modular, and more testable code—contrasting it with Django's middleware and DRF's permission patterns.