Hindsight 0.7.1 Postgres 升级风险与方案 C 规划
Hindsight 0.7.x 解决了 entity links O(N²) 膨胀方向问题，但 v0.7.1 官方包在本机 Postgres 升级路径上存在 migration 硬阻塞；当前不建议直接升级 live。
0.7.x 值得跟进，但 v0.7.1 官方 migration 原样不能作为本机 production cutover 依据。
先向 vectorize-io/hindsight 提 issue；若走方案 C，则采用 patched 0.7.1 + cloned DB rehearsal + clone-and-swap。
rehearsal-only 的普通 DDL 补丁只证明 runtime 可用，不能直接用于生产升级。
关键判断
| 判断项 | 摘要 |
|---|---|
| 推荐方案 | 保持 live 0.6.2；向上游提交 issue；等官方修复或先做可审计 production patch，再 fresh rehearsal。 |
| 关键依据 | isolated 0.7.1 在补丁后 health/retain/recall/consolidation 通过，但官方 migration 原样失败。 |
| 落地方式 | 方案 C 采用 patched package、cloned DB、batch cleanup、clone-and-swap cutover，不做 in-place 硬升。 |
| 风险边界 | 官方包目前缺 psycopg，且多处 DROP/CREATE INDEX CONCURRENTLY 运行在 Alembic transaction block 内。 |
证据摘要
- 上游 #1887：0.7.x redesign 解决 entity links O(N²) 膨胀。
- 本机 rehearsal：entity links 从 39372 清零，0.7.1 runtime 功能验证通过。
- 阻塞日志：
ModuleNotFoundError: No module named 'psycopg'与DROP INDEX CONCURRENTLY cannot run inside a transaction block。 - 上游对比：main 与 v0.7.1 相关 migration 文件相同，尚未修复。
- 已提交 issue：vectorize-io/hindsight#1902。
行动清单
vectorize-io/hindsight 提交 GitHub issue：#1902。边界 / 风险
官方 migration 可能让 API 启动失败，并把 alembic_version / 索引状态停在中间态。
普通 DDL 会锁表；生产应优先使用 autocommit + CONCURRENTLY，或拆出手工 batch cleanup。
不要依赖 downgrade migration；使用旧 venv + 旧 DB + final dump 做快速回滚。
完整记录
Hindsight 0.7.1 Postgres 升级风险与处理规划
1. 背景
本机当前 live Hindsight：
本次任务是评估上游 0.7.1 是否值得升级，以及是否能安全从本机 live 0.6.2 迁移过去。
隔离演练路径：
live 8889 和 live DB 未直接修改。
---
2. 0.7.x 解决的问题
上游 issue #1887 指出，0.6.x 中 memory_links 的 link_type = 'entity' 行会按高频实体近似 O(N²) 增长，导致表膨胀、dead tuples、stats 慢查询、CPU 飙高和连接池耗尽。
官方在该 issue 中说明，0.7.0 已重新设计：
- entity edges 不再物化为
memory_links行； - entity relationships 改为从
unit_entities按需派生； - migration
e9b2c7d1f3a4_drop_entity_memory_links会删除既有entitylinks。
本机 rehearsal DB 迁移前后验证：
说明 0.7.x 的方向和目标是有效的。
---
3. 本机实测阻塞点
3.1 缺少 psycopg
hindsight-api-slim 0.7.1 安装后包含：
但启动 migration 时 SQLAlchemy 使用 postgresql+psycopg 路径，报：
补救方式：
3.2 CONCURRENTLY 在 transaction block 中执行
补 psycopg 后，migration 继续失败：
已撞到的 revision：
继续扫描上游 v0.7.1/main 发现同类写法还存在于多个 migration：
上游 main 与 v0.7.1 的相关 migration 文件对比结果为 SAME，说明截至本次检查时，上游 main 尚未修复该问题。
---
4. 隔离验证结果
为了验证 0.7.1 runtime 本身是否可用，本次只在 isolated venv + copied rehearsal DB 中做 rehearsal-only patch：
这不是 production 方案，只用于确认 runtime 能力。
补丁后 isolated 0.7.1 启动成功：
验证通过：
关键结果：
---
5. 对 live 的影响
短期：本机 live 仍健康，当前 rehearsal DB 规模较小，不是马上要抢修。
中长期：继续停留在 0.6.2 会保留 entity links 膨胀风险。如果后续 retain、历史回放、consolidation 增加，memory_links 表可能持续膨胀。
直接升级的风险更高：如果直接在 live DB 上跑官方 0.7.1 migration，可能出现 API 启动失败、alembic_version 半路状态、索引部分删除、DB schema 中间态等问题，回滚不能只退 Python 包，可能需要恢复 dump。
---
6. 方案 C：patched 0.7.1 的规划
6.1 原则
不做 in-place 硬升。采用：
6.2 Patch 范围
只修 migration/依赖，不改业务逻辑。
- 补依赖：
- 修
CONCURRENTLYmigration：
将：
改为：
- 单独处理
e9b2c7d1f3a4的 entity cleanup。
生产更稳的方式是将大规模 entity links 删除拆成可观测 batch cleanup：
循环直到 0 行，并在结束后：
6.3 Rehearsal 要求
fresh dump 新建 rehearsal DB，必须验证：
还要记录：
6.4 Cutover 策略
生产采用 clone-and-swap：
- 维护窗口开始，停止 Hindsight API 写入；
- final dump live DB；
- 恢复到新 DB，如
hindsight_071_prod_candidate_<timestamp>； - patched 0.7.1 指向 candidate DB 跑 migration；
- isolated API 验证通过；
- systemd/env 切换到 patched venv + candidate DB；
- live
8889验证通过； - 保留旧
0.6.2venv、旧 DB、旧 env 和 final dump 作为回滚点。
6.5 回滚
不依赖 downgrade migration，直接切回旧 venv + 旧 DB：
---
7. 建议
当前建议：
如果后续继续推进方案 C，应先把 patch 做成可重复脚本/本地分支，并至少完成两次 fresh rehearsal，再安排生产维护窗口。
---
8. 证据与路径
本机审计目录：
关键文件：
上游相关：
---
9. 当前执行状态
本记录生成时间：2026-06-01 18:31:18 CST。
本记录用于 wiki / HTML / Hindsight retain pointer 归档，并作为向上游提 issue 的依据。