Repository navigation
Add command "check-if-head" #1705
Description
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"
fiAdditional context
Have a nice day!
Thanks. You, too! And thanks for this library. :-)
Activity
sscherfke commentedon Aug 4, 2025
I could create an initial PR if you'd like to have this feature added. :)
zzzeek commentedon Aug 4, 2025
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 commentedon Aug 4, 2025
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 commentedon Aug 4, 2025
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 commentedon Aug 4, 2025
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 commentedon Aug 4, 2025
maybe this could be added to the existing current command? A flag that says
--check-headsor something similarNote 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 commentedon Aug 5, 2025
yeah I thought of that too, just augment the current command
CaselIT commentedon Aug 5, 2025
great, @sscherfke if you want to submit a PR for it it would be great!
sscherfke commentedon Aug 5, 2025
I'll prepare a PR in the next few days.
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. 🤞 😅
Add "--check-heads" option to "current" command
sqla-tester commentedon Oct 27, 2025
Stefan Scherfke has proposed a fix for this issue in the main branch:
Add "--check-heads" option to "current" command https://gerrit.sqlalchemy.org/c/sqlalchemy/alembic/+/6265
Add "--check-heads" option to "current" command
Add "--check-heads" option to "current" command