postgresql

PostgreSQL

工作规则

• 在保真度很重要时，将原始字节保留为字节；为查询单独选择解析后的类型。
• 将已部署的迁移视为不可变，并在发布期间兼顾新旧应用版本。
• 数据回滚需要来源信息。 按目标值选择行，也可能选中正向迁移从未触及的行。如需可逆性，应保留受影响的标识和原始值，并明确规定后续写入的处理策略。使用将读取已恢复数据的应用版本验证数据是否已还原。
• 检查锁定时长和事务范围；保护读-改-写路径，避免并发更新。
• 让索引谓词和 NULL 语义与每个写入方及迁移查询保持一致。
• 使用有代表性的数据和实际执行计划衡量查询变更；将数据库结果作为不变量进行验证。

数据类型默认值

需求	使用	避免
主键	BIGINT GENERATED ALWAYS AS IDENTITY	SERIAL、BIGSERIAL
时间戳	TIMESTAMPTZ	TIMESTAMP（会丢失时区）
文本	TEXT	VARCHAR(n)，除非需要约束
金额	NUMERIC(precision, scale)	MONEY、FLOAT
布尔值	带有 NOT NULL DEFAULT 的 BOOLEAN	可为空的布尔值
JSON	JSONB	JSON（不支持索引）、文本形式的 JSON
UUID	gen_random_uuid()（PG13+）	uuid-ossp 扩展
IP 地址	INET / CIDR	文本
范围	TSTZRANGE、INT4RANGE 等	成对的列
原始字节（原样载荷）	BYTEA	JSONB、TEXT（二者都会重新编码）

规范中写着“记录原始响应”，意味着需要保留字节保真度，而文本类型无法做到这一点。JSONB 会重新解析：它会删除无意义的空白、对对象键排序、仅保留重复键中的最后一个，并将指数表示法的数字改写为非指数形式（1e0 -> 1；1.00 中的尾随零会保留，因此说“所有数字形式都会合并”并不准确）。非 JSON 请求体根本无法存储，通常会变成 NULL。TEXT 会拒绝 NUL 字节以及任何在数据库编码中无效的序列，因此二进制或编码错误的请求体会报错，而不是被存储。将字节存储在 BYTEA 中，并在旁边保存内容类型；如需查询，再单独添加解析后的 JSONB 列。把列类型当作请求体已被保留的证据，是审查中的错误。

验证

从使用 EXPLAIN 检查变更后的查询开始。只有在执行查询及其副作用已获授权且安全时，才使用有代表性的数据运行 EXPLAIN (ANALYZE, BUFFERS)。对于写入操作，优先使用可丢弃的数据；仅当所有相关影响都属于事务性操作时，才使用先运行事务再回滚的方式。调查意外的顺序扫描并比较实际成本；如果读取表中大部分数据比使用索引更便宜，则应接受顺序扫描。结束前确认不存在未建立索引的 FK 列。

任务专属参考资料

实施或审查对应行为前，请阅读相关参考资料：

• 对于表设计、约束、架构变更或回填：schema-and-migrations.md。
• 对于索引、查询计划、JSONB、分页或查询反模式：query-and-index-patterns.md。
• 对于 RLS、事务边界、锁、分区、连接池或运维功能：security-and-operations.md。

适用主题对应的现有专项参考资料：

• operations.md。
• concurrency-patterns.md。
• full-text-search.md。
• performance-patterns.md。