如何用SQLAlchemy的DeclarativeBase/MappedAsDataclass在PostgreSQL创建UUID列

问题背景 #

已基于SQLAlchemy 2.0的MappedAsDataclass和DeclarativeBase创建了Post数据表，现希望将主键替换为GUID（UUID）类型，但尝试的实现方式未成功，核心错误在于类型注解和列配置不正确。

解决方案 #

要正确实现UUID主键，需修正类型注解、列类型配置及默认值设置，以下是完整步骤：

1. 导入必要依赖 #

确保导入uuid模块及SQLAlchemy的PostgreSQL UUID类型：

import uuid
from sqlalchemy.dialects.postgresql import UUID
from sqlalchemy.orm import Mapped, mapped_column, MappedAsDataclass, DeclarativeBase
from sqlalchemy import ForeignKey, ARRAY, TEXT
from datetime import datetime, Optional

2. 修正Post模型定义 #

将原有的post_id主键替换为UUID类型的guid，以下是完整示例：

class Base(MappedAsDataclass, DeclarativeBase):
    """子类将被转换为数据类"""

class Post(Base):
    __tablename__ = 'allposts'
    # UUID类型主键，自动生成默认值，实例化时无需传入
    guid: Mapped[uuid.UUID] = mapped_column(
        UUID(),
        primary_key=True,
        default=uuid.uuid4,
        init=False
    )
    collection_id: Mapped[int] = mapped_column(ForeignKey("collections.collection_id"), default=None, nullable=True)
    user: Mapped[str] = mapped_column(default=None, nullable=True)
    title: Mapped[str] = mapped_column(default=None, nullable=True)
    description: Mapped[str] = mapped_column(default=None, nullable=True)
    date_added: Mapped[datetime] = mapped_column(default=None, nullable=True)
    date_modified: Mapped[Optional[datetime]] = mapped_column(default=None, nullable=True)
    tags: Mapped[list] = mapped_column(ARRAY(TEXT, dimensions=1), default=None, nullable=True)
    views: Mapped[int] = mapped_column(default=0, nullable=True)

# 创建表
Base.metadata.create_all(engine)

关键修正点说明 #

• 类型注解：Mapped[uuid.UUID]是正确的类型标注，uuid.uuid1是生成UUID的函数，不能作为类型使用。
• 列类型配置：通过mapped_column的type_=UUID()指定PostgreSQL的UUID列类型。
• 主键与默认值：设置primary_key=True将guid设为主键，default=uuid.uuid4（或uuid.uuid1）实现自动生成UUID值，init=False表示实例化Post对象时无需传入该字段。

保留原有post_id的方案（可选） #

若需保留原post_id同时新增UUID字段，只需调整guid的配置，去掉primary_key=True：

guid: Mapped[uuid.UUID] = mapped_column(
    UUID(),
    default=uuid.uuid4,
    nullable=False,
    unique=True
)

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