command.upgrade hangs with uvicorn and fastapi

[Thlr]

Describe the bug
I am trying to run a FastAPI server but the startup process hangs on the migration.

INFO:     Will watch for changes in these directories: ['/home/tlarue/vav/solena/gateway-controller']
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [1168209] using StatReload
INFO:     Started server process [1168211]
INFO:     Waiting for application startup.
2025-09-03 17:27:07,833 - app.database.init_db - INFO - init_db.py:27 - Database tables already exist
INFO  [alembic.runtime.migration] Context impl SQLiteImpl.
INFO  [alembic.runtime.migration] Will assume non-transactional DDL.
INFO:     Application startup complete.

Expected behavior
I should see the confirmation in my logs that the migration has completed and then the rest of the startup process going on with the API running:

2025-09-03 17:22:15,166 - app.main - INFO - main.py:38 - Migrations applied successfully
2025-09-03 17:25:23,919 - app.core.home_assistant_client - INFO - home_assistant_client.py:113 - REST API reachable
2025-09-03 17:25:23,969 - app.core.home_assistant_client - INFO - home_assistant_client.py:137 - WebSocket authenticated
2025-09-03 17:25:23,977 - app.core.home_assistant_client - INFO - home_assistant_client.py:71 - Successfully Connected to Home Assistant and listening to state_changed events

This works fine when I comment the command.upgrade call.

To Reproduce

"""
Main entry point for the FastAPI app
Configures the app, the middlewares and the routes
"""

import asyncio
import logging
import os
from contextlib import asynccontextmanager

import uvicorn
from fastapi import FastAPI

from alembic import command
from alembic.config import Config
from app.database.init_db import create_database

logger = logging.getLogger(__name__)


async def run_migrations():
    """Run database migrations asynchronously"""
    try:
        cfg = Config("alembic.ini")
        await asyncio.to_thread(command.upgrade, cfg, "head")
        logger.info("Migrations applied successfully")
    except Exception as e:
        logger.error("Migration error: %s", e)


@asynccontextmanager
async def lifespan(app: FastAPI):
    """Manages the start and stop of the application"""
    # Initialize SQLite database
    await create_database()

    # Run migrations asynchronously
    await run_migrations()
   
    # Rest of the startup process

    yield


app = FastAPI(lifespan=lifespan)


def run():
    uvicorn.run(
        "app.main:app", port=8000, log_level=settings.log_level.lower(), reload=True
    )


if __name__ == "__main__":
    run()

Versions.

• OS: NixOS
• Python: v3.12.10
• Alembic: 1.6.5
• SQLAlchemy: 2.0.41
• Database: SQLite
• DBAPI:

Additional context

This seems very similar to #1155 but the solution of adding disable_existing_loggers=False to the fileConfig call in env.py did not function for me.

I have not modified the env.py

When running migrations from the command line I have the same logs but the process finishes normally with a 0 exit code

❯ uv run alembic upgrade head
INFO  [alembic.runtime.migration] Context impl SQLiteImpl.
INFO  [alembic.runtime.migration] Will assume non-transactional DDL.

Happy to provide more information if needed

[zzzeek]

hi -

there's no bug here in alembic. Hangs can be caused by PG table locks, or if your application / fastAPI has some kind of locking going on. It seems significant that your app seems to have something else going on with the database based on the message "2025-09-03 17:27:07,833 - app.database.init_db - INFO - init_db.py:27 - Database tables already exist", that's not anything Alembic does, so your issue may be related to whatever is the source of that message.

[Thlr]

Hi, thank you for your answer. This message is from the database creation step await create_database() and its removal does not seem to have any sort of impact.

I will look more closely into DB locks (I suspected something like that was happening). In the meanwhile, here is what I get with debug logs from sqlalchemy

INFO  [alembic.runtime.migration] Context impl SQLiteImpl.
INFO  [alembic.runtime.migration] Will assume non-transactional DDL.
INFO  [sqlalchemy.engine.Engine] BEGIN (implicit)
INFO  [sqlalchemy.engine.Engine] PRAGMA main.table_info("alembic_version")
INFO  [sqlalchemy.engine.Engine] [raw sql] ()
DEBUG [sqlalchemy.engine.Engine] Col ('cid', 'name', 'type', 'notnull', 'dflt_value', 'pk')
DEBUG [sqlalchemy.engine.Engine] Row (0, 'version_num', 'VARCHAR(32)', 1, None, 1)
INFO  [sqlalchemy.engine.Engine] SELECT alembic_version.version_num 
FROM alembic_version
INFO  [sqlalchemy.engine.Engine] [generated in 0.00013s] ()
DEBUG [sqlalchemy.engine.Engine] Col ('version_num',)
DEBUG [sqlalchemy.engine.Engine] Row ('7ae9564b8663',)
INFO  [sqlalchemy.engine.Engine] ROLLBACK

[zzzeek]

looks normal. when you get a hang, take a look in pg_stat_activity at the same time to see what transactions are in play (if any)

[Thlr]

We use a sqlite database and therefore do not have access to pg_stat_activity.

I suspect something is going on with asyncio, do you think it could be possible?

[Thlr]

So I managed to get logs at the very end of env.py. It terminates successfully (which if I understand correctly would mean that there is no issue with migrations?), however In the main.py that I shared I still cannot get passed the command.upgrade call.

await asyncio.to_thread(command.upgrade, cfg, "head")

[CaselIT]

does it work if you remove that asyncio.to_thread and instead call command.upgrade directly? just to test, I know that it blocks the event loop

[Thlr]

With the async env.py, it ends in an error

RuntimeWarning: coroutine 'run_async_migrations' was never awaited

With the standard env.py, it hangs just the same

[Thlr]

Somewhere else in the code, we create an engine for all of our database operations:

# app/database/connection.py
from sqlalchemy.ext.asyncio import create_async_engine

engine = create_async_engine(DATABASE_URL, echo=False, future=True)

I changed echo=False to echo=True and noticed that I was constantly getting logs indicating that the connection was somehow constantly doing work, eventhough the application had not yet started.

I tried re-using this engine:

from app.database.connection import engine
...

alembic_cfg = Config("alembic.ini")
async with engine.begin() as connection:
    alembic_cfg.attributes["connection"] = connection
    await asyncio.to_thread(command.upgrade, alembic_cfg, "head")

Alas it did not give different results, but the fact that I get a constant stream of operations in my log... Seems somewhat fishy. It seems that I have things to investigate on my own side.

Thank you for your time and helpful insights.