nonobie — Real dev skills, explained like a friend would

What you'll learn

By the end of this chapter you will:

Initialize Alembic against an existing SQLAlchemy metadata
Autogenerate and hand-edit migration scripts safely
Run upgrades/downgrades locally and in deployment
Handle the classic failure modes: drift, branches, and data migrations

The why

Schema changes are inevitable. The only question is whether they are controlled.

Without migration discipline, teams end up with:

environments that do not match production,
manual edits with no audit trail,
rollbacks that fail under pressure,
and broken deploys because app code expects columns that do not exist.

Alembic gives you a versioned schema timeline that can be reviewed, tested, and executed in .

Migration quality is backend reliability quality.

Core concepts: Safe schema evolution

Revision graph mental model

Each migration file is a node with:

revision id,
down_revision pointer,
upgrade() operations,
downgrade() operations.

Together these files a directed graph from old schema states to current .

Initialize and bind metadata

bash

alembic init migrations

In migrations/env.py, point Alembic at your model metadata:

python

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

Set database URL from environment or settings module for consistency across local and CI runs.

Autogenerate then review

bash

alembic revision --autogenerate -m "add users email unique constraint"

Autogenerate is a draft, not a guarantee. Review for:

missing indexes,
unintended drops/renames,
constraint names,
and data safety implications.

Upgrade and downgrade workflow

bash

alembic upgrade head
alembic downgrade -1
alembic current
alembic history --verbose

Practice downgrades locally before claiming rollback readiness in production.

Schema migrations vs data migrations

Schema migration changes structure: tables, columns, indexes, constraints.

Data migration changes contents: backfills, passes, value transformations.

Example migration pattern:

python

from alembic import op
import sqlalchemy as sa
 
 
def upgrade() -> None:
    op.add_column("users", sa.Column("is_active", sa.Boolean(), server_default=sa.true(), nullable=

For large backfills, prefer operational scripts or chunked jobs over giant transactional migration steps.

Branch conflicts and merge revisions

If two heads exist, create merge revision:

bash

alembic heads
alembic merge -m "merge feature heads" <head_a> <head_b>

Never edit already-applied migrations in shared environments. Add a corrective migration instead.

Deployment discipline

Treat migration scripts like production code. Review them, test them, and run them with the same rigor as application releases.

Migration decision table

Scenario	Better move	Why
New nullable column	Add column first, then app write/read rollout	Minimizes deployment coupling
Large backfill needed	Incremental backfill job	Avoids long lock windows
Rename column	Add new column + dual-write + backfill + remove old later	Safer than hard rename in one step
Parallel branch migrations	Merge revision	Keeps migration graph linearized for deploy
Emergency rollback	Revert app + run tested downgrade path if safe	Controlled recovery sequence

Common mistakes

Mistake	Why it hurts	Better move
Blind trust in autogenerate	Missed constraints and risky operations	Review generated SQL intent manually
Editing old applied migration files	Environment divergence and audit breakage	Create a new corrective migration
Mixing heavy data backfill in schema step	Long-running locks and timeout risk	Separate data migration execution
No downgrade testing	False rollback confidence	Test downgrade path in staging/local
Manual production SQL outside Alembic	Untracked drift	Version every schema change

Production notes

Run migrations in deployment pipeline before flipping new app code paths.
Observe lock duration and long-running migration metrics.
Backup strategy and restore drills are part of migration reliability.
For zero-downtime systems, plan expand-contract schema changes.

Practice: Prove your Mastery

beginner Challenge

4 min

Alembic bootstrap

Initialize Alembic and wire target metadata from your models package.

Input— given data

data

Existing SQLAlchemy Base metadata

Expected Output— your code should produce this

expected

Working alembic revision generation

Write your solutionCtrl+Enter to run

Ctrl+Enter

beginner Challenge

5 min

First generated migration

Add a new table and generate migration draft.

Input— given data

data

New SQLAlchemy model

Expected Output— your code should produce this

expected

Revision with create_table op

Write your solutionCtrl+Enter to run

Ctrl+Enter

intermediate Challenge

6 min

Backward-compatible column rollout

Add a non-null column to a table with existing rows safely.

Input— given data

data

Production table with data

Expected Output— your code should produce this

expected

No write outage during deploy

Write your solutionCtrl+Enter to run

Ctrl+Enter

intermediate Challenge

6 min

Dual-head merge

Resolve two migration heads produced by parallel feature branches.

Input— given data

data

Two revision head ids

Expected Output— your code should produce this

expected

Single merged migration path

Write your solutionCtrl+Enter to run

Ctrl+Enter

intermediate Challenge

7 min

Rollback rehearsal

Practice upgrade then downgrade for a risky schema change.

Input— given data

data

Staging database snapshot

Expected Output— your code should produce this

expected

Measured rollback confidence and caveats

Write your solutionCtrl+Enter to run

Ctrl+Enter

Interview Questions

Beginner:

"Why are migrations necessary if models already define schema?"

Models define desired shape; migrations define versioned, executable transitions across real environments.
"What does alembic revision --autogenerate actually do?"

It compares model metadata to database state and drafts migration operations that you must review.

Senior:

"How do you design zero-downtime schema migrations for large tables?"

Use expand-contract sequencing, avoid long locks, and separate backfills from structural changes.
"What is your policy on editing applied migration files?"

Never edit applied revisions in shared environments; issue a corrective migration to preserve history integrity.

Summary

Alembic gives controlled, auditable schema evolution.
Autogenerate accelerates drafting but does not replace review.
Upgrade and downgrade workflows must be tested, not assumed.
Migration quality directly impacts deployment safety and incident recovery.

Quick recall

text

Model change -> autogenerate draft -> review -> migrate -> verify
Schema migration != data migration
Never rewrite applied migrations
Practice rollback before production needs it

Self-Check Quiz

Q1 / 3

MCQ

What is the best interpretation of alembic revision --autogenerate output?

Chapter 6 — Alembic Migrations

The why

Core concepts: Safe schema evolution

Revision graph mental model

Initialize and bind metadata

Autogenerate then review

Upgrade and downgrade workflow

Schema migrations vs data migrations

Branch conflicts and merge revisions

Migration decision table

Common mistakes

Production notes

Practice: Prove your Mastery

Alembic bootstrap

First generated migration

Backward-compatible column rollout

Dual-head merge

Rollback rehearsal

Interview Questions

Summary

Quick recall

Self-Check Quiz