# PostgreSQL 接入 `mpc sql-join --pg-url` 直连业务库取本方数据,靠的是 `crates/mpc-data/src/pg` 里一份手写的 PG v3 前端协议客户端(**零外部依赖**)。这份文档说明它支持到哪、 怎么验、以及出问题时先看什么。 ## 为什么要手写 铁律是「单二进制、能编进 TEE / Zynq」。`tokio-postgres` 会拖进 tokio + bytes + futures;`postgres`(同步版)也是一串依赖 + 自己的 TLS 栈。 联邦学习这条路上真正需要的只有一件事:**执行一条只读 SELECT,把行取回来**。 没有参数化、没有预编译、没有连接池、没有通知、没有 COPY——这些都不要, 要的就手写。协议本身不难:StartupMessage + 认证 + Simple Query,一千多行。 ## 支持矩阵 | 能力 | 状态 | |---|---| | 连接串 `postgres://user:pass@host:port/db?sslmode=disable` | 支持 | | `sslmode=disable` / 省略 | 支持 | | `sslmode=require` 及其他 | **明确报错**,不假装支持 | | 认证 `trust` / `cleartext` / `md5` / `SCRAM-SHA-256` | 支持;`SCRAM-SHA-256-PLUS` 不支持(要 TLS) | | Simple Query(`Q`),多语句返回多个结果集 | 支持 | | Extended Query(prepare/bind/execute) | 不做 | | 结果文本格式 → `Frame`(**只要数值列**) | 支持,非数值列先丢后报 | | `COPY`、`LISTEN/NOTIFY`、游标 | 不做 | | 密码来源 | 连接串 → 省略时取 `MPC_PG_PASSWORD`;**别写进 argv** | 被丢的列:`ResultSet::to_frame` 只收 `bool/int2/int4/int8/oid/float4/float8/numeric` (OID 16/21/23/20/26/700/701/1700),`text/varchar/date/timestamp/json` 一律丢弃 并回报列名。`Frame` 的格子是 `f64`,这是刻意的——密态算子只认定点数。 join 键必须是**非负整数**(PSI 的 id 是 `u64`),且 < 2^53(`f64` 能精确表示的上界)。 ## 三层验证 单元测试只能证明「我们自己写的服务端和客户端能对上」,等于自证。所以分三层: 1. **golden 向量**(`pg/crypto.rs` 的测试)——PBKDF2 / HMAC / MD5 / base64 / SCRAM 的中间值与 `python3 hashlib` 独立算出的结果逐位比对。 2. **假服务端**(`pg/mod.rs` 的 `tests::Server`)——真 TCP、三种认证、错误注入, 验证客户端的状态机(错密码、错误后连接仍可用、SCRAM 全流程)。 3. **真 Postgres**(`tools/pg-dev/`)——PGlite 是 Postgres 编到 WASM 的版本, 复用同一份 PG 源码,协议行为一致。`tools/pg-dev/e2e.sh` 起两个**独立的**库 (银行 / 商户),跑完整的两方密态聚合并断言结果。 ```bash tools/pg-dev/e2e.sh # 全自动,退出码 0 = 全部断言通过 tools/pg-dev/e2e.sh --keep # 跑完不关库,方便手工再看 ``` 它验的是:客户端连真库 → `SELECT uid, balance` 取数 → PSI 求交(`uid=6` 只在乙方、 `uid=5` 只在甲方,必须被挡掉)→ 列分片交换 → 密态聚合 → 两方结果一致。 ``` 第一轮(聚合 spend) COUNT=4 SUM=140 MIN=20 MAX=50 第二轮(WHERE spend>=30,聚合 balance) COUNT=3 SUM=1600 MIN=300 MAX=900 ``` ## 手工起一个本地库 ```bash cd tools/pg-dev && node server.mjs --port 5433 --init seed-bank.sql ``` - 默认 `memory://`,跑完即弃;要保住数据给 `--data-dir .data/bank` - 就绪信号是 stdout 上的 `[pg-dev] ready 127.0.0.1:5433` - 认证走 trust(PGlite 单用户),**所以 SCRAM 只在假服务端 + golden 向量里验过** ## 出问题时先跑 `mpc pg` `sql-join` 的报错来自分布式会话深处,「连不上库 / 列被丢 / 键不是整数 / 值不是数值」 四种错在终端上长得差不多。把库这条路单独跑通再排查: ```bash mpc pg --url postgres://u@127.0.0.1:5432/db \ --sql "select uid, balance, name from t" --frames ``` 输出三块:原始结果集、**列类型表**(每列的 OID、类型名、会不会进 `Frame`)、 以及 `--frames` 时真正进密态计算的那几列。用户最常见的困惑「我查了 5 列, 怎么聚合只认 2 列」,答案永远在那张列类型表里。 ## 已知限制(写清楚免得踩) - **链路上不加密**。`sslmode=require` 直接拒绝,跨公网请套 SSH 隧道 / WireGuard。 - **密码以 md5 / SCRAM 证明过网**(trust 除外),明文只出现在 cleartext 模式。 - **整表物化**。Simple Query 一次返回全部 `DataRow`,百万行会吃掉内存; 真流式要 extended query + Execute 分页,属后续。CSV 侧已有分批流接口 (`mpc-data::source`),PG 侧还没有。 - **PGlite 是 PG 18**,生产是 15.18;两者 wire 协议同为 v3,但新版本的行为差异 (如参数默认值)不会被这套端到端测试覆盖。