如何使Alembic识别SQLAlchemy通用类创建的跨声明式基类共享表？

问题根源 #

Alembic通过扫描SQLAlchemy声明式基类的子类、或读取基类的metadata来发现需要迁移的模型。如果你的GenericTableW是通过动态方式（比如类工厂）创建，且没有被Alembic的扫描流程捕获、或未正确关联到BaseX/BaseY的元数据集合，就会被遗漏。

可行解决方案 #

方案1：改用Mixin类复用（最稳妥） #

放弃动态类工厂，用SQLAlchemy推荐的Mixin模式复用字段，静态定义两个库的TableW类，Alembic能直接识别：

# 定义通用字段Mixin
from sqlalchemy import Integer, String
from sqlalchemy.orm import mapped_column

class TableWMixin:
    id = mapped_column(Integer, primary_key=True)
    name = mapped_column(String(50), nullable=False)

# X库的TableW
from app.db.base_class import BaseX
class TableWInX(TableWMixin, BaseX):
    __tablename__ = "table_w"

# Y库的TableW
from app.db.base_class import BaseY
class TableWInY(TableWMixin, BaseY):
    __tablename__ = "table_w"

方案2：显式在Alembic env.py中导入动态模型 #

如果坚持用动态类工厂，需要在Alembic的env.py中显式导入动态创建的TableWInX/TableWInY，确保它们被加载到对应基类的元数据中：

假设你的动态类定义在app/db/models/table_w.py：

from app.db.base_class import BaseX, BaseY

def create_table_w(base_class):
    class GenericTableW(base_class):
        __tablename__ = "table_w"
        id = mapped_column(Integer, primary_key=True)
        name = mapped_column(String(50), nullable=False)
    return GenericTableW

TableWInX = create_table_w(BaseX)
TableWInY = create_table_w(BaseY)

然后在对应数据库的env.py（多库迁移场景）中显式导入：

# 针对X库的env.py
from app.db.base_class import BaseX
from app.db.models.table_z import TableZ
from app.db.models.table_w import TableWInX  # 必须显式导入

target_metadata = BaseX.metadata

方案3：手动注册动态类到基类元数据 #

如果动态类创建后未自动加入基类的metadata.tables，可以手动添加：

TableWInX = create_table_w(BaseX)
# 手动将表添加到BaseX的元数据
if "table_w" not in BaseX.metadata.tables:
    BaseX.metadata.tables["table_w"] = TableWInX.__table__

额外注意事项 #

• 多数据库场景下，要为Alembic配置独立的迁移环境（比如在alembic.ini中设置多个sqlalchemy.url，或使用分支迁移结构），每个环境对应BaseX/BaseY的元数据。
• 运行alembic revision --autogenerate前，确保所有模型都已被正确导入，没有循环导入问题。

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