SQLAlchemy插入PostgreSQL触发id非空约束问题排查

核心问题 #

触发id列非空约束错误的根源有两个：

1. 数据库表未配置自增序列：PostgreSQL中INTEGER类型主键不会自动生成值，必须显式指定自增机制（如SERIAL或IDENTITY）。你的建表脚本仅设置id INTEGER NOT NULL，无自动生成逻辑，导致插入时id字段为空。
2. 实体模型定义错误：每个实体类单独使用@as_declarative()装饰器是错误用法，该装饰器应用于创建所有实体的基类，而非每个实体，这会导致SQLAlchemy无法正确识别自增配置。

解决方案 #

1. 修正数据库建表脚本 #

将id字段改为PostgreSQL支持的自增类型，推荐两种写法：

方式一：SERIAL（传统兼容写法）

CREATE TABLE organization (
    id SERIAL PRIMARY KEY, 
    name VARCHAR NOT NULL, 
    enabled BOOLEAN DEFAULT FALSE, 
    created_by VARCHAR NOT NULL
);

CREATE TABLE network (
    id SERIAL PRIMARY KEY, 
    organization_id INTEGER NOT NULL REFERENCES organization(id), 
    name VARCHAR NOT NULL, 
    created_by VARCHAR NOT NULL
);

方式二：IDENTITY（PostgreSQL 10+推荐写法）

CREATE TABLE organization (
    id INTEGER GENERATED ALWAYS AS IDENTITY PRIMARY KEY, 
    name VARCHAR NOT NULL, 
    enabled BOOLEAN DEFAULT FALSE, 
    created_by VARCHAR NOT NULL
);

CREATE TABLE network (
    id INTEGER GENERATED ALWAYS AS IDENTITY PRIMARY KEY, 
    organization_id INTEGER NOT NULL REFERENCES organization(id), 
    name VARCHAR NOT NULL, 
    created_by VARCHAR NOT NULL
);

2. 修正实体模型定义 #

正确使用as_declarative创建基类，所有实体继承该基类：

from sqlalchemy import Column, INTEGER, VARCHAR, BOOLEAN, ForeignKey
from sqlalchemy.ext.declarative import as_declarative, declared_attr
from sqlalchemy.orm import relationship

# 创建所有实体的基类
@as_declarative()
class Base:
    @declared_attr
    def __tablename__(cls):
        return cls.__name__.lower()  # 自动生成表名（类名转小写）
    id = Column(INTEGER, primary_key=True, autoincrement=True)

class OrganizationEntity(Base):
    name = Column(VARCHAR, nullable=False)
    enabled = Column(BOOLEAN, default=False)
    created_by = Column(VARCHAR, nullable=False)
    networks = relationship("NetworkEntity", back_populates="organization")

class NetworkEntity(Base):
    organization_id = Column(INTEGER, ForeignKey("organization.id"), nullable=False)
    name = Column(VARCHAR, nullable=False)
    created_by = Column(VARCHAR, nullable=False)  # 补充建表脚本中存在的字段
    organization = relationship("OrganizationEntity", back_populates="networks")

3. 验证修复 #

重新创建数据库表结构后，运行原仓库代码即可实现id自动自增插入，无需手动指定id值。

若已存在旧表，可通过ALTER语句修改id字段属性：

ALTER TABLE organization ALTER COLUMN id TYPE SERIAL;
ALTER TABLE network ALTER COLUMN id TYPE SERIAL;

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