Skip to content

[FEATURE] 兼容 callstack 去重前后的 DB schema:v1 旧库直接只读查询/focus,不迁移 #134

Closed

Description

@codeasier

功能描述

callstack 去重优化(#113 / PR #114,commit 9e1095a)将调用栈文本移入共享 callstack 表、由 callstackId 引用,SnapshotDB schema 由 v1 变为 v2。当前没有兼容层:旧版本 import/focus 的 DB 在升级 pt-snap 后被 IMPORT_FORMAT_VERSION=2 / import_format_changed 门控拦下,无法继续分析。

希望的是同时支持 v1 和 v2 两种 schema 的读取:v1 旧库无需重新导入或迁移,可直接 query / focus;且 focus(打开)旧库时应保持只读,不对 DB 做任何写入或原地迁移。

使用场景

  • 用户此前用旧版导入并 focus 过 DB(如 628k 事件大库,去重前 DB ~5.95GB),升级后旧工程直接失效;原始快照可能已归档/删除,重新导入成本高甚至不可行。
  • DB 文件可能被多处引用或共享,隐式迁移会改写原文件,影响仍在用旧版工具/脚本的场景;只读打开保证无副作用。
  • CI / 自动化脚本、报告中引用的旧 DB 路径升级后全部 break。
  • 团队内 pt-snap 版本不一致时,各自产出的 DB 无法互相分析。

期望的实现方式

  1. 读取侧按 import_metadata 识别 v1/v2,两条读取路径共存:
    • v1:走旧 inline-TEXT 解析路径(直接读 callstack 文本);
    • v2:走 callstackId JOIN 共享 callstack 表。
  2. query / focus / 查询模板等读路径对 v1 库全部可用,效果与旧版本一致。
  3. focus 及打开旧库全程只读:不写库、不改文件、不隐式迁移。
  4. 若未来提供 v1→v2 迁移,只能是显式 opt-in(独立命令或参数),默认关闭。
  5. 若个别功能确实无法支持 v1,明确报错并说明原因,而不是笼统地拒绝分析。

示例

pt-snap query legacy.db   # v1 旧库:应可直接查询
pt-snap focus legacy.db   # v1 旧库:只读聚焦,不做 schema 迁移、不写回文件

参考资源

验收标准

  • v1(去重前)DB 可直接 query / focus,无需重新导入或迁移
  • focus / 打开 v1 库全程只读(不写库、不改文件)
  • 若提供迁移能力,必须显式 opt-in,默认不触发
  • 测试覆盖新旧双 schema(旧格式 fixture + 新格式 fixture)
  • 文档说明双 schema 支持范围与只读保证(docs/zh/database.md、docs/en/database.md)

Activity

  1. changed the title [-][FEATURE] 兼容 callstack 去重前后的 DB schema:旧版本导入/聚焦的 DB 升级后可继续分析[/-] [+][FEATURE] 兼容 callstack 去重前后的 DB schema:v1 旧库直接只读查询/focus,不迁移[/+] on Sep 17, 2026
  2. codeasier commented on Sep 17, 2026

    @codeasier
    OwnerAuthor

    评审结论:支持增加 v1/v2 双 schema 的只读读取兼容。旧快照可能已不可获取,要求重新导入不足以覆盖历史数据库的使用场景。建议修正现状描述,并采用「共享模板契约 + v1/v2 SQL 变体 + Context 自动识别」方案。

    已核实的现状

    • import_format_changed 是导入缓存未命中原因,并非 focus/query 的统一版本门控,见 src/pt_snap_cli/core/import_metadata.py:218。
    • focus 当前可以打开旧库;Context 校验 dictionary 表,并使用 SQLite mode=ro,见 src/pt_snap_cli/context.py:69、:141。
    • 真正的兼容性缺口在 event、callstack_analysis、active_memory_callstack_at_event 三个模板:它们直接依赖去重后的结构,旧库会收到要求重新导入的错误。依赖调用栈模板的报告也受影响。

    用合成 SQLite 数据库复现:无 metadata 的 inline 库、format=1 的 inline 库、format=2 的去重库均可 focus,并执行 memory_peak;前两类执行上述三个模板均失败,v2 均成功。操作前后数据库 SHA-256 与 mtime 均未变化。相关定向测试 59 passed。

    建议方案:自动选择 v1/v2 模板

    1. 对外保持相同模板名、参数和输出契约,例如用户始终使用 event;内部根据数据库布局选择 v1 inline SQL 或 v2 callstackId/JOIN SQL。
    2. 只为存在差异的三个模板增加 v1/v2 SQL 变体,无需复制所有模板。建议在同一模板配置内增加 query_variants.v1 / query_variants.v2,共用 description、parameters 和 output_schema;不受影响的模板继续使用单个 query。此配置形式需要新增支持。
    3. Context 通过只读检查所选设备的 trace_entry 表列及共享 callstack 表识别布局。实际元数据表名是 pt_snap_metadata,可作为辅助校验,但不能成为唯一依据:历史或外部生成的库可能没有 metadata。对未知、损坏、元数据与结构冲突的情况明确报错。
    4. focus 时提前识别和验证,并可展示识别结果;查询时也必须能独立识别,覆盖显式 DB 路径及 API/MCP 无项目 focus 的调用方式。QueryExecutor 统一选择 SQL 变体,CLI、Python API、MCP 和报告共享该行为。
    5. 识别结果缓存在 Context 中,随数据库身份/文件签名变化及现有 Context 缓存失效机制重新检测,不将版本固化到 focus.json。保持 v2 按 ID 聚合等优化,避免兼容方案导致性能回退。

    边界与验收建议

    • 只读保证针对数据库文件:focus 仍需正常保存 .pt-snap/focus.json,但打开、查询旧库不得写库或隐式迁移。读取兼容无需取消导入时的版本缓存失效策略;迁移能力若提供,必须显式 opt-in。
    • 本次保证是新版工具读取两种布局,不延伸为旧版工具读取新库,也不承诺自动改写用户自定义 SQL。
    • 测试覆盖 v1/v2、有无 metadata、多设备、结构异常,以及数据库替换后的重新识别。
    • 对三个模板及报告验证结果语义,包括空/缺失调用栈、聚合、排序、分页与总数;增加 CLI/API/MCP 契约覆盖。
    • 增加只读连接、数据库内容和 mtime 不变的断言,并保留 v2 查询性能验证。
    • 更新 docs/en/database.md 与 docs/zh/database.md,说明双 schema 支持范围及只读保证。

    示例查询需指定模板:

    pt-snap query legacy.db --template-use event
    pt-snap focus legacy.db
  3. added 2 commits that reference this issue on Sep 17, 2026
    de1b385
    53f2196
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions