用途:这是一套与调用语言无关的 Postgres 模式(schema)与查询规则集合,触发时机是在编写或编辑 .sql 文件、迁移、模式、索引之前加载。
模式规则:封闭值集用 text 加具名 CHECK,不要用 Postgres ENUM;ENUM 加值属类型迁移、删值不受支持,而 CHECK 只需一次 ALTER。同一 schema 不混用两种风格,status 列不可无约束。已有 ENUM 应安排转换。每个外键列都要有索引,Postgres 不会自动创建。时刻用 timestamptz,日历日期用 date,时间不得存为 text。JSON 用 jsonb,不用 text。所有约束与索引都要命名,采用统一方案(<table>_<cols>_key、_fkey、check、<table><cols>_idx)。每列缺失值含义唯一,NULL 或 '' 二选一。追加型表在建表迁移中就要有保留策略,对清理过滤列建索引,从定时任务批量删除过期行。
查询规则:每次比较只用一个时钟,应用比较或测试断言的时间以参数传入,避免 SQL NOW() 与应用 time.Now() 混用。显式列清单,不用 SELECT * 和 RETURNING *。每个列表查询都要有硬 LIMIT;大表用 keyset 分页而非 OFFSET。避免 N+1 循环,用 = ANY($1::uuid[]) 取数、多行 VALUES 或 COPY 写入。领取任务用 FOR UPDATE SKIP LOCKED。先读后写用事务内 SELECT ... FOR UPDATE。唯一冲突按约束名匹配 SQLSTATE 23505。ON CONFLICT 必须指明目标。
改表规则:加列先可空或带常量默认,回填后再加 NOT NULL,不在加列迁移中重写大表;回填按主键分批提交;在线表用 CREATE INDEX CONCURRENTLY 且在事务外;大表约束分两步 ADD CONSTRAINT ... NOT VALID 再 VALIDATE CONSTRAINT。迁移合并后只进不退,改错用新迁移修正。
相关文件:Go 侧规则在 go-idiomatic(references/database.md、references/patterns.md);迁移见 references/migrations.md;goose 仓库见 references/goose.md;含 sqlc.yaml 的仓库见 references/sqlc.md。其他限制或收费信息暂未提供。