alembic revision - multiple heads (due branching) error

Question

I've got an application and I wanted to create a new migration for it today. When I run

$ alembic revision -m "__name__" 

I got a message

Only a single head is supported. The script directory has multiple heads (due branching), which must be resolved by manually editing the revision files to form a linear sequence.  Run `alembic branches` to see the divergence(s). 

Running

alembic branches 

gives nothing

I'm new to alembic. There are 2 developers working on this app and we have 2 git branches - master & develop (I'm not sure if this have anything to do with it).

Any clue on what is this about?

Answer 1

Perhaps the most conventional (and robust) solution is to use alembic merge heads. In the same way that when you have two branches in Git you can bring them back together with a merge commit, in Alembic when you have two branches you can bring them back together with a merge revision.

For instance, suppose we have a revision 1a6b1a4a0574 that adds table A, and a revision 2e49118db057 that adds table B. We can see these revisions (both marked as (head)) in alembic history:

$ alembic history <base> -> 2e49118db057 (head), Add table B <base> -> 1a6b1a4a0574 (head), Add table A 

Then we can merge them by running alembic merge heads:

$ alembic merge heads   Generating /Users/markamery/alembictest/alembic/versions/409782f4c459_.py ... done $ alembic history 2e49118db057, 1a6b1a4a0574 -> 409782f4c459 (head) (mergepoint), empty message <base> -> 2e49118db057, Add table B <base> -> 1a6b1a4a0574, Add table A 

If one of your revisions may have already been run somewhere (including on the development machine of one of your coworkers), then you probably want to use alembic merge instead of tinkering with the down_revision of one of the revisions, as the other answers here suggest. The danger of tinkering with the down revision is that it may result in a revision never getting applied. For instance, suppose that your colleague Bob has already pulled down your branch with revision 2e49118db057 and run alembic upgrade head, creating table B. Then you decide to modify the down_revision of 2e49118db057 to point to 1a6b1a4a0574, which Bob has never seen or run before. Bob pulls down your change, runs alembic upgrade head, and... nothing happens, because as far as Alembic is concerned he's already at the head and doesn't need to run 1a6b1a4a0574. And so Bob ends up never getting table A and probably never figures out why his database is in a broken state.

Don't break Bob's database - make a merge revision instead.

Answer 2

This issue happens when two alembic migrations are branched from the same migration. Usually, this happens when multiple people are making schema changes. To fix it you just have to adjust thedown_revision of your migration to be that of the latest one. Running alembic history shows us this:

2f4682466279 -> f34e92e9dc54 (head), Fifth revision (on a separate branch) 2f4682466279 -> f673ac37b34a (head), Fifth revision (local) 2dc9337c3987 -> 2f4682466279, Fourth revision 0fa2aed0866a -> 2dc9337c3987, Third revision 22af4a75cf06 -> 0fa2aed0866a, Second revision 9a8942e953eb -> 22af4a75cf06, First revision 

You can see that one of the Fifth revisions was made locally and it's downstream revision is2f4682466279 but whoever made the other Fifth revision got the same downstream revision too.

Go into one of the Fifth revision files and update down_revision variable to reference the other Fifth revision, like this:

f673ac37b34a -> f34e92e9dc54 (head), Fifth revision (on a separate branch) 2f4682466279 -> f673ac37b34a, Fifth revision (local) 2dc9337c3987 -> 2f4682466279, Fourth revision 0fa2aed0866a -> 2dc9337c3987, Third revision 22af4a75cf06 -> 0fa2aed0866a, Second revision 9a8942e953eb -> 22af4a75cf06, First revision 

In this case I updated migration f34e92e9dc54 to have down_revision='f673ac37b34a'.