Today I went to run automated tests in my Ironic development setup, and tests failed with a slew of errors like this:

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

This was quite baffling to me, and I at first assumed it was a git thing, given the references to branches and head.

I am still moderately confused. But here is how I fixed it.

Please note that: * I have little idea what I’m doing. This is what worked for me, not necessarily what someone clueful would do. * My fix involves trashing your database and recreating it. That’s perfectly acceptable for my test database, but proceed with caution.

Run alembic branches

The error told me to run alembic branches, but that failed:

$ alembic branches
  No config file 'alembic.ini' found, or file
  has no '[alembic]' section

The solution is to find your alembic.ini file. In Ironic, that’s ironic/db/sqlalchemy. cd into there, and now it will work:

$ alembic branches
None -> 2581ebaf0cb2 (branchpoint), initial migration
     -> 2581ebaf0cb2 -> 21b7629c61e7 (head), 
     -> 2581ebaf0cb2 -> 21b331f883ef (head), Add provision_updated_at

The alembic documentation talks a little bit about this, for further reading.

Look for .pyc files

Each of those hashes should point to a Python file in alembic/versions/.

I think where I went wrong is that I had switched branches and ended up with a .pyc file, but not matching .py. The name should match one of the hashes above. (I suppose you could safely just delete all the .pyc files, actually.)

Downgrade to alembic base

I’m actually not sure if this was necessary, but I did this: alembic downgrade base. If it bombs out with errors, I think we’ll fix them momentarily.

Delete the tables from your database

Now we’re basically going to start a new database.

I fired up mysql, ran USE ironic, and then deleted all the tables. You might have to play with ordering to get it right, due ot foreign key constraints.

Re-run alembic

In Ironic, we have ironic-dbsync to do this for us. If not using Ironic, I think alembic upgrade head is analogous.

And then you should be good. Hopefully.