FastAPI+SQLAlchemy+Alembic中greenlet_spawn报错及迁移生成失败问题

问题原因 #

这个错误的核心是：Alembic默认以同步方式运行迁移，但你使用了SQLAlchemy的异步引擎/会话。异步IO操作必须在greenlet上下文（比如asyncio.run()或SQLAlchemy的greenlet_spawn）中执行，而默认的Alembic env.py脚本没有处理异步上下文，导致异步数据库操作找不到合法的运行环境。

解决步骤 #

1. 检查并修改env.py脚本 #

这是解决问题的核心，需要让Alembic适配SQLAlchemy的异步引擎。以下是适配后的完整env.py示例（结合你的db.py和user.py结构）：

from logging.config import fileConfig

from sqlalchemy import engine_from_config
from sqlalchemy import pool
from sqlalchemy.ext.asyncio import AsyncEngine
from sqlalchemy.future import Connection

from alembic import context

# 导入你的模型基类和所有实体模型
from db import Base
from user import User  # 必须导入所有需要迁移的模型，否则autogenerate会遗漏

# 读取Alembic配置
config = context.config

# 配置日志（默认逻辑保留）
if config.config_file_name is not None:
    fileConfig(config.config_file_name)

# 设置迁移的目标元数据
target_metadata = Base.metadata

def run_migrations_offline() -> None:
    """离线模式运行迁移（无需数据库连接）"""
    url = config.get_main_option("sqlalchemy.url")
    context.configure(
        url=url,
        target_metadata=target_metadata,
        literal_binds=True,
        dialect_opts={"paramstyle": "named"},
    )

    with context.begin_transaction():
        context.run_migrations()

def do_run_migrations(connection: Connection) -> None:
    """实际执行迁移的同步逻辑"""
    context.configure(connection=connection, target_metadata=target_metadata)

    with context.begin_transaction():
        context.run_migrations()

async def run_migrations_online() -> None:
    """在线模式运行迁移（适配异步引擎）"""
    # 创建异步引擎
    connectable = AsyncEngine(
        engine_from_config(
            config.get_section(config.config_ini_section),
            prefix="sqlalchemy.",
            poolclass=pool.NullPool,
            future=True,
        )
    )

    # 建立异步连接，并在同步上下文里执行迁移
    async with connectable.connect() as connection:
        await connection.run_sync(do_run_migrations)

    # 释放连接资源
    await connectable.dispose()

# 根据模式选择执行逻辑
if context.is_offline_mode():
    run_migrations_offline()
else:
    import asyncio
    asyncio.run(run_migrations_online())

2. 关键注意事项 #

• 必须导入所有模型：如果某个实体模型没导入到env.py中，alembic revision --autogenerate会检测不到该模型的变化。
• 配置文件的URL要匹配：alembic.ini中的sqlalchemy.url必须是异步数据库URL（比如postgresql+asyncpg://user:pass@localhost/dbname，而非同步的postgresql://）。
• 使用run_sync桥接同步与异步：connection.run_sync()会把同步的迁移逻辑包装到异步连接的greenlet上下文中，解决MissingGreenlet错误。

3. 验证修复 #

执行以下命令测试：

alembic revision --autogenerate -m "initial migration"

如果没有报错，说明上下文问题已解决，后续正常执行迁移即可。

内容的提问来源于stack exchange，提问作者sonochiwa