Add command "check-if-head"

[sscherfke]

Describe the use case
When multiple services/container use a database, only one of them should run the migrations. Assuming, that all services/containers are deployed at the same time, other services should not start, until the datatabase has been migrated to the head version. Currently, I use alembic current 2>/dev/null | grep --quiet '\(head\)' to perform this check. A dedicated command alembic check-if-main (or something like this) would make this easier and improve readability. The command would exit with 0 if the DB is at head or with 1 otherwise.

Optionally, this command could have a --retry SECONDS options.

Databases / Backends / Drivers targeted

all / independent of backend

Example Use

if [[ $RUN_MIGRATIONS = "1" ]] || [[ $RUN_MIGRATIONS = "true" ]]; then
    alembic upgrade head
else
    SLEEP=5
    until alembic current 2>/dev/null | grep --quiet '\(head\)'; do
        echo "Database migration version is not HEAD"
        sleep $SLEEP
    done
    echo "Database migrations are up-to-date"
fi

Additional context

Have a nice day!

Thanks. You, too! And thanks for this library. :-)

[sscherfke]

I could create an initial PR if you'd like to have this feature added. :)

[zzzeek]

Can you confirm this is the exact command you want : https://alembic.sqlalchemy.org/en/latest/cookbook.html#test-current-database-revision-is-at-head-s

[sscherfke]

Oh, I completely overlooked the cookbook. I was only checking the various CLI commands. 🙈

The linked snippet does what I want.

Is this something that you would wrap with a CLI command or would your rather leave it in the cookbook only?

[zzzeek]

the fact that I have it as a cookbook recipe already means other people have asked for this so it's not that controversial for a feature add, given that they finally got us to add alembic check which is a much bigger command

[zzzeek]

our CLI is more extensible than it was before but still not all the way plugin-extensible, so you could go that way but you'd need to have your own runner front-end

[CaselIT]

maybe this could be added to the existing current command? A flag that says --check-heads or something similar

Note that I would advise against using this method in your use case, since there are clear race conditions. Most orchestration frameworks support a way of creating a container that runs before the main services, and that container could run the migrations without risking race conditions

[zzzeek]

yeah I thought of that too, just augment the current command

[CaselIT]

great, @sscherfke if you want to submit a PR for it it would be great!

[sscherfke]

I'll prepare a PR in the next few days.

Note that I would advise against using this method in your use case, since there are clear race conditions. Most orchestration frameworks support a way of creating a container that runs before the main services, and that container could run the migrations without risking race conditions

My service consists of an API server and two additional daemon processes. Currently, they are deployed in the same deployment/pod which also has an init container that performs the migrations.

However, we want to put the three containers into different deployments so that we can scale the API server without also running multiple instances of the other services. Since we know that's we'll never scale up these helper services, one of them will always run the migrations and all other containers just check and wait at startup. We can also guarantee that all containers will always be updated at the same time, so I think we schould be alright. 🤞 😅