Alembic忽略alpha schema时如何为beta表添加其user表外键？

现有项目中，alpha schema由Go+Goose维护，其中包含user表（存储认证数据）。当前使用FastAPI+SQLAlchemy+Alembic开发，需要在beta schema的表中添加指向alpha.user.id的外键，代码示例如下：

class Forms(Base, UserMixin):
    __tablename__ = "forms"
    
    form_config = Column(String(8192), nullable=False)
    is_active = Column(SMALLINT, default = 0)

class UserMixin(object):
    @declared_attr
    def user_id(self):
        return Column(String(64), ForeignKey('alpha.user.id'), nullable=False)

执行alembic revision --autogenerate时触发错误：

sqlalchemy.exc.NoReferencedTableError: Foreign key associated with
column 'forms.user_id' could not find table 'alpha.user' with which to
generate a foreign key to target column 'id'

当前env.py中通过include_names仅包含beta和public schema：

def include_name(name, type_, parent_names):
    if type_ == "schema":
        # note this will not include the default schema
        return name in ["beta", "public"]
    else:
        return True

    ...
    
    context.configure(
        include_schemas=True,
        include_name=include_name,
        ...
    )

需求：无需在代码中定义alpha表，让beta schema的所有表能添加指向alpha.user.id的外键。

方法1：手动声明外部表的存在（推荐） #

在SQLAlchemy中通过Table类直接声明alpha.user表的核心结构（仅需外键关联依赖的字段），无需映射成ORM模型，即可让Alembic识别该表：

# 可放置在项目models目录的__init__.py或单独文件中
from sqlalchemy import Table, Column, String, MetaData

# 创建alpha schema专属元数据
alpha_metadata = MetaData(schema="alpha")

# 仅声明user表的id字段（外键关联必需的主键）
Table(
    "user",
    alpha_metadata,
    Column("id", String(64), primary_key=True),
    # 无需定义其他字段，保留外键依赖的部分即可
)

同时修改env.py中的include_name函数，允许alpha schema被识别但排除其迁移操作：

def include_name(name, type_, parent_names):
    if type_ == "schema":
        # 保留beta、public，同时允许alpha被识别
        return name in ["beta", "public", "alpha"]
    elif type_ == "table" and parent_names["schema"] == "alpha":
        # 排除alpha下的所有表，禁止Alembic生成相关迁移脚本
        return False
    else:
        return True

配置完成后，Alembic自动生成迁移时能找到alpha.user表验证外键，且不会对alpha schema的表产生任何迁移操作。

方法2：手动编写迁移脚本 #

若不想修改代码结构，可跳过自动生成，直接手动创建迁移脚本：

1. 执行命令生成空迁移脚本：

alembic revision -m "add user_id foreign key to forms"

2. 在生成的脚本中手动添加外键逻辑：

from alembic import op
import sqlalchemy as sa

def upgrade():
    # 添加user_id字段
    op.add_column(
        "forms",
        sa.Column("user_id", sa.String(64), nullable=False),
        schema="beta"
    )
    # 创建外键约束
    op.create_foreign_key(
        "fk_forms_user_id",
        "forms",
        "user",
        ["user_id"],
        ["id"],
        source_schema="beta",
        referent_schema="alpha"
    )

def downgrade():
    # 删除外键约束
    op.drop_constraint(
        "fk_forms_user_id",
        "forms",
        schema="beta"
    )
    # 删除user_id字段
    op.drop_column("forms", "user_id", schema="beta")

该方式适合临时或少量表的外键添加，但多表关联时维护成本较高。

方法3：通过SQLAlchemy反射配置 #

在env.py的context.configure中开启反射，并指定需要反射的schema，同时过滤不需要的表：

def run_migrations_online():
    # ... 原有代码 ...
    context.configure(
        include_schemas=True,
        include_name=include_name,
        reflect=True,
        # 指定需要反射的schema列表
        reflect_schemas=["alpha", "beta", "public"],
        # ... 其他配置 ...
    )

同步调整include_name函数，确保alpha表被反射但不生成迁移：

def include_name(name, type_, parent_names):
    if type_ == "schema":
        return name in ["beta", "public", "alpha"]
    elif type_ == "table" and parent_names["schema"] == "alpha":
        return False
    else:
        return True

此方式会反射alpha schema的全量表结构，适合alpha表结构稳定的场景，若alpha表有变更可能影响反射结果。

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