← 返回首页

数据库与迁移规范

Managed Schema 从单一 descriptor 和 Catalog 派生当前物理清单：411 张受管表、备份 payload 410 张、ACCESS EXCLUSIVE 锁目标 411 张。迁移 Journal 当前包含 85 个不可变 SQL（0000_full_system 至 0084_relationship_radar_category_indexes），不是业务完成度指标。

0077、0078、0079、0080、0081、0083 的历史 SQL 保持原始字节不变；其中文用途由 apps/api/drizzle/meta/migration-documentation.json 旁注按迁移执行器相同的 LF 规范化规则绑定固定 SHA-256。旁注缺失、摘要变化或范围扩充均使门禁失败，新增迁移仍必须以中文文件用途头开头。字典编码迁移与人物别名历史进入完整备份和恢复锁集合，不得遗漏。

migration_ledger 进入 managed/锁定/指纹合同，payload 固定为空，恢复 preserve；auth_session payload 固定为空；backup_manifest 不递归进入 payload 且 preserve。Record Kernel 继续使用 record_core、record_revision、feature_execution；0010 只追加可空 revision module、memory_text_entry_v2、record_migration_operation 和 maintenance_state，不复制或切换业务数据。

Batch 004 的 0010 继续保持 Expand-only：只追加 record_revision.module_code 可空边界、memory_text_entry_v2、record_migration_operation 与 maintenance_state，不执行旧业务数据 UPDATE/DELETE/COPY/DROP，也不切换 MEM-001 或运行主链。

普通数据库写入通过持久化维护状态与 shared transaction advisory lock 失败关闭；维护激活把数据库操作互斥锁、active 状态、exclusive 排空锁和 operation 的 PostgreSQL 排空证据放在同一外层事务，超时、台账冲突或证据失败都会整体回滚。Capture 长流程使用 session shared lease，避免在 Provider 或长计算期间持有长数据库事务。

Batch 005R 已实现 Catalog 固定的 24 模块/72 来源表映射、版本化 canonical JSON、七类 reconciliation、Planning/Frozen Preflight、只复制 legacy_only 的 Copy、响应丢失精确重放和新事务独立 Verify。Frozen/Copy/Verify 会在数据库事务内复核 running operation、maintenance owner 与 PostgreSQL drain proof，并按固定顺序取得来源/目标表锁；台账只保存计数和 SHA-256，不保存业务正文。

迁移阶段仍固定为 preflight → maintenance → copy → verify → cutover → runtime_acceptance → completed。文档生成器不执行数据库迁移、Copy、Verify 或恢复演练；这些状态必须读取同一轮独立运行报告，不能从源码存在或本机工具可用性推导。

0074_system_feedback 只 CREATE 新表、索引、trigger 和权限，不 UPDATE/COPY/DELETE/DROP 既有业务数据；这只说明迁移形态，不自动证明任意旧 API 与新 schema 业务兼容。

备份窗口分为 pre-cutover、migration-window 和 post-cutover。pre-cutover 在迁移 operation 尚未开始时，按 migration_ledger 最后一条 passed 记录绑定历史 schema generation；因此待迁移数据库可以安全导出当时实际存在的表，而不会伪造当前 Journal 最新清单。migration-window/post-cutover 仍必须绑定当前完整 schema、running/passed operation 与 active/inactive maintenance。

0000_full_system 至 0084_relationship_radar_category_indexes 后列合同状态为 已验证（Two independently initialized PostgreSQL 16.15 instances, migrations 0000-0084, measured 2026-09-30; docs/验证报告/2026-09-30-第四轮PostgreSQL与性能修复.md）。备份创建与恢复会核对目标 PostgreSQL 的实际列指纹，不匹配即失败关闭；记录的列数 5318 不能冒充真实物理合同。payload v4 记录 schema generation、managed-schema 版本、列/约束 fingerprint 和 migration_ledger 的源物理 schema fingerprint，后者由三者共同重算绑定。

恢复仍依赖目标数据库中的 backup_manifest、SHA-256、不可变迁移前缀和历史 ledger target fingerprint；post-cutover 还依赖源迁移 operation 已在目标数据库中保留为 passed/completed。运维事实表不从 payload 恢复，历史 pre-cutover 恢复只把迁移后新增表保持为空；0035 前快照保留当前授权控制面并只补入无角色禁用用户。

恢复在 v4 Manifest、owner、迁移台账与窗口校验后，在既有排他锁内预检已知不支持的内容：传入的字典编码迁移或人物别名历史，以及已审阅无条件删除守护保护的非空目标，均在首个 DML 前拒绝。只核对启用、行级、无 WHEN 条件的实际 public DELETE 触发器，不扩大条件守护。其他 typed 域尚未证明可完整重放，仍可能被原约束拒绝并整体回滚；本次不引入新备份格式、离线灾难恢复、证明导出或数据库切换。

备份文件创建拒绝根目录本身的链接；可信祖先链接允许解析，但其最终物理根身份必须保持不变。创建使用 0600 权限的独占 no-follow 句柄写入并同步、关闭后再登记 Manifest；读取和列表同时复核文件 inode、根目录身份与物理包含关系，不能只凭文件 inode 接受移出目录后的同一文件。列表在空目录、元数据读取和成功审计事务中复核配置根；审计期间已检测到漂移则共同回滚。失败清理只删除本轮仍处于原物理根和路径的文件，无法证明身份时保留现场。若根恰在底层 open 期间被替换，可能留下未写内容的空文件；发现后不得写入备份字节、登记 Manifest 或通过不可信路径盲删。可移植 Node 路径复核不是内核级目录事务；备份根目录及其祖先必须由可信进程管理，不能授予不可信主体并发重命名权限，本次不宣称已消除任意操作系统级命名空间竞态。

迁移执行与 API 启动

显式 pnpm db:migrate 是生产 apply 入口；PostgreSQL API 默认且生产只允许 DATABASE_MIGRATION_MODE=validate-exact。启动校验使用 shared advisory lock 与合作式迁移命令瞬时互斥，验证台账与源码同代及当前表/列/约束 fingerprint；0074 还精确核对其 trigger（含 WHEN 条件）、trigger function body、普通/partial index 的访问方法与有效状态和默认反馈权限种子，随后释放锁。它不在 API 生命周期持续持锁；其他历史迁移尚未声明同等级的非表对象合同，不能把本项扩写成所有历史普通索引、function、grant 均已覆盖。

当前没有 validate-compatible。两槽只有在同一数据库迁移代际时才能共享数据库；含迁移发布不得把旧代码目录当作可直接回滚点。逐版本前向兼容必须另有不可变兼容清单、真实双版本读写/worker 测试和人工审批。

真实 PostgreSQL Runner 按 Journal 顺序、LF 归一化 SHA-256、managed 清单和 advisory lock 失败关闭；迁移 SQL 与 passed 在同一事务提交，既有库 baseline 必须通过表、列和约束 fingerprint。解锁失败会销毁连接，禁止持锁 session 回池。pg-mem 不伪造 PostgreSQL lock、排空证明或恢复合同。

历史 descriptor 中的 PostgreSQL 16 列合同只证明当次物理测量，不替代本轮 system-feedback owner/trigger/lifecycle 集成测试或登录态浏览器验收；本轮 focused PG16 与 PC/H5 登录验收未执行时必须分别记为 not_run。