如何在SQLModel中创建带指定schema的数据库表？

核心问题原因 #

PostgreSQL不会自动创建不存在的Schema，所有依赖该Schema的表创建操作都会失败；另外需确保SQLModel的元数据配置与表创建逻辑匹配。

解决方案步骤 #

1. 先显式创建目标Schema：执行CREATE SCHEMA IF NOT EXISTS语句避免Schema不存在的报错；
2. 正确配置SQLModel类的Schema参数：两种配置方式的正确用法如下：

方式一：使用自定义MetaData

from sqlmodel import SQLModel, Field, Session, create_engine
from sqlalchemy import MetaData, text

# 定义带Schema的元数据
foo_metadata = MetaData(schema="fooschema")

class Foo(SQLModel, table=True):
    __tablename__ = "footable"
    metadata = foo_metadata  # 将表关联到自定义元数据

    id_: int = Field(primary_key=True)

engine = create_engine("<你的数据库URL>")

# 第一步：创建Schema（关键）
with engine.connect() as conn:
    conn.execute(text("CREATE SCHEMA IF NOT EXISTS fooschema"))
    conn.commit()

# 使用自定义元数据创建表
foo_metadata.create_all(engine)

# 测试插入数据
with Session(engine) as session:
    row = Foo(id_=0)
    session.add(row)
    session.commit()
    session.refresh(row)

方式二：使用__table_args__

from sqlmodel import SQLModel, Field, Session, create_engine
from sqlalchemy import text

class Foo(SQLModel, table=True):
    __tablename__ = "footable"
    __table_args__ = {"schema": "fooschema"}  # 直接指定表的Schema

    id_: int = Field(primary_key=True)

engine = create_engine("<你的数据库URL>")

# 第一步：创建Schema（关键）
with engine.connect() as conn:
    conn.execute(text("CREATE SCHEMA IF NOT EXISTS fooschema"))
    conn.commit()

# 使用SQLModel默认元数据创建表（该表默认关联SQLModel.metadata）
SQLModel.metadata.create_all(engine)

# 测试插入数据
with Session(engine) as session:
    row = Foo(id_=0)
    session.add(row)
    session.commit()
    session.refresh(row)

为什么之前的尝试失败？ #

• 报错schema "fooschema" does not exist：PostgreSQL要求Schema必须提前创建，SQLModel的create_all不会自动生成Schema；
• 使用__table_args__创建表失败：本质还是Schema未提前创建，读取已有表时能正常工作是因为Schema和表已存在，SQLModel仅需完成映射，无需创建资源；
• 自定义MetaData时的问题：之前的代码缺少Schema创建步骤，导致创建表时找不到对应的Schema。

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