跳转至

§12 数据访问档(定稿 v0.8,2026-09-22)

状态:定稿——随服务器路线 P5 波(std/db 数据访问层)落地回写(2026-09-22;执行判定见 仓库内部设计文档 执行记录)。原草案(v0.8-d1,2026-09-20)承自服务器路线设计 v3。能力/纯度语义归 §8;取消语义归 §7.2 与 §11.4。 本章定驱动契约、连接池、行映射(as-built 运行时面)、事务与取消。规范性约定同规范 README。 实装面:std/db/{db,pg,redis,pool,rowmap}.ct + tests/db/(回放零真库;真靶 nightly;性能门 tests/db/perf,登记跳过口径随实测)。

12.1 能力键 db.connect(规范性)

  • 数据库访问一律经能力对象;[caps] 声明 db.connect 上限,超出 = E4010。连接以 DSN 经能力对象参数传入,程序内不得从任意字符串自行建连。
  • #[pure] 函数触库 = E4020(编译期拒绝)。
  • 派生面:由一个已授权连接派生的事务/预编译语句继承授权,不重复消耗键。

12.2 驱动契约(规范性:纯 Ctron 线协议)

  • 驱动必须为纯 Ctron 线协议实现——这是能力面可审计性的根据(C 绑定驱动绕过语言级审计,触发 W 级 lint):
  • PostgreSQL 线协议 v3:startup、简单查询、扩展查询(Prepared Statement)、SCRAM-SHA-256 认证(密码学原语 std/crypto:SHA-256/HMAC/PBKDF2,纯 Ctron,RFC 6234/4231/6070 向量锚定;SASLprep 口令规范化省略 = v0 登记档,口令按原始字节,系 RFC 5802 §5.1 建议档;plus-only channel binding 拒收 = clean Err);
  • Redis RESP2:GET/SET/DEL/EXPIRE/INCR 基本面;订阅(pub/sub)列生态档。
  • MySQL/Mongo 等不在 v1 契约内;SQLite(C 绑定例外路径)列志向档,落地时须显式 #[trusted] 审计面。

12.3 连接池与背压(规范性)

  • 池有界(容量必填,同 Channel 纪律);池等待经有界通道表达背压,等待可取消(§12.4)。
  • 回池前复位(必须):活动事务回滚、会话变量复位、预编译语句按策略清理——禁止跨取消/跨错误复用脏连接。

12.4 事务与取消传播(规范性)

  • begin / commit / rollback 显式面;查询在挂起点响应作用域取消(§7.2/§11.4):取消 → 连接回滚复位回池,不把取消语义泄漏为半程提交。
  • 嵌套事务不支持(savepoint 列志向档);错误沿 Result 显式传播,不 panic。

12.5 行映射(规范性;as-built = 运行时绑定,D-P5-1 偏差回写)

  • 查询结果行 → struct 绑定:运行时展开(P5 波 as-built;std/db/rowmap.ct OID 表/列名匹配/类型族门,列缺失/类型不符/NULL 误配/行越界/值域出界 = 运行时 Result Err 报,kind noent/type/null/row-oob/val-domain)。 原草案"comptime 展开、编译期报"在 §8.4 禁反射(类型产出函数预留 v2)下 不可达——本条为 D-P5-1 设计偏差的定稿回写,偏差登记与出口判定见 P5 计划执行记录。负例锚 r7d_db_rowmap(锚语义随之由"编译期报"改 "运行时 Err")。
  • @derive(DbRow)(编译器已知 derive 集扩展,编译期生成绑定代码)= 志向 档,列编译泳道;本条 OID/列名匹配面即其运行时回落位,落地后运行时面 降级为手写回落路径。
  • SQL 文本不做静态校验(无 live-DB 依赖;静态 SQL 检查列志向档)。
  • NULL → Option[T] 显式映射,无隐式零值(rowmap NULL Err 面 + 调用方 wrapper 映射 Option 两段形)。

12.6 与 std/json 的接口(前置依赖声明)

  • 请求体 → struct → 行绑定链路以 std/json 数值/布尔类型保真为前置工项(2026-09-20 v3 评审认定:现 json 值模型为扁平化字符串表,不满足数值保真);流式/NDJSON 解析列生态档。

12.7 与测试集的对应

  • 协议夹具回放(as-built:手工按公开协议构造字节脚本,README 各自登记录制口径;CI 零真库依赖);真库(Postgres/Redis)仅 nightly 靶(tests/db/nightly/,env 驱动,无靶 SKIP 登记口径)。
  • tests/db/ 双臂(解释器 + emit;夹具 script 40 面 + corpus + fd 真源 x_ emit 专臂);解码器 fuzz 与差分(libpq/官方 resp 实现垫,仅测试线引用)列后续;性能门:简单查询回环 vs libpq 同构 ≤1.5×(tests/db/perf/,min-of-3;本机无 libpq 开发面 = SKIP 登记口径,实测 2026-09-22)。