使用SQLAlchemy 2.0与PostgreSQL创建1:1映射缺失关联列问题

我的代码 #

class Base(orm.DeclarativeBase): 
    pk: orm.Mapped[uuid.UUID] = orm.mapped_column(
    primary_key=True,
    default=uuid.uuid4,
    )


class AAA(Base):
    __tablename__ = "aaa"

    name: orm.Mapped[str]
    # 1:1 mapping with BBB 
    linked_bbb: orm.Mapped["BBB"] = relationship(back_populates="linked_aaa", lazy="selectin")


class BBB(Base):
    __tablename__ = "bbb"

    name: orm.Mapped[str]

    # 1:1 mapping with AAA 
    linked_aaa: orm.Mapped["AAA"] = relationship(back_populates="linked_bbb", lazy="selectin")

生成的数据库表结构 #

my_db=> \d aaa
                     Table "public.aaa"
 Column |       Type        | Collation | Nullable | Default 
--------+-------------------+-----------+----------+---------
 name   | character varying |           | not null | 
 pk     | uuid              |           | not null | 
Indexes:
    "aaa_pkey" PRIMARY KEY, btree (pk)

my_db=> \d bbb
                     Table "public.bbb"
 Column |       Type        | Collation | Nullable | Default 
--------+-------------------+-----------+----------+---------
 name   | character varying |           | not null | 
 pk     | uuid              |           | not null | 
Indexes:
    "bbb_pkey" PRIMARY KEY, btree (pk)

我原本预期每个表都会有一个关联到另一个表的列，请问我遗漏了什么？

解决方案 #

你只定义了ORM层面的relationship关联逻辑，但没有在数据库层面显式声明外键字段——这就是数据库表中没有出现关联列的核心原因。

SQLAlchemy的relationship仅负责处理Python对象之间的关联交互，而数据库层面的外键约束和关联列，必须通过mapped_column配合ForeignKey来定义。同时，默认的relationship是一对多模式，需要加上uselist=False来明确这是一对一映射。

修改后的代码示例 #

import uuid
from sqlalchemy import ForeignKey
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship


class Base(DeclarativeBase):
    pk: Mapped[uuid.UUID] = mapped_column(
        primary_key=True,
        default=uuid.uuid4,
    )


class AAA(Base):
    __tablename__ = "aaa"

    name: Mapped[str]
    # 明确一对一关联，uselist=False指定非列表类型
    linked_bbb: Mapped["BBB"] = relationship(
        back_populates="linked_aaa",
        lazy="selectin",
        uselist=False
    )


class BBB(Base):
    __tablename__ = "bbb"

    name: Mapped[str]
    # 添加外键字段，指向aaa表的主键pk
    aaa_pk: Mapped[uuid.UUID] = mapped_column(ForeignKey("aaa.pk"))
    # 明确一对一关联
    linked_aaa: Mapped["AAA"] = relationship(
        back_populates="linked_bbb",
        lazy="selectin",
        uselist=False
    )

关键说明 #

1. 外键字段：在其中一个表（示例中是BBB）添加指向另一表主键的外键列，这是数据库层面生成关联的核心。
2. uselist=False：告诉SQLAlchemy这是一对一映射，而非默认的一对多，避免生成列表类型的属性。
3. 双向外键不推荐：一对一映射只需单向外键即可满足需求，无需在两个表都添加外键，否则会造成冗余和维护负担。

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