ProxySQL DuckDB 插件审查修复与文档化实施计划深度解析

原创2026-10-08 18:37:341,638 阅读
文章标签:后端数据库负载均衡

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——绝不能假装支持,也不能让客户端永久悬挂。

修改文件:

接口契约

  • 产出 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:加固测试并修正遗留文案

本任务聚焦测试确定性、连接丢失安全性与文档准确性,修改文件包括:

让 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:最终验证

  1. 串行运行聚焦单元测试:运行受影响的单元二进制,避免并发归档重建。
  2. 语法与空白检查:对无运行测试覆盖的变更 C++ 做非链接语法检查,并执行 git diff --check。
  3. 最终差异复审:对照每一项已批准的审查意见与每个文档页面复核最终 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 包裹。部分 DML RETURNING 无法包裹,降级路径可能对不支持类型返回 NULL(并非 SQL NULL),建议在原始 SQL 中显式 ::VARCHAR 强转。

附:如何查看与验证

本文所有代码、测试与文档均在当前仓库内可查:

需要强调的是,仓库只读,本文仅说明查看、构建、运行与配置方式:构建用 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() 结果不得被当作产品性能声明。

登录后查看全文
proxysql