Skip to content

refactor(db): 迁移异步数据库操作与事务边界 - #105

Merged
xiaoland merged 16 commits into
mainfrom
refactor/async-database-boundaries
Sep 19, 2026
Merged

xiaoland merged 16 commits into
mainfrom
refactor/async-database-boundaries

Conversation

@xiaoland

@xiaoland xiaoland commented Sep 17, 2026 •

Copy link
Copy Markdown
Member

当前 async HTTP、Resolver 和后台任务曾直接执行同步 SQL,多个 Manager 又用可选 session 参数切换事务所有权。此变更将业务数据库 I/O 迁移到原生 async,并以用例拥有的短 UoW 明确提交和回滚边界。

  • app/business 保留业务编排;app/persistence 持有 session-bound repositories 与事务工厂。HTTP 通过业务入口访问数据库,并发 task 各自拥有 UoW。
  • 覆盖配置、AI/Agent、Peer、Graph/Storage/Resolver、Host、Source/Sink、Job/Cron、六个采集/协议扩展、检索、Organization 和 MCP。删除同步工厂、旧 CRUD Manager 和可选 raw session 接口。
  • flat graph 批量写入 Blocks/Relations,检索投影按 batch upsert;外部 AI/网络等待在数据库作用域外。Source checkpoint 与对应 graph 原子提交,Cron occurrence 与 Job 同事务,保留原有逐项 partial effects。
  • PostgreSQL 日志经有界队列独立异步批量写入;关闭时先保护 Job 已开始的 terminal transaction,再排空其余调度回调和日志,最后释放连接池。readiness 明确保留线程内独立 psycopg 适配器,与 CLI 共用 contract 检查。
  • 全 runtime 数据库 import lint、AST ownership 检查、Unit TDD 和局部指南共同维护边界;规则独立于根 Ruff 通用配置。

依赖 ext-reg #38、#39 已合并并正式发布,Core 锁定 Runtime SDK 0.1.5。Host 合同推进到 0.2,七个 first-party wheel 声明匹配窗口;旧同步 wheel 必须先停用并升级,新 immutable artifact 版本仍由正式 Release PR 准备。

本地验证:完整 pdm run check 通过;隔离 PostgreSQL 回归覆盖 Graph/blob 回滚、配置 HTTP、AI/Agent/Peer、组织行为、Memos/RSS、检索,首轮 38 passed/2 skipped,fixture 修复后的目标复验通过;三项无需真实 AI 凭据的语义纵向验收通过。任务 probes 验证 Job/Cron 并发与取消、扩展 state/config 生命周期、采集 checkpoint、导航、MCP、日志隔离和 shutdown drain。OpenAPI 无差异,无 schema migration。

Mail graph/checkpoint 已验证;本轮未运行依赖专用 Dovecot distribution 和命名 disposable database 的完整 IMAP 验收。已提供 scripts/benchmark_database.py:100 Blocks/99 Relations、30 次提交及批量读取,在本任务隔离 PostgreSQL 上并发 1/8 分别为 9.127/51.354 graph/s,两次零错误。原始延迟和环境记录在 task packet;没有旧版对照,不宣称相对同步版本的提升倍数。

最终提交 52d59239ce6d34c7379f563d73c51a3047b7a4f4 已通过全部远端验收:repository/artifact/portable-runtime、preview database、preview application 部署及线上探测。PR 已按后续授权合并。执行计划及逐步证据见 tasks/async-database-boundaries/。

交付完成:#105 合并为 5b8dbf8,Release PR #106 合并为 2c4be48,发布 Core 0.4.0 及七个匹配 Host 0.2 的扩展版本。生产部署与探测 全部成功,stable 已更新为 sha256:111be24909a3de44dfd779080606dce6e4642d091245a3004b4d3f25fd4de1ca。任务实施与交付已完成,task packet 保留为已完成任务的历史证据。

- repository 和 UoW 工厂归入 app/persistence,business 保留用例入口
- 实体批量读取通过应用用例,数据库 lint 使用独立配置
- 记录 SDK 合并发布及现有 PostgreSQL 验收结果
- 采用正式 SDK 0.1.4,拆分 Extension state 用例和 session-bound repository
- 迁移 Host、Twitter state/config 消费者和 Source catalog,保留锁与 enabled RPC
- 验证并发、回滚、取消清理与补偿,隔离 Host 0.2 兼容窗口
- 记录 callback SDK 修复 #39 的正式交付依赖
- 验证公开 route 的启动、取消和重启
- 关闭步骤 05 artifact 阻塞,进入 Source 与 Job/Cron 迁移
- 在 persistence 组合短事务,保留 Cron 与 Job 的原子创建
- 异步化执行资格检查,验证并发领取、取消收尾与回滚
- 扩大数据库边界 lint 并适配既有验收调用
- 通过必需的 UoW 组合 graph、storage 与 Source checkpoint
- 保持协议定义的部分提交与清理语义,修复 Twitter checkpoint 提前推进
- 验证 Memos 附件并发归属及采集失败回滚,扩大边界 lint
- 将检索 SQL 与批量投影写入移入 persistence
- 明确组织行为事务边界并迁移图导航调用链
- 验证重放、回滚、媒体解释和导航约束
- 使用有界队列和独立异步事务持久化日志
- 排空调度回调及日志后释放数据库连接池
- 明确 readiness 的隔离同步适配边界
- 完成 MCP 数据库调用链与旧 factory/session API 清零
- 将测试数据准备移入独立适配器,业务验收调用异步入口
- 通过全 runtime lint 和结构检查维护持久化及事务职责
- 参数化图规模和并发,记录提交与批量读取延迟
- 精确清理本轮数据并保存隔离环境测量证据
- 先排空 Job,再取消其余调度回调
- 收尾阶段拒绝重复取消,停止 admission 后拒绝新 claim
- 验证 terminal write 与 shutdown 的交错
- 更新最终迁移清单并区分历史阶段证据\n- 记录已通过的代码检查与待完成的 preview 交付
@xiaoland
xiaoland marked this pull request as ready for review September 19, 2026 05:41
@xiaoland
xiaoland merged commit 5b8dbf8 into main Sep 19, 2026
7 checks passed

This branch was successfully deployed

1 active deployment
preview — 52d59239 Deployed Sep 19, 2026 by xiaoland via Retire preview resources #311
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant