python - 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?

question from:https://stackoverflow.com/questions/22342643/alembic-revision-multiple-heads-due-branching-error

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.