Alembic关联Supabase预存auth.users表失败问题求助

核心思路 #

问题根源是SQLAlchemy无法识别Supabase预创建的auth.users表，且Alembic默认会扫描所有关联表导致误操作。解决要点是让SQLAlchemy正确识别跨schema外键，同时阻止Alembic改动Supabase的auth schema。

方法1：显式定义跨Schema外键（无需反射） #

直接通过ForeignKeyConstraint指定跨schema的外键关系，不需要将auth.users加入自己的元数据，避免Alembic试图重建该表。

from sqlalchemy import Column, Integer, String, ForeignKeyConstraint
from sqlalchemy.ext.declarative import declarative_base

Base = declarative_base()

class FactUsers(Base):
    __tablename__ = "fact_users"
    # 指定你的应用专属schema，比如"app"
    __table_args__ = (
        # 显式定义外键，指定目标表的完整schema+表名
        ForeignKeyConstraint(
            ["auth_user_id"],
            ["auth.users.id"],
            name="fact_users_auth_user_id_fkey"  # 自定义外键名称，避免自动生成的名称冲突
        ),
        {"schema": "app"}
    )

    id = Column(Integer, primary_key=True)
    auth_user_id = Column(Integer, nullable=False)
    # 其他业务字段
    username = Column(String(50), nullable=False)

方法2：反射Supabase的auth.users表（适合ORM关联查询场景） #

如果需要通过ORM直接关联auth.users表进行查询，可以用SQLAlchemy的反射功能加载该表，同时确保Alembic不会处理它。

from sqlalchemy import create_engine, MetaData
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy import Column, Integer, String, ForeignKey
from sqlalchemy.orm import relationship

# 初始化你的应用元数据
app_metadata = MetaData(schema="app")
Base = declarative_base(metadata=app_metadata)

# 反射Supabase的auth schema下的users表
engine = create_engine("postgresql://your-supabase-connection-url")
auth_metadata = MetaData(schema="auth")
# 只反射users表，避免加载其他auth表
auth_metadata.reflect(engine, only=["users"])
auth_users = auth_metadata.tables["auth.users"]

class FactUsers(Base):
    __tablename__ = "fact_users"

    id = Column(Integer, primary_key=True)
    auth_user_id = Column(Integer, ForeignKey(auth_users.c.id), nullable=False)
    # 建立ORM关联
    auth_user = relationship(auth_users)
    username = Column(String(50), nullable=False)

关键：配置Alembic忽略auth schema #

无论用哪种方法，都必须修改Alembic的env.py，确保它只处理你的应用schema，不会扫描或修改auth下的表：

# alembic/env.py
from sqlalchemy import text
from your_app.models import Base  # 导入你的Base类

target_metadata = Base.metadata

def run_migrations_online():
    # ... 保留原有代码 ...
    with connectable.connect() as connection:
        # 设置搜索路径为你的应用schema，避免默认包含auth
        connection.execute(text("SET search_path TO app"))
        context.configure(
            connection=connection,
            target_metadata=target_metadata,
            include_schemas=False,  # 不包含其他schema的表
            exclude_tables=["auth.users"],  # 明确排除auth.users表
            compare_type=True,
            compare_server_default=True
        )

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

迁移文件善后处理 #

如果之前已经生成过错误的迁移文件，需要：

1. 删除自动生成的会删除外键的迁移代码
2. 手动创建包含外键的迁移（用方法1时，Alembic会自动生成正确的外键创建语句）
3. 执行alembic upgrade head确保迁移生效

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