ProxySQL DuckDB 插件审查修复与文档化实施计划深度解析
ProxySQL DuckDB 插件审查修复与文档化实施计划深度解析
本文以仓库内实施计划文档 2026-09-01-duckdb-review-and-documentation.md 为骨架,结合 DuckDB 插件设计文档 与
plugins/duckdb/、lib/sqlite3db.cpp、test/tap/tests/等真实源码,逐任务拆解 PR 6133 遗留审查意见的修复方案,以及doc/duckdb/系列文档的发布流程。读者可据此掌握超大数据行拒绝、多语句SET NAMES拦截、PostgreSQL 扩展查询错误再同步三大修复点的接口设计与测试策略,并了解 v4.0 插件化 DuckDB 服务的完整运维文档体系。
背景与全局约束
该实施计划承接 PR 6133 的代码审查,目标是解决遗留的合法审查意见,并在仓库中发布一套网站级可用的 DuckDB 插件文档。其架构决策非常明确:
- 线协议决策保留在 DuckDB 会话层(
plugins/duckdb/src/duckdb_session.cpp); - 超大数据行在既有的
SQLite3_result::add_row边界拒绝(include/sqlite3db.h); - 两类修复均配套聚焦的 TAP 单元测试;
doc/duckdb/成为面向运维的规范文档,插件源码树与 vendored 依赖旁仅保留简短的开发者 README。
技术栈为 C++17、DuckDB 1.4.5 C/C++ API、PostgreSQL v3 线协议、GNU Make、TAP 与 Markdown。设计依据见 2026-08-26-duckdb-server-plugin-design.md。
计划开篇列出四条全局约束,它们是所有后续任务的验收底线:
| 约束 | 含义 |
|---|---|
| DuckDB 仅作为 PROXYSQL40/v4.0 运行时插件 | 不编译进核心二进制,仅以 .so 形式在启动时加载 |
| PostgreSQL 扩展查询仍不支持 | 拒绝必须遵循 PostgreSQL 错误再同步(error resynchronization)语义 |
enable_external_access 默认 false |
覆盖 DuckDB 自身的宽松默认,默认拒绝外部文件系统访问 |
| 文档归属明确 | 用户文档归 doc/duckdb/,docs/superpowers/ 仅存放内部设计/计划材料 |
此外还有两条工程纪律:只运行聚焦的单元/语法检查,不做全仓构建;除非用户另行要求,否则不提交不推送。
Task 1:拒绝超大数据行(SQLITE_TOOBIG)
问题本质:int 表示范围的边界溢出
SQLite3_result::add_row(char** fields, const unsigned long* sizes) 是有尺寸感知的添加接口。修复前,行内字段尺寸与累计行大小没有经过 INT_MAX 校验,一旦字段或整行超过 int 可表示范围,随后把 unsigned long 收窄为 int 的拷贝逻辑就会产生不可预期的行为。
修改文件:
接口契约
SQLite3_row::add_fields(char **fields, const unsigned long *sizes)返回bool;SQLite3_result::add_row(fields, sizes)在字段或整行无法装入既有int表示时,返回SQLITE_TOOBIG且不追加该行。
先写失败测试(TDD)
char byte = 'x';
char* fields[] = { &byte, &byte };
unsigned long one_too_large[] = { static_cast<unsigned long>(INT_MAX) + 1UL, 0UL };
unsigned long cumulative_overflow[] = {
static_cast<unsigned long>(INT_MAX / 2),
static_cast<unsigned long>(INT_MAX / 2)
};
SQLite3_result result(2);
ok(result.add_row(fields, one_too_large) == SQLITE_TOOBIG && result.rows_count == 0,
"a field larger than INT_MAX is rejected without adding a row");
ok(result.add_row(fields, cumulative_overflow) == SQLITE_TOOBIG && result.rows_count == 0,
"a cumulative row larger than INT_MAX is rejected without adding a row");
运行聚焦测试:
cd test/tap/tests/unit && make sqlite3db_unit-t -j2 && ./sqlite3db_unit-t
预期修复前该边界用例失败或中止。
校验先于收窄/分配
修复的核心是在拷贝之前用 64 位累加器做两次上界判断:单字段不得大于 INT_MAX,累计大小(含每字段的 NUL 终结字节)也不得突破 INT_MAX:
bool SQLite3_row::add_fields(char **fields, const unsigned long *input_sizes) {
unsigned long long total = 0;
for (int i = 0; i < cnt; ++i) {
if (fields[i] == nullptr) continue;
if (input_sizes[i] > static_cast<unsigned long>(INT_MAX) ||
total + input_sizes[i] + 1ULL > static_cast<unsigned long long>(INT_MAX)) {
return false;
}
total += input_sizes[i] + 1ULL;
}
// Existing copy logic, now using validated lengths.
return true;
}
校验失败时删除临时行对象并从 SQLite3_result::add_row 返回 SQLITE_TOOBIG。
仓库现状印证
当前仓库中该修复已经落地,与计划的 Step 3 完全一致:lib/sqlite3db.cpp:165-199 的 add_fields(char **_fields, const unsigned long *_sizes) 先遍历校验 _sizes<a href="https://link.gitcode.com/i/3b97af27f9efb7eeb8609ce94ba98670" target="_blank">i] > INT_MAX 与 data_size + _sizes[i] + 1ULL > INT_MAX,失败即 return false;[lib/sqlite3db.cpp:988-1003 的 add_row(char **_fields, const unsigned long *_sizes) 在 add_fields 返回 false 时 delete row 并返回 SQLITE_TOOBIG。对应单元测试见 test/tap/tests/unit/sqlite3db_unit-t.cpp:180-199,断言同时检查返回码与 rows_count == 0、rows.empty()。
Task 2:拒绝多语句 SET NAMES
问题本质:前缀匹配器误吞多语句包
duckdb_classify_query 对兼容性语句做归一化识别。修复前,SET NAMES utf8; SELECT 1 这种包会被前缀匹配当作 ok_noop 兼容空操作吞掉——DuckDB 因此永远看不到后续语句,客户端收到的是虚假的成功。
修改文件:
接口契约
- 消费
duckdb_classify_query归一化后的兼容语句; - 对
SET NAMES ...; <second statement>产生DuckDBIntercept::none,使其落入 DuckDB 的 prepare 路径被拒绝,而不是返回无操作成功。
先写失败断言
ok(classify("SET NAMES utf8; SELECT 1") == DuckDBIntercept::none,
"SET NAMES followed by another statement is not swallowed as a compatibility no-op");
cd test/tap/tests/unit && make duckdb_session_unit-t -j2 && ./duckdb_session_unit-t
预期修复前该断言报 not ok(前缀匹配器返回 ok_noop)。
修复:要求归一化命令不再含分号
return q.rfind("SET NAMES ", 0) == 0 && q.find(';') == std::string::npos;
即 SET NAMES 必须以 SET NAMES 开头,且整条归一化字符串中不得再出现分号——任何后续语句都会触发 none 走正常执行路径,被 DuckDB 的多语句 prepare 拒绝。
仓库现状印证
当前实现位于 plugins/duckdb/src/duckdb_session.cpp:46-55 的 is_client_compatibility_set(),正是 q.rfind("SET NAMES ", 0) == 0 && q.find(';') == std::string::npos 的组合;同时兼容 SET autocommit=0/1 紧凑写法。单元断言见 test/tap/tests/unit/duckdb_session_unit-t.cpp:82-83。
值得注意:SET NAMES ...; SELECT 1 也是多语句请求,因此在 doc/duckdb/troubleshooting.md 中明确它不是兼容空操作。这与设计文档 §7 的"prepare-first 结构性单次执行"决策互为表里——duckdb_prepare() 拒绝一次调用中的多条语句("Cannot prepare multiple statements at once!"),从根上封堵了"先执行隐藏副作用、只回显最后一条结果"的语句走私(statement smuggling)路径。
Task 3:PostgreSQL 扩展查询错误再同步
问题本质:不支持的扩展消息需要协议正确的错误恢复
DuckDB 插件不支持 PostgreSQL 扩展查询(Parse/Bind/Execute)。收到第一个不支持的扩展消息时,必须按 PostgreSQL 错误再同步规则处理:先发一个不带 ReadyForQuery 的 ErrorResponse,丢弃后续前端消息直到 Sync,然后恰好发送一次 ReadyForQuery——绝不能假装支持,也不能让客户端永久悬挂。
修改文件:
- plugins/duckdb/include/duckdb_session.h
- plugins/duckdb/src/duckdb_session.cpp
- lib/PgSQL_Session.cpp
- test/tap/tests/unit/duckdb_session_unit-t.cpp
- test/tap/tests/test_duckdb_e2e_pgsql-t.cpp
接口契约
- 产出
DuckDBPgsqlAction duckdb_pgsql_message_action(DuckDBSessionState&, char),含process、discard、send_error、send_ready四种结果; - 扩展
DuckDBSessionState增加bool pgsql_extended_error; - 在第一个不支持的扩展消息上发出不带 ReadyForQuery 的 ErrorResponse,丢弃后续消息直到 Sync,然后恰好发送一次 ReadyForQuery。
先写状态机失败断言
DuckDBSessionState state;
ok(duckdb_pgsql_message_action(state, 'P') == DuckDBPgsqlAction::send_error,
"the first extended-query message emits one error");
ok(duckdb_pgsql_message_action(state, 'B') == DuckDBPgsqlAction::discard,
"messages after an extended-query error are discarded until Sync");
ok(duckdb_pgsql_message_action(state, 'S') == DuckDBPgsqlAction::send_ready,
"Sync ends extended-query error recovery with ReadyForQuery");
ok(duckdb_pgsql_message_action(state, 'Q') == DuckDBPgsqlAction::process,
"simple queries resume after Sync");
cd test/tap/tests/unit && make duckdb_session_unit-t -j2
预期先出现编译失败(缺失的 action 类型/函数),驱动接口落地。
实现纯状态迁移
enum class DuckDBPgsqlAction { process, discard, send_error, send_ready };
DuckDBPgsqlAction duckdb_pgsql_message_action(DuckDBSessionState& state, char type) {
if (state.pgsql_extended_error) {
if (type == 'S') {
state.pgsql_extended_error = false;
return DuckDBPgsqlAction::send_ready;
}
return DuckDBPgsqlAction::discard;
}
if (type == 'P' || type == 'B' || type == 'C' || type == 'D' || type == 'E') {
state.pgsql_extended_error = true;
return DuckDBPgsqlAction::send_error;
}
if (type == 'S') return DuckDBPgsqlAction::send_ready;
return DuckDBPgsqlAction::process;
}
然后在 lib/PgSQL_Session.cpp 中把 S 路由给插件(SQLite 会话);简单查询错误仍走既有的 ErrorResponse+ReadyForQuery 路径。
强化裸协议测试
同一连接上依次发送 P、B、S,断言响应类型序列是 E、Z,且没有第二个 E。
仓库现状印证
实现位于 plugins/duckdb/src/duckdb_session.cpp:233-248,与计划 Step 3 的伪代码一致,且额外把 H(Flush)在非错误态也归为 discard(作为协议消息消费,而非当作 SQL 解析)。头文件声明与枚举见 plugins/duckdb/include/duckdb_session.h:59-68,会话状态中已有 pgsql_extended_error 字段(duckdb_session.h:53)。调用点位于 duckdb_session.cpp:1050 的消息分发循环。
单元断言见 test/tap/tests/unit/duckdb_session_unit-t.cpp:171-182,端到端裸协议测试 extended_error_resynchronizes_on_sync 见 test/tap/tests/test_duckdb_e2e_pgsql-t.cpp:85-96:发送 P、H 后预期收到 E,随后 poll 确认 100ms 内无额外消息,再发 S 并断言收到 Z。端到端断言(test_duckdb_e2e_pgsql-t.cpp:260-270)覆盖"仅一个错误 + 丢弃至 Sync + 一次 ReadyForQuery"。
底层设计注记
D3 决策解释了为何这里需要核心变更:PostgreSQL 路径要求 PgSQL_Protocol::get_header() 由私有改为公开,并在 lib/PgSQL_Session.cpp(约 2279 行)的查询分发门槛中为 PROXYSQL_SESSION_SQLITE 增加路由分支——否则 'Q' 包在 SQLite 会话上会泄漏并导致客户端永久悬挂。这两处均为头文件可见性/分发条件级别改动,不影响未加载该插件时任何其他会话类型的行为(详见 设计文档 §4 D3)。
Task 4:加固测试并修正遗留文案
本任务聚焦测试确定性、连接丢失安全性与文档准确性,修改文件包括:
- test/tap/tests/test_duckdb_admin_tables-t.cpp
- test/tap/tests/test_duckdb_e2e_pgsql-t.cpp
- test/tap/tests/unit/duckdb_engine_unit-t.cpp
- test/tap/tests/unit/duckdb_admin_schema_unit-t.cpp
- doc/PLUGIN_API.md
- deps/duckdb/README.md
让 Admin 编辑值区别于观测值
threads_edit_value = threads_before_edit == "7" ? "6" : "7"——将编辑值插入 UPDATE,并断言加载后的运行时值等于该编辑值。这样测试不再依赖固定值,避免与真实运行环境中的并发修改冲突。
集中化 libpq 执行检查
PGresult* exec_or_bail(PGconn* conn, const char* sql) {
PGresult* result = PQexec(conn, sql);
if (result == nullptr) BAIL_OUT("DuckDB PostgreSQL connection lost while executing: %s", sql);
return result;
}
同时在 PQstatus / PQfinish 之前对 PQconnectdb 的 null 返回做守卫——防止 PostgreSQL 连接在测试中途丢失时出现未定义行为。当前仓库中该函数已在 test_duckdb_e2e_pgsql-t.cpp 被广泛调用(如 exec_or_bail(c, "SELECT 42 AS answer"))。
安全临时 CSV 夹具
用 mkstemp 替换可预测文件名,通过 fdopen 写入,断言后 unlink 生成的路径;同时把字面量 /tmp 状态夹具改为非临时示例数据库路径,避免 Sonar 把惰性 JSON 数据误判为文件创建。
修正既有参考文案
- ABI 布局版本与
PROXYSQL_PLUGIN_ABI_DEBUG_BIT分开记录; - 说明确切的 DEBUG 标签匹配规则;
- 删除"DuckDB 复制了既有 libssl/re2 LFS/校验和/验证器模式"的错误表述。
验证
运行聚焦测试目标,随后执行 git diff --check 与过时 ABI/vendoring 表述的搜索。
Task 5:发布模块化用户文档
这是文档化工作的主体:doc/duckdb/ 下建立 10 个页面,每页对应未来网站的一个独立板块,并以相对链接互相导航。计划要求的新建文件在仓库中已全部存在:
| 页面 | 内容定位 |
|---|---|
| doc/duckdb/index.md | 落地页:v4.0 可用性、前置条件、插件加载、默认端口、一个表生命周期、下一步路由 |
| doc/duckdb/quickstart.md | 五分钟教程:构建、加载、双协议连接、首个分析查询、持久化 |
| doc/duckdb/installation.md | 源码构建、插件加载、升级注意事项 |
| doc/duckdb/user-guide.md | 日常 SQL、连接、持久化、客户端示例 |
| doc/duckdb/configuration-reference.md | 全部八个变量的默认值、可接受形式、校验、安全影响、LOAD 即时生效或需重启 |
| doc/duckdb/admin-reference.md | 两张表、运行时视图、命令、别名、启动时磁盘到内存行为、全新安装空表行为 |
| doc/duckdb/protocol-compatibility.md | 文本结果元数据、单语句/简单查询限制、MySQL/PostgreSQL 客户端行为 |
| doc/duckdb/security.md | 外部访问风险、信任模型、资源隔离 |
| doc/duckdb/operations.md | 监控/状态、持久化/备份、资源规划、重启/恢复 |
| doc/duckdb/troubleshooting.md | 基于症状的恢复步骤 |
同时修改 plugins/duckdb/README.md 与 doc/README.md。
八个变量的配置全景(configuration-reference)
doc/duckdb/configuration-reference.md 给出了完整的变量表:
| 变量 | 默认值 | 可接受值 | 生效行为 |
|---|---|---|---|
duckdb-mysql_ifaces |
0.0.0.0:6031 |
分号分隔的 addr:port |
变更被拒绝;重开监听器 |
duckdb-pgsql_ifaces |
0.0.0.0:6034 |
分号分隔的 addr:port |
变更被拒绝;重开监听器 |
duckdb-database_path |
:memory: |
DuckDB 路径或 :memory: |
变更被拒绝;重开数据库 |
duckdb-memory_limit |
1GB |
DuckDB 内存限制字符串 | 即时生效,校验并读回 |
duckdb-threads |
2 |
整数 1..INT_MAX |
即时生效,既有连接可见 |
duckdb-max_connections |
100 |
整数 1..INT_MAX |
新准入即时生效 |
duckdb-read_only |
false |
布尔别名 | 变更被拒绝;重开数据库 |
duckdb-enable_external_access |
false |
布尔别名 | true→false 即时生效;反向被拒绝 |
布尔别名(true/false、1/0、on/off)以规范形式存储;空数据库路径归一为 :memory:;运行时引擎值来自 DuckDB current_setting()(含规范内存单位,例如 DuckDB 1.4.5 把输入 512MB 读回为 488.2 MiB)。
Admin 命令与别名(admin-reference)
doc/duckdb/admin-reference.md 整理了完整命令族:
-- Main to Runtime
LOAD DUCKDB VARIABLES TO RUNTIME;
LOAD DUCKDB VARIABLES FROM MEMORY; -- alias
-- Runtime to Main
SAVE DUCKDB VARIABLES TO MEMORY;
SAVE DUCKDB VARIABLES TO MEM; -- alias
SAVE DUCKDB VARIABLES FROM RUNTIME; -- alias
SAVE DUCKDB VARIABLES FROM RUNTIME TO MEMORY; -- legacy alias
-- Main to Disk
SAVE DUCKDB VARIABLES TO DISK;
SAVE DUCKDB VARIABLES FROM MEMORY; -- alias
SAVE DUCKDB VARIABLES FROM MEMORY TO DISK; -- legacy alias
-- Disk to Main only
LOAD DUCKDB VARIABLES FROM DISK;
LOAD DUCKDB VARIABLES TO MEMORY; -- alias
关键行为:所有拷贝只替换 duckdb-% 行,不影响其他模块命名空间;LOAD 用合法的稀疏 Main 切片覆盖有效状态,校验完整候选,拒绝未知变量、非法值与不支持的在线迁移;Main 失败时不静默修复。即时生效项为 duckdb-memory_limit、duckdb-threads、duckdb-max_connections、duckdb-enable_external_access(仅 true→false);其余项需数据库/监听器生命周期重开。
从源码看,变量解析逻辑集中在 plugins/duckdb/src/duckdb_config.cpp:默认值注册(duckdb_config.cpp:151-158)、read_only/enable_external_access 的布尔校验(duckdb_config.cpp:189-209)、iface 解析(parse_one_iface 支持方括号 IPv6 字面量与端口 1-65535 校验,duckdb_config.cpp:64-96)。
开发者 README 瘦身
plugins/duckdb/README.md 转为开发者入口:保留构建产物与维护者链接(vendored DuckDB 维护说明、doc/PLUGIN_API.md、设计/计划文档),每个运维主题一律链接到 doc/duckdb/ 而非重复内容。构建命令为 deps/duckdb/verify-source.bash && PROXYSQL40=1 make,产物 plugins/duckdb/ProxySQL_DuckDB_Plugin.so,标准安装路径 /usr/lib/proxysql/plugins/ProxySQL_DuckDB_Plugin.so。
导航与声明校验
逐一检查每个相对 Markdown 链接,搜索过时端口/路径与自相矛盾的变量行为,运行 git diff --check。链接检查正是本仓库的规范要求——例如 plugins/duckdb/README.md 中的链接全部指向 doc/duckdb/ 下的页面与 docs/superpowers/ 下的设计材料,均以仓库根为基准。
Task 6:最终验证
- 串行运行聚焦单元测试:运行受影响的单元二进制,避免并发归档重建。
- 语法与空白检查:对无运行测试覆盖的变更 C++ 做非链接语法检查,并执行
git diff --check。 - 最终差异复审:对照每一项已批准的审查意见与每个文档页面复核最终 diff,确认未采纳不安全的
conn->internal_ptr建议,且未把纯风格改动混入补丁。
设计文档中的关键背景:类型映射与准备优先
理解 Task 1 的 SQLITE_TOOBIG 拒绝和 Task 2 的多语句拦截,离不开设计文档 §7 的演进史:
- 早期版本用
duckdb_query()先执行、再检查真实结果,若存在不可渲染列则重新执行包裹查询,并依赖词法闸门duckdb_is_safe_to_rewrap()判断"是否安全重跑"。该闸门被证明不充分——SELECT [nextval('s')]返回LIST(不可渲染)、以SELECT开头且无RETURNING,通过了闸门却被静默执行两次,序列号每次客户端语句推进两次。 - 现版本改为准备优先(prepare-first):
duckdb_execute_effective()先duckdb_prepare()(解析绑定但不执行),用duckdb_prepared_statement_column_type()检查列类型;若有列不在白名单,则准备SELECT COLUMNS(*)::VARCHAR FROM (<original>)包裹语句;选择包裹或原语句后恰好执行一次。这从结构上消除了双重执行风险——不存在"第一次执行"可被重复。 - 副作用:
duckdb_prepare()拒绝多语句包,因而多语句输入被整体拒绝,封堵了DROP TABLE t; SELECT 1;这类"执行全部、只回显最后一条结果"的走私路径;纯注释语句也会报 "No statement to prepare!"。 - 类型白名单来自 DuckDB C API 的字符串强转路径:
BOOLEAN、整型族、FLOAT/DOUBLE、DATE/TIME/TIMESTAMP、HUGEINT/UHUGEINT、DECIMAL、INTERVAL、VARCHAR、BLOB可直接渲染;LIST/STRUCT/MAP/ARRAY/UNION/UUID/ENUM/BIT/TIMESTAMP_S/MS/NS走 VARCHAR 包裹。部分 DMLRETURNING无法包裹,降级路径可能对不支持类型返回 NULL(并非 SQL NULL),建议在原始 SQL 中显式::VARCHAR强转。
附:如何查看与验证
本文所有代码、测试与文档均在当前仓库内可查:
- 核心边界修复:lib/sqlite3db.cpp、include/sqlite3db.h
- 会话层修复:plugins/duckdb/src/duckdb_session.cpp、plugins/duckdb/include/duckdb_session.h
- 单元测试:test/tap/tests/unit/sqlite3db_unit-t.cpp、test/tap/tests/unit/duckdb_session_unit-t.cpp
- 端到端测试:test/tap/tests/test_duckdb_e2e_pgsql-t.cpp、test/tap/tests/test_duckdb_admin_tables-t.cpp、test/tap/tests/test_duckdb_e2e_mysql-t.cpp、test/tap/tests/test_duckdb_plugin_load-t.cpp
- 运维文档:doc/duckdb/ 全系列
- 设计依据:2026-08-26-duckdb-server-plugin-design.md
需要强调的是,仓库只读,本文仅说明查看、构建、运行与配置方式:构建用 deps/duckdb/verify-source.bash && PROXYSQL40=1 make;加载通过 proxysql.cnf 的 plugins 数组;运行测试走 test/tap/tests/unit/Makefile 聚焦目标与隔离式 TAP 基础设施(如 test/infra/control/run-tests-isolated.bash)。端到端测试必须在已加载插件的隔离 ProxySQL 实例上运行,本地基准 test_duckdb_bench-t 仅在 RUN_DUCKDB_BENCH=1 时执行,且其 diag() 结果不得被当作产品性能声明。