goodbuddy/docs/development/database-migrations.md

数据库迁移与大数据升级指南

本文约束已发布用户数据的数据库升级。具体字段、存储表示和功能行为由对应功能文档负责； 本文不建立通用迁移框架、回滚引擎或独立状态日志。

先确认问题和数据边界

1. 先只读统计文件大小、WAL、页数、空闲页、表与字段的字节数，不先删除或压缩数据库。
2. 区分有效内容、重复存储、索引和已释放但未回收的空间。空闲页少时，单独 VACUUM 不能消除重复记录。
3. 查清实际写入、读取、删除、重放与恢复入口。修改 Runtime 相关持久化时，同时检查 本机和 GoodBuddy Agent 的桌面路径，不假设一个入口覆盖另一个入口。
4. 明确用户必须保留的信息、稳定 ID、顺序、时间、引用与远程去重字段。 分支内未发布、可安全重建的内部记录不需要兼容机制。

实现原则

• 先修新增数据路径，再修历史数据。历史转换与新写入尽量使用同一套转换函数。
• 普通 schema 变更使用既有 PRAGMA user_version 和 SQLite 事务； 已升级 schema 不允许旧客户端强行打开，不通过回写版本号支持降级。
• 大数据转换不得同步阻塞 Electron Main 或 Renderer。放到工作线程，在业务连接 打开前处理，并使用应用的共享字体、主题与页面组件显示进度和可执行的失败提示。
• 根据实测设置有界读取批次与缓存，批次提交后再报告进度。保持 SQLite 事务与 checkpoint，不靠关闭同步落盘、取消约束或一次性读入整库提速。
• 从已提交数据直接重试和还原即可完成的迁移，不增加 durable snapshot、journal、 receipt 或多阶段恢复状态。退出及失败至少回滚未提交批次，保留已完成部分。
• 差量编码必须能精确还原原始事件。更新内容、删除或重排都要覆盖；涉及远程来源时， 去重、冲突判断、消息投影和恢复序号不得失效。
• 释放数据库页和归还文件系统空间是不同步骤。先减少实际存储内容，再执行需要的 空间回收；保留足够临时空间，磁盘不足时明确失败并允许重试。
• SQLite 同库写入是串行的。是否增加读取／转换并行，应由实际读取、解析、写入、 提交与 checkpoint 的耗时决定，不把增加写线程当作默认优化。

验证与备份

合成回归

覆盖正常转换、无变化记录、重复打开、内容修订、失败事务和退出续跑。数据库大小问题 必须同时验证新增写入的增长量、旧记录可还原性以及文件实际缩小，而不只检查 schema。

真实旧库

1. 关闭占用源数据库的应用，确认 WAL 状态。没有 WAL 时可复制已关闭的数据库； 有活动 WAL 时使用 SQLite 一致性备份机制，不只复制主文件。
2. 备份到空间足够的位置，记录字节数并校验 SHA-256。备份和测试副本分离， 不直接在唯一原件或唯一备份上试跑。
3. 使用当前源码或用户要求的 portable 正常启动入口执行升级，不用手工 SQL 代替 产品升级过程。退出一次后重新启动，验证已提交数据可以继续处理。
4. 比较升级前后消息、任务、成果等用户表的内容；对转换事件逐条还原后比较原始内容、 ID、顺序、时间和去重来源，不只比较行数。日志只能包含统计和断言结果，不记录正文。
5. 运行数据库完整性检查，记录主文件和 WAL 的实际字节数、回收比例、耗时、平台、 源 schema 与目标 schema。确认原件和备份未被改写。
6. 运行 npm test、npm run typecheck、npm run lint；生产构建变化按开发验证规则 检查，发布准备则遵循发布手册，不重复本地打包。

发布与维护

发布说明应告知升级范围、可能耗时、退出重试、额外磁盘空间和降级边界。不得把一个测试库 的回收比例当作所有用户都能获得的保证。功能文档记录具体转换规则，进度文档记录实际 证据和未完成项；未经验证的阶段不能标为完成。

已有实例

• Desktop 0.13.1：子任务累计过程重复保存导致数据库膨胀，转换到 schema 34 的差量事件 表示，并回收空间。具体规则见 执行记录存储与升级回收， 数据保留与真实旧库验证见工作栏进度。