使用Alembic生成迁移时无法检测到SQLAlchemy registry映射表的问题

数据老陈

2026-6-15

问题

使用Alembic + SQLAlchemy生成数据库迁移时，生成的修订文件中upgrade和downgrade函数为空，Alembic未检测到项目中用registry.mapped_as_data_class定义的映射表。

项目结构：

模型文件存放在model文件夹，每个实体单独一个文件
config/register.py初始化registry()实例，赋值给table_register变量
模型通过@table_register.mapped_as_data_class装饰器映射数据库表

相关代码

register.py

from sqlalchemy.orm import registry

table_register = registry()

metadata = table_register.metadata

示例模型（model/aluno.py）

from enum import Enum
from datetime import datetime
import sqlalchemy
from sqlalchemy import (String, func, ForeignKey)
from sqlalchemy.orm import (Mapped, mapped_column)
from configs.register import table_register

@table_register.mapped_as_dataclass
class Aluno():
    __tablename__ = 'aluno'
    
    id: Mapped[int] = mapped_column(primary_key=True, init=False, name='id_aluno')
    nome: Mapped[str] = mapped_column(String(100), nullable=False, name='nome_aluno')
    serie: Mapped[int] = mapped_column(ForeignKey('serie.id_serie'), nullable=False, name='serie_aluno')
    turma: Mapped[Enum] = mapped_column(sqlalchemy.Enum('A', 'B', name='turma_enum'), nullable=False, name='turma_aluno')
    created_at: Mapped[datetime] = mapped_column(name='created_at', server_default=func.now(), init=False)

Alembic配置（env.py）

config = context.config
config.set_main_option('sqlalchemy.url', Config().DB_URI)

target_metadata = table_register.metadata

def run_migrations_online() -> None:
    """Run migrations in 'online' mode.

    In this scenario we need to create an Engine
    and associate a connection with the context.

    """
    connectable = engine_from_config(
        config.get_section(config.config_ini_section, {}),
        prefix="sqlalchemy.",
        poolclass=pool.NullPool,
    )

    with connectable.connect() as connection:
        context.configure(
            connection=connection, 
            target_metadata=target_metadata,
            compare_type=True
        )

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

原因与解决办法

核心原因

Alembic的target_metadata虽然指向了table_register.metadata，但模型文件未被导入加载，导致metadata中没有注册任何表结构信息。

使用registry.mapped_as_data_class装饰器时，只有当模型文件被执行（导入）时，才会将表结构注册到registry关联的metadata中。如果Alembic的env.py没有导入所有模型，metadata就是空的，自然生成空迁移。

解决步骤

在Alembic的env.py中导入所有模型
在env.py的合适位置（比如target_metadata定义之前）添加模型导入代码，确保所有模型文件被加载：
```
# 单个导入示例
from model.aluno import Aluno
from model.serie import Serie  # 假设存在Serie模型
```
若模型数量较多，可在model文件夹下创建__init__.py批量导入：
```
# model/__init__.py
from .aluno import Aluno
from .serie import Serie
# 导入其他所有模型...
```
然后在env.py中一次性导入：
```
from model import *
```

验证metadata表结构
可在env.py中临时添加打印代码，确认target_metadata是否包含表信息：

target_metadata = table_register.metadata
print(target_metadata.tables)  # 运行迁移命令时会输出已注册的表，检查是否包含你的模型表

检查模型定义规范
确认每个模型类都正确设置了__tablename__属性，mapped_column的定义符合SQLAlchemy 2.0语法（你的示例代码已符合规范，可快速核对）。

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

使用Alembic生成迁移时无法检测到SQLAlchemy registry映射表的问题

问题 #

相关代码 #