Does alembic care what its migration files are called?

Question

I'm reviewing some code that a colleague wrote, and I noticed that the migration ID contained in an Alembic migration file does not match the name of the file, e.g. the file 18b6422c9d3f_some_migration.py contains

revision = 'c4218d61f026'

My colleague does not know how this happened, and the names of all of the other revision files seem to line up with their revision IDs. For my own sanity I would like to rename the file to match its revision ID.

It seems clear that Alembic revision IDs don't hold any real semantic value, and renaming the file doesn't appear to break anything. I can still run the migration forwards and backwards. But I'm fairly inexperienced with Alembic and I'd like to make sure this is safe to do.

If I git mv 18b6422c9d3f_some_migration.py c4218d61f026_some_migration.py can I expect any long-term problems?

Answer 1

It's OK to rename a revision file as long as the revision variable inside it is set to the revision id.

While the revision id does get prepended to the name of a newly generated revision file (the remainder being derived from the comment that describes the migration), all Python files inside the versions directory are considered when collection revision ids and the links between them.

The tutorial says:

Every time Alembic runs an operation against the versions/ directory, it reads all the files in, and composes a list based on how the down_revision identifiers link together, with the down_revision of None representing the first file.

A look at the code (version 0.8.5, alembic/script/base.py, the Script._from_filename method) reveals that a script is loaded from any file that the revision id can be determined for, and if a revision id is set inside the script file, it is used without any regard whatsoever for the filename. Only if no revision id is set explicitly is it expected to be read from the beginning of the filename. This logic appears to have been in place since version 0.2.

Answer 2

The specific answer to your question is that yes, you can rename your migration without long-term issues. In fact, you're more likely to have long-term issues if you don't due to confusion about the actual revision ID.

The whole point of having the revision ID in the name of the file is to make it easy to find the file containing a specific revision, and a mis-labeled file could easily throw you off in a couple of months.

You can think of the name of the migration file as a commit message, while the revision ID is very much like a a commit hash. I personally have sometimes renamed my migration files to make the name more useful since the autogenerated names sometimes are ugly or leave out a key bit of the message due to the auto-generation length constraints.