Beads 存储层 Schema 一致性守卫与连接池迁移修复实战从 be-krza3 发布门禁看 CLI/Runtime 模式对齐工程【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beadsBeads 为编码 Agent 提供嵌入式 Dolt 数据库存储其 schema 通过 SQL 迁移流演进而 CLI 侧则内置同一套 schema 的 DDL 模板。为了确保CLI 打包的 schema 与运行时实际提交的 schema 永远一致项目引入了一个名为schema_cli_parity_integration_test.go的模式一致性 oracleparity oracle测试。本文以发布门禁 be-krza3-schema-parity-pool-heal-gate.md 为线索深入剖析该 oracle 的工作原理、它曾暴露的两类假性不一致缺陷ignored-stream 列误报、Go map 迭代顺序导致的随机空读以及一个被逐字节 cherry-pick 进来的连接池迁移修复be-itm5 的rebuildPoolAfterMigration。读完本文你将理解 Beads 如何用双快照对比守护数据库 schema 演进如何消除测试中的非确定性以及一个严谨的发布门禁release gate如何通过 8 项标准判定一个修复是否具备合入资格。一、背景Beads 的 Dolt 存储层与 schema 治理Beads 的核心存储位于 internal/storage/dolt其底层是嵌入式 Dolt一个类 MySQL 的版本化数据库。所有持久化对象——issue、wisp、lease、metadata、repo 元数据等——都落在 Dolt 数据库中schema 的演进完全由迁移migration驱动。schema 治理有两个关键约束运行时 schema由store.initSchema在打开数据库时执行迁移得到迁移 SQL 由schema.AllMigrationsSQL()统一提供见 internal/storage/schema。CLI 侧 schemaCLI 内部预置了同一套 DDL 模板如 internal/storage/schema/cli_prepared_ddl.go供各种命令准备语句使用。两套 schema 来源不同却必须保持完全一致——如果 CLI 预置的 DDL 与运行时迁移出的真实 schema 出现漂移会导致命令执行 SQL 报错、结果集字段不匹配等隐蔽故障。为此项目用集成测试TestCLIBundleMatchesRuntimeCommittedSchema位于 internal/storage/dolt/schema_cli_parity_integration_test.go充当oracle分别从 CLI 侧和运行时侧采集 schema 快照逐行对比。二、Parity Oracle 的工作原理双快照对比oracle 的核心思想非常直观对同一个 schema 分别从两个源头生成规范化文本快照然后逐行比较。2.1 快照查询集committedSchemaSnapshotQueriescommittedSchemaSnapshotQueries 定义了一组针对information_schema的查询覆盖 5 个维度维度查询内容关键输出字段tables表清单表名 表类型columns列定义表名、序号、列名、类型、可空性、默认值、extra、生成表达式indexes索引定义索引名、列序号、非唯一标志、子分区、可空、索引类型constraints约束定义约束名、类型、键列序号、引用表/列、更新/删除规则version迁移版本schema_migrations中的最大迁移号每行输出都被拼成一条规范化文本例如列维度SELECT CONCAT(column|, c.table_name, |, LPAD(c.ordinal_position, 3, 0), |, c.column_name, |, c.column_type, |, c.is_nullable, |, COALESCE(c.column_default, NULL), |, c.extra, |, COALESCE(c.generation_expression, )) AS line FROM information_schema.columns c JOIN information_schema.tables t ON t.table_schema c.table_schema AND t.table_name c.table_name WHERE ...LPAD(..., 3, 0)与COALESCE(..., NULL)都是为了让同一 schema 在两边产生逐字节一致的文本从而可直接用sort.Strings排序后用 diff 比较。2.2 两条采集路径测试TestCLIBundleMatchesRuntimeCommittedSchema在临时目录中构造两个并行的 Dolt 环境CLI 路径dolt init 执行schema.AllMigrationsSQL()然后用 dolt CLI 跑同样的快照查询得到cliCommittedSchemaSnapshot运行时路径通过New()打开一个真实 DoltStoreCreateIfMissing: true触发initSchema执行迁移直接对store.db跑快照查询得到runtimeCommittedSchemaSnapshot。两者都调用sortedSnapshotQueryNames按固定顺序执行 5 类查询最后sort.Strings后由firstSchemaSnapshotDiff找出第一处差异。若存在差异则t.Fatalf测试失败——这就是oracle 报警。三、缺陷剖析oracle 为何产生假性不一致be-krza3 门禁文档的 Scope 部分明确指出这个 oracle 存在两个缺陷会误报false parity mismatch而不是漏报3.1 缺陷一ignored-stream 列无法表达Beads 存在一个被忽略的迁移流ignored migration series。该流拥有的对象分为两个层次整张表wisps以及wisp_前缀的表还有ignored_schema_migrations、local_metadata、repo_mtimes等元数据表挂在主线表上的单列例如leases.granted_node由migrations/ignored/0016_add_lease_granted_node.up.sql添加。而schema.AllMigrationsSQL()只遍历主线迁移序列没有对应的 ignored 系列 bundle 可与 CLI 侧配对。如果 oracle 不过滤这些对象它们会在运行时侧出现、而 CLI 侧缺失被误读为only in runtime的假性漂移。oracle 的过滤谓词如下以tables为例WHERE t.table_schema DATABASE() AND t.table_name NOT IN (ignored_schema_migrations, local_metadata, repo_mtimes, wisps) AND LEFT(t.table_name, 5) wisp_ AND LEFT(t.table_name, 5) dolt_columns维度额外增加了一行针对单列的排除AND NOT (c.table_name leases AND c.column_name granted_node)值得警惕的是这种排除是有代价的文档记录到迁移 0065 的wisp_comments.text宽度漂移曾持续 6 天而 oracle 无法发现ga-61ruw因为该列属于 ignored 平面。因此文档强调正确方向是给 CLI 侧补一个 ignored 系列 bundle而不是删除这些谓词在实现之前cli_prepared_ddl.go中的源码级守卫masking-proof guard负责覆盖这类漏洞。3.2 缺陷二Go map 迭代顺序导致的随机空读committedSchemaSnapshotQueries返回的是map[string]string。修复前两个快照采集器直接for name : range queries迭代 map而Go 的 map 迭代顺序是随机的。文档与代码注释sortedSnapshotQueryNames解释了这个问题的微妙之处运行时侧的快照查询经由一个 Dolt 会话读取而该会话的 root 只在查询成功之后才前进be-itm5 行为。直接 range map 会让每次调用中谁先执行随机变化——先执行的那个类别可能读取到尚未就绪的状态被记录为空。于是同一个类别的查询在每次运行时可能随机读到空结果产生间歇性、不可复现的假性不一致。3.3 修复方案静态排除 确定性排序修复包含两处均为测试代码改动静态排除子句在 5 个快照查询中加入上述NOT IN/LEFT(...)/NOT (...)过滤明确表达oracle 只对比主线迁移流sortedSnapshotQueryNames辅助函数把 map 的 key 先收集进 slice 再sort.Strings保证两个采集器以固定顺序执行查询func sortedSnapshotQueryNames(queries map[string]string) []string { names : make([]string, 0, len(queries)) for name : range queries { names append(names, name) } sort.Strings(names) return names }两个采集器cliCommittedSchemaSnapshot与runtimeCommittedSchemaSnapshot都改为遍历sortedSnapshotQueryNames(queries)彻底消除了对 map 迭代顺序的依赖。四、关联修复be-itm5 的连接池迁移修复pool healbe-krza3 门禁的 Round-2 重做还包含了一个逐字节 cherry-pick的生产代码修复be-itm5 的rebuildPoolAfterMigration位于 internal/storage/dolt/store.go。4.1 问题本质会话 root 未随迁移前进bug 场景be-itm5 / be-jjv2 复现是一个执行了迁移的 store 打开流程让连接池store.db中的连接停留在了迁移前的 Dolt 会话 root上。第一次语句通过该过期连接读取时返回table not found而失败的查询不会推进会话 root所以错误不会在重试时自愈——只有某个无关的成功查询比如information_schema探测才会推进 root。这让故障表现为打开后第一读必失败且随机自愈极难排查。4.2 修复实现迁移后重建连接池func (s *DoltStore) rebuildPoolAfterMigration(ctx context.Context, applied int) error { if applied 0 { return nil } newDB, err : sql.Open(mysql, s.connStr) if err ! nil { return fmt.Errorf(rebuild pool after migration: %w, err) } applyPoolLimits(newDB, s.cfg) if err : newDB.PingContext(ctx); err ! nil { _ newDB.Close() return fmt.Errorf(rebuild pool after migration: %w, err) } old : s.db s.db newDB return old.Close() }关键设计点applied 0快速返回非迁移打开重新打开一个已迁移完成的库是最常见路径不支付任何重建代价也不触碰s.db——这是 be-itm5 的 Done-when 守卫迁移走独立连接池initSchema通过openMigrationDB这个一次性连接执行迁移store.go而 store 主池在打开早期已被启动 Ping 钉住一个连接无锁的池交换是安全的文档在 OWASP 审查一节专门论证了这一点——rebuildPoolAfterMigration只有单一调用点构造函数内部、发布前执行不存在并发读者因此s.db newDB无需加锁。4.3 为什么必须带上 store.go门禁文档解释了一个重要的工程判断Round-1 时有人主张 store.go 不属于本 diff 的授权范围scope但若把 store.go 还原到 be-itm5 之前的状态本轮的测试文件根本无法编译——post_migration_pool_heal_integration_test.go与connection_pool_test.go直接调用rebuildPoolAfterMigration。于是原始验收标准中的#3 非确定性消除与#4 不触碰生产文件机械矛盾。Round-1 审查者裁定包含 store.go 是正确解法Round-2 审查者则独立复核了这条授权链authority chain并用 RED/GREEN 复证不含 store.go 即编译失败而非照单全收。五、验证体系从纯 Go 单元测试到真实容器集成测试5.1 连接池生命周期单元测试无需 Dolt 服务器connection_pool_test.go 用进程内 mock drivermockDriver统计 Open/Close 次数钉住连接池不变量可在go test -short下运行。它覆盖 5 个维度恰好对应门禁中的 9 个 diff-owned 测试测试断言的不变量TestApplyPoolLimits_Defaults默认池参数MaxOpenConns10、MaxIdleConns5、ConnMaxLifetime1hTestApplyPoolLimits_OverridesConfig 非零字段覆盖默认值如 3/2/15minTestApplyPoolLimits_ClampsIdleToOpenMaxIdleConns不得超过MaxOpenConns否则database/sql会静默钳制TestPool_SequentialQueriesReuseSingleConnection两次顺序查询只 Open 1 次、Close 0 次——池必须复用连接TestPool_ConcurrentQueriesRespectMaxOpen8 个并发查询、池上限 2 时底层连接数不超过 2TestPool_CloseReleasesUnderlyingConnectionsClose()后所有已打开连接全部释放opens closesTestRebuildPoolAfterMigration_NoopWhenNotMigratedapplied0时不得打开新连接、不得触碰s.db这些测试的来源是一个真实的线上故障报告dolt-server.log 中出现无穷无尽的NewConnection/ConnectionClosed配对说明守护进程实际上每条查询都在新建*sql.DB。单元测试把连接复用固化为可回归的不变量。5.2 迁移后首读集成测试需要真实 Doltpost_migration_pool_heal_integration_test.go 中的TestMigratingOpen_FirstReadSucceeds是 be-itm5 的复现测试设计极其克制在New()返回后只发出唯一一条查询SELECT key FROM config因为第二条无关查询会通过推进会话 root直接掩盖 bug。测试断言首次读返回迁移后的 config 种子数据非 0 行。5.3 非确定性消除的复证门禁记录到Round-2 审查者独立运行TestCLIBundleMatchesRuntimeCommittedSchema -count5共 5 轮5/5 全 PASS证明 map 迭代顺序的随机性已被彻底消除。六、发布门禁Release Gate评估标准全解be-krza3 门禁文档的核心是一张 8 行#0–#7的评估表这是 Beads 项目修复必须过门禁才能合入的工程制度。以下完整继承并解释每一项#标准判定证据要点0预检是否已合入NOgh pr list --search无结果git merge-base --is-ancestor确认目标 commit 不在 main 上继续评估1是否存在 Review PASSPASS审查 bead be-8xjjg第 2 轮 verdictpass以 reasonpass关闭2验收标准是否达成PASSscope 授权链按文档化路径裁决而非人说了算uncovered_criteria: none-count5复证非确定性已消除3diff 自有测试是否全过SKIPFAIL 规则PASS9/9 PASS、0 FAIL、0 SKIP19.002s真实 Dolt 容器rootless podman执行非 SKIP 替代品rebase 后 deployer 独立复核gofmt -l/go build ./.../go vet ./...全干净3a非 diff 自有的既有失败归因PASS全包运行193 测试有 14 个 FAIL全部位于federation_test.go且非 diff 自有13 个是包级并行槽竞争下的既有超时约 45s 处第 14 个TestFederationDatabaseIsolation是已跟踪的 P0 be-3c78sbase-ref 对照运行逐条复现13 PASS 1 FAIL4 条归因子句全部满足3b策略 / lint 通道PASSgolangci-lint run0 issues——这是该 diff 上第 3 次独立的 gofmt/vet/lint 干净验证4无未决 HIGH 级发现PASS显式 OWASP Top 10 走查注入、认证、访问控制、XXE/SSRF/反序列化/XSS、错误配置、漏洞依赖、日志无 blocker/major/minorstore.go 无锁池交换的安全性已验证单调用点、发布前、构造函数内5分支是否干净PASS恢复 rebase 后git status --short为空6是否与 main 干净分叉PASSassert_deploy_ancestry_scoperc0无.claude/**路径所有 commit 都引用已接受的 bead idattempt_bounded_self_rebase0 冲突完成 rebaseBEFORE_SHAe0c39aa25...→ AFTER_SHA7d294b4b5...7单一功能主题PASSbe-0v3loracle 修复 被授权的 be-itm5 cherry-pick编译必需依赖范围内无杂散 commit6.1 值得借鉴的三个工程细节not caused by this diff 必须实证而非假设14 个既有失败通过 base-refmerge-base6ec78f3a2对照运行逐一复现且 4 条归因子句非 diff 自有、已跟踪、base-ref 已存在、无路径重叠全部满足——即使后来发现 be-3c78s 已由 PR #5836 修复也不追溯否定当时的快照判断。SKIP 不被当作 PASSdiff 自有测试 0 SKIP且容器真实执行杜绝了用 SKIP 顶替验证的造假路径。分支恢复有据可依worktree 的pre_start在轮次间把本地分支指针硬重置回origin/main但 rebase 产物 commit 对象仍在本地对象库git cat-file -e确认且 bead 笔记已记录 SHA 为持久状态因此用git reset --hard AFTER_SHA恢复而非重做随后对恢复后状态重新跑全部门禁检查。七、推送策略、合并权限与最终裁定推送目标origingastownhall/beads被哨兵配置DISABLED-upstream-is-fetch-only-push-to-fork-and-PR禁止推送headforkquad341/beads-sec003-contrib.git按本 rig 既定先例be-r3ysh接受推送。PR 以跨仓库方式对gastownhall/beads:main发起head 为quad341:deploy/be-krza3-gate。已知基建缺口 be-z3iuvattempt_bounded_self_rebase内部的 force-with-lease 推送仍硬编码指向origin脚本 rebase-resolve-lib.sh 第 489 行故本轮改用直接手动推送到headforkrebase 本身干净完成不受该推送 bug 影响。注意此路径为本机环境信息仅作为流程记录。合并权限gastownhall/beads对本 rig 是仅贡献者仓库rig 无合并权限deployer 的职责止于打开已核验的 PR门禁结果通过邮件上报 mayor。这是 be-vc1m、be-gd3v、be-79jh、be-39ss、be-pp7e、be-r3ysh 等先例确立的制度。最终裁定PASS 7/7。分支经本地 ref 重置后恢复并重新核验、对最新 main 的 rebase 复证干净、build/vet/gofmt 独立复跑已推送 headforkPR 状态 OPEN/MERGEABLE。deployer 交棒后续以 PR CI 作为额外的真实环境确认但不是门禁通过的前提条件。八、从本门禁提炼的可复用经验确定性是测试的第一性原理Go map 迭代顺序、会话 root 推进时机、连接池回收时机这些隐式非确定性是间歇性 flaky 的温床。sortedSnapshotQueryNames的教训是凡是顺序会影响结果的测试必须显式固定顺序并加注释说明原因。oracle 的盲区要显式记账ignored 迁移流的排除谓词让 oracle 失去了对 wisp 列漂移的感知ga-61ruw 事件文档没有掩盖这一点而是记录了代价、实测了 ignored 平面拥有的对象清单并给出正确的根治方向补 ignored bundle。测试要能精确复现而非大概率复现TestMigratingOpen_FirstReadSucceeds刻意只发一条查询来复现 be-itm5connection_pool_test.go用 mock driver 把连接生命周期变成可断言的数值。好的复现测试应该让 bug 每次必现而不是碰运气。修复的生产代码边界要靠编译约束强制be-krza3 的 scope 争议最终由不含 store.go 就无法编译这一机械事实裁决比任何评审意见都更有说服力——测试本身就是需求。九、继续深入仓库门禁全文release-gates/be-krza3-schema-parity-pool-heal-gate.mdParity oracle 实现internal/storage/dolt/schema_cli_parity_integration_test.go池重建与池参数实现internal/storage/dolt/store.goapplyPoolLimits、internal/storage/dolt/store.gorebuildPoolAfterMigration连接池单元测试internal/storage/dolt/connection_pool_test.go迁移后首读复现测试internal/storage/dolt/post_migration_pool_heal_integration_test.goSchema 迁移与 CLI DDL 模板internal/storage/schema【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考