Alembic Migrations in PostgreSQL: Fix Multiple Heads

1. Understanding Alembic and Migration Heads

Alembic keeps track of database structure changes using versioned migration scripts that include upgrade() and downgrade() functions. Each migration is connected to a parent revision, creating a continuous sequence of updates. The most recent revision in this chain is called a head. Ideally, there should only be one head. However, when multiple developers generate migrations separately without syncing their branches, Alembic can end up with multiple heads.

2. Setting a Baseline for an Existing Database

If you’re introducing Alembic to a database that already contains tables and data, you can set a baseline instead of recreating everything. This helps Alembic recognize the current schema as the starting point.

Steps to Create a Baseline

• • 1. Initialize Alembic (if not already done):

alembic init alembic

• • 2. Configure the Environment:
    In alembic.ini, update your database connection string:

sqlalchemy.url = postgresql://user:password@localhost/mydatabase

In env.py, ensure that your SQLAlchemy models are properly imported to enable schema autogeneration.

from myapp.models import Base  target_metadata = Base.metadata

• • 3. Create an Empty Migration Script:

alembic revision –autogenerate -m “Baseline migration”

Then, remove any automatically generated schema changes, keeping it as a placeholder.

• • 4. Stamp the Database with the Current Revision:

alembic stamp head

This marks the database as being at the latest migration version without applying any changes. Alembic will update the alembic_version table accordingly.

3. Identifying Multiple Heads

You might see an error like this:

ERROR: Multiple heads are present; please specify a ‘head’ to merge

or when running:

alembic heads

you may find output such as:

Rev: a563930e420e (head) Parent: 6151c8336ea3 Rev: b6722ef1b33d (head) Parent: 6151c8336ea3

This indicates that two different migration branches share the same parent revision, creating multiple heads.

4. Resolving Multiple Head Issues

To combine these branches into a single unified chain, Alembic offers the merge command:

alembic merge -m “Merge multiple heads” a563930e420e b6722ef1b33d

This command generates a new migration file that merges both heads, resulting in one continuous migration path.

Tips to Prevent Multiple Heads

• Always pull the latest changes and run migrations before creating a new one.
• Maintain consistent branch naming in version control.
• Regularly run alembic heads to check for multiple heads.
• Avoid generating migrations on outdated feature branches.

5. Common Scenarios and Troubleshooting

Then reapply migrations in order to restore synchronization.