command.upgrade(alembic_cfg, "head") never returns and blocks the process indefinitely.

[oefterdal]

Bug Description:
Running command.upgrade(alembic_cfg, "head") never returns and blocks the process indefinitely.

Expected Behavior:
The process should complete and return, either successfully or with a failure.

To Reproduce:

def run_migrations():
    try:
        logger.info("Starting database migrations")
        alembic_cfg = Config("alembic.ini")
        command.upgrade(alembic_cfg, "head")
        logger.info("Database migrations completed successfully")
    except Exception as e:
        logger.error(f"Migration failed: {e}")
        raise

Error:

# Copy error here. Please include the full stack trace.

Environment:

• OS: macOS 14.15
• Python: 3.12
• Alembic: 1.13.1
• SQLAlchemy: 2.0.30
• Database: SQLite
• DBAPI: SQLModel 2.0.0

Additional Context:
The following workaround using subprocess works:

def run_migrations():
    try:
        logger.info("Starting database migrations")

        # Run the Alembic upgrade command using subprocess
        result = subprocess.run(["alembic", "upgrade", "head"], capture_output=True, text=True)
        if result.returncode != 0:
            logger.error(f"Alembic upgrade failed: {result.stderr}")
            raise RuntimeError(f"Alembic upgrade failed: {result.stderr}")
        
        logger.info("Database migrations completed successfully")
    except Exception as e:
        logger.error(f"Migration failed: {e}")
        raise
    finally:
        # Ensure the engine is disposed
        engine.dispose()
        logger.info("Disposed of the engine to close all connections.")

Have a nice day!

[CaselIT]

Hi,

If alembic upgrade blocks it means that the db is waiting for a lock.
Depending on the db you may set a timeout on the transaction, so that it will error after a while

[CaselIT]

Have you opened the sqlite file in other places in the file?

[oefterdal]

I haven't.

[oefterdal]

lsof only shows one process.

[dunielpls]

I am not quite sure why yet, but I am having a similar issue. I am running alembic.command.check as part of the startup of a FastAPI application and my exceptions are somehow eaten. Posting this in hopes that it may aid troubleshooting.

Note that I can catch the exception (i.e. print something before the raise Exception) but the raised exception never does anything with Alembic.

A somewhat minimal example of the issue ($PWD/main.py):

import contextlib

import fastapi
import alembic.util
import alembic.config
import alembic.command

@contextlib.asynccontextmanager
async def lifespan(app):
    try:
        alembic.command.check(alembic.config.Config("alembic.ini"))
    except alembic.util.AutogenerateDiffsDetected:
        raise Exception("Database schema missing or outdated.")

    yield

app = fastapi.FastAPI(lifespan=lifespan)

Code that shows intentional behaviour (also $PWD/main.py)

import contextlib

import fastapi
import alembic.util
import alembic.config
import alembic.command

@contextlib.asynccontextmanager
async def lifespan(app):
    raise Exception("Database schema missing or outdated.")
    yield

app = fastapi.FastAPI(lifespan=lifespan)

They can be executed as:

$ uvicorn --workers 1 --log-level debug main:app

Relevant packages:

aiohttp==3.9.5
fastapi==0.111.0
aiosqlite==0.20.0
SQLAlchemy[asyncio]==2.0.31
uvicorn[standard]==0.30.1

[dunielpls]

My issue was caused by fileConfig's argument disable_existing_loggers defaulting to True. Setting it to False solved my issue.

if config.config_file_name is not None:
    fileConfig(config.config_file_name, disable_existing_loggers=False)