Dolt MySQL 客户端集成测试套件：本地 Docker 运行、多阶段构建与多语言协议验证全指南

• 数据库
• 关系型数据库
• 后端
• CLI

本篇技术指南围绕 Dolt 仓库中的 MySQL/MariaDB 客户端集成测试套件（integration-tests/mysql-client-tests）展开，系统讲解其定位、本地 Docker 运行方式、多阶段镜像构建的优化技巧，以及该套件如何借助 BATS 脚本在 C/C++/Java/Go/Python/Node/Ruby/Rust 等十余种语言生态中验证 Dolt SQL Server 的协议兼容性。读完本文，你将掌握如何在本机完整跑通这套冒烟测试、如何只构建指定阶段加速迭代，以及如何理解每个客户端测试背后的实现原理与可验证的源码依据。

套件定位：面向 MySQL/MariaDB 客户端生态的冒烟测试

Dolt 是一个"Git for Data"数据库，其核心能力之一是以 MySQL 兼容协议对外提供 SQL 服务。要保证这一层协议兼容性持续可靠，仅靠单一语言的客户端测试远远不够——真实世界里连接 Dolt 的应用可能来自 Go、Java、Python、Node.js、Ruby、Rust、C、C++、PHP、Perl、R、Elixir、Swift、.NET 等任意技术栈。

套件根目录的 README.md 开宗明义地说明：

This suite contains smoke tests for Dolt's MySQL and MariaDB client integrations. It runs in GitHub Actions on pull requests.

也就是说，这是一组"冒烟测试"（smoke tests）：在 PR 阶段通过 GitHub Actions 自动执行，用最低成本快速暴露协议层面的回归问题。测试模式非常直接：先通过dolt命令行初始化一个数据库仓库并启动dolt sql-server，然后让各种语言的 MySQL/MariaDB 客户端分别连接该服务器，执行基础的读写与 Dolt 专属 SQL 存储过程调用，以此验证客户端能否正常工作。

本地运行：使用 Docker 一键复现 CI 环境

README 给出了在本地完整运行套件的标准流程。由于 Dockerfile 内部以dolt/go/...这类路径复制文件，构建上下文必须包含包含dolt/目录的工作区根目录（即整个仓库的父目录），而不能直接把integration-tests/mysql-client-tests当作上下文根。

$ cd <workspace-root> $ docker build -t mysql-client-tests -f dolt/integration-tests/mysql-client-tests/Dockerfile . $ docker run mysql-client-tests:latest

其中<workspace-root>指包含dolt/目录的根路径。README 还提示，如果使用 GoLand 的 Docker 集成插件，可以跳过上述全部命令行操作。

构建耗时说明：docker build可能需要数分钟，因为它要为十余种语言分别安装工具链和客户端依赖——从 Go 的 CGO 编译环境、Rust 工具链、.NET SDK、Java/Maven，到 Python 的 PyInstaller 打包、Elixir 的 Burrito 打包等，全部在构建阶段完成。

运行输出预期：启动构建好的容器后，会依次输出配置更新和测试执行两类日志：

$ docker run mysql-client-tests:latest Updating dolt config for tests: Config successfully updated. Config successfully updated. Config successfully updated. Config successfully updated. Running mysql-client-tests: ...

这段输出的来源在 mysql-client-tests-entrypoint.sh 中清晰可见：入口脚本先用dolt config --global写入 4 项测试所需配置（关闭 metrics 上报、指定 metrics host、设置测试用户名与邮箱），然后依次调用 BATS 执行三组测试文件。这 4 条 "Config successfully updated." 正是脚本中 4 条dolt config命令的输出。

运行容器会产生 BATS 输出。若套件中任一测试失败，入口脚本会累计失败状态并在最后以非零码退出（run_bats中|| status=1的累积逻辑），便于 CI 判失败。

多阶段构建剖析：为什么构建会"慢"

套件的高质量工程实践体现在 Dockerfile 的多阶段设计上。该 Dockerfile 使用syntax=docker/dockerfile:1指令，将不同语言客户端的编译隔离为独立 stage，最终在runtime阶段聚合所有产物。各构建阶段的要点可归纳如下：

runtime阶段则基于php:8.3-bookworm，一次性安装 PHP 扩展、Perl DBD 驱动、PostgreSQL 的 mysql_fdw、R 环境、mariadb-server、bats 等运行时依赖，再通过COPY --from=<stage>把各构建阶段的产物聚合到/build/bin/<语言>/目录，最终把入口脚本设为ENTRYPOINT。这种设计让"编译一次、运行时极薄"成为可能。

编译本地依赖目录：在 Docker 内调试 go-mysql-server 等依赖

README 特别给出了一种有用的调试手段：如果你在本地的dolt之外还维护着被dolt依赖的仓库（如go-mysql-server），可以在dolt_build阶段追加一条COPY，把本地目录复制进 stage 的/build/目录，让go mod自动解析它。

COPY dolt/go/go.mod /build/dolt/go/ # COPY go-mysql-server /build/go-mysql-server WORKDIR /build/dolt/go/ RUN go mod download

这里的要点：COPY必须放在go mod download之前；复制路径需对应 stage 内的/build/目录；只要dolt的 go.mod 中引用了该依赖，Go 工具链就会自动解析并使用被复制进去的本地源码，从而实现对依赖库改动的即时验证。Dockerfile 中对应的原始片段位于 Dockerfile。

定向构建：用--target加速单点迭代

完整构建需要安装所有语言工具链，如果只想调试某个特定环节（例如 MariaDB 命令行客户端的行为），可以使用多阶段构建的--target参数，只构建对应 stage，避免反复重建整个镜像。README 给出的示例是针对mariadb_clientsstage：

$ cd <workspace-root> $ docker build \ --target mariadb_clients \ -t mysql-client-tests:mariadb-clients \ -f dolt/integration-tests/mysql-client-tests/Dockerfile .

随后即可进入该 stage 的容器手动检查与验证，例如确认 MariaDB 两个版本二进制是否就位、查看动态链接依赖：

$ docker run --rm -it --entrypoint /bin/bash mysql-client-tests:mariadb-clients # ls -la /usr/local # /usr/local/mariadb-10.11/bin/mariadb --version # /usr/local/mariadb-11.8/bin/mariadb --version # ldd /usr/local/mariadb-11.8/bin/mariadb

这套 MariaDB 客户端是通过 mariadb-install.sh 从官方归档站下载 bintar 压缩包并解压安装的，脚本支持-o（输出文件名）与-d（安装目录）两个参数。Dockerfile 中分别以版本10.11.16与11.8.3构建了两套客户端，并在 runtime 阶段通过软链接/usr/local/mariadb指向默认版本。

测试矩阵：BATS 驱动的多语言协议验证

套件执行的核心是 mysql-client-tests.bats。这个 BATS 文件的setup()会创建一个全新的 Dolt 仓库、启动一个监听随机端口的dolt sql-server，随后每个@test用例通过指定语言的客户端连接并执行验证。从源码可见，覆盖范围包括：

• MariaDB 命令行客户端：分别在 10.11 与 11.8 两个版本下验证--version输出、无凭据连接被拒绝（Access denied for user 'root'）、以及用测试用户连库执行SELECT、SELECT DATABASE()；
• Go：go-sql-driver/mysql（database/sql）与go-mysql两个驱动；
• Python：mysql.connector、官方mariadbconnector、PyMySQL、SQLAlchemy、mysql-replication（binlog 复制）；
• Java：mysql-connector-j（含 collation 专项）、mariadb-java-client、r2dbc-mariadb；
• Node.js：mysql客户端、knex.js、mariadbconnector，以及针对 Hosted 工作台稳定性的workbench.js；
• C / C++：MySQL 与 MariaDB connector、MariaDB ODBC；
• .NET：MySqlClient 与 MySqlConnector 两套驱动；
• Perl / Ruby / Elixir / R / Rust / Swift / PHP：DBD::mysql、DBD::MariaDB、ruby/mysql、mysql2、MyXQL、mysql-otp、RMySQL、RMariaDB、rust mysql 客户端、perfect-mariadb（Swift）、mysqli 与 PDO（PHP）；
• 工具链：mysqldump与 PostgreSQL 的mysql_fdw只读路径。

以 Python 的 mysql-connector-test.py 为例，它连接服务器后依次执行：建表、DESCRIBE、插入、查询、带尾随分号的查询（回归验证"分号后带空格导致断连"的历史 bug）、以及call dolt_add('-A')、call dolt_commit(...)、call dolt_checkout(...)、call dolt_merge(...)等 Dolt 专属 SQL 存储过程与dolt_log系统表查询。这正体现了冒烟测试的双重目标：既验证 MySQL 协议兼容性，也验证 Dolt 的 Git 语义 SQL 接口在多语言客户端下可用。

Go 侧的实现可参见 sql-driver-mysql-test.go：它用database/sql打开 DSN 后，依次执行一组查询字符串，再对SELECT * FROM test WHERE pk = ?、SELECT COUNT(*) FROM dolt_log等语句走 prepare/execute 路径并逐行比对返回值，同时覆盖普通查询与预编译语句两条协议链路。

基础设施：随机端口、测试用户与统一生命周期

测试的基础设施逻辑集中在 helpers.bash 中：

• setup_dolt_repo创建形如dolt_repo_$$的仓库目录，dolt init初始化，用dolt sql -q预置mysqldump_table与warehouse两张表，创建密码为空的dolt@'%'用户并授予全部权限，最后以--host 0.0.0.0 --port=$PORT --loglevel=trace启动 SQL Server；
• definePORT基于进程 PID 在 1024~65535 区间内探测一个未被lsof占用的端口，规避并行运行时的端口冲突；
• 每个测试的teardown先 kill 并 wait 服务进程、再删除仓库目录，同时检查并停止 postgresql 服务，保证环境干净可重复。

自定义版本字符串测试：验证握手阶段的版本上报

套件中还包含一个专门测试：custom-version-string-test.bats。它通过setup_dolt_repo '1.2.3-MariaDB'传入自定义版本字符串，helpers.bash 会据此生成一份含system_variables.version配置的config.yaml，再以dolt sql-server --config config.yaml启动：

listener: host: "0.0.0.0" port: $PORT system_variables: version: '1.2.3-MariaDB'

随后用 Python 的 custom-version-string-test.py 连接并校验客户端握手阶段收到的版本信息。入口脚本注释说明了设计动机：很多驱动（包括 Go 的 SQL driver）会忽略版本字段，必须用真实客户端测试来确认自定义版本字符串确实被送达客户端。

MariaDB binlog 集成测试：数据迁移路径验证

除了直接客户端连接，套件还通过 mariadb-binlog.bats 验证一条重要的数据迁移路径：用mariadb-binlog解析 MariaDB 二进制日志，把 SQL 重放到 Dolt SQL Server 中。这与mysqldump测试（mysqldump $REPO_NAME -P $PORT -h 0.0.0.0 -u $USER）互补，覆盖两种常见迁移/同步场景。

该 BATS 文件在setup_file中启动一个真实的 MariaDB 实例（配置log-bin、binlog-format=MIXED、server-id=1等），预生成 6 个 binlog 文件，分别覆盖：statement 格式安全语句、row 格式 DML（INSERT/UPDATE/DELETE）、带 LIMIT 的不安全语句、用户与 GRANT 操作、以及跨多个 binlog 文件的数据分布。测试用例则以mariadb-binlog <file> | mariadb -u root -h 127.0.0.1 -P $PORT --skip-ssl管道方式重放日志，并在 Dolt 侧断言表存在性、行数、更新后的字段内容，甚至验证未授权用户重放会被拒绝、授予 SUPER 后可重放的权限语义。

在 CI 与日常开发中的使用建议

• PR 自动验证：套件已在 GitHub Actions 中随 PR 运行，任何 Dolt 协议层改动都会触发全语言冒烟测试，是防止"某个驱动悄悄坏掉"的第一道防线；
• 本地快速回归：日常开发建议优先用--target定向构建你正在修改的客户端 stage（如mariadb_clients、python_clients_build），确认无误后再跑全量镜像；
• 依赖库联调：当改动涉及dolt的外部依赖（如go-mysql-server）时，按 README 提示在dolt_build阶段追加COPY即可在容器内使用本地依赖版本，无需发布中间版本；
• 单语言快速迭代（Node 为例）：node 子目录的 run-tests.sh 展示了脱离 Docker 的轻量思路——source ../helpers.bash后调用setup_dolt_repo起服务、运行指定index.js/workbench.js、最后teardown_dolt_repo。例如sh run-tests.sh workbench.js即可单独运行工作台稳定性测试（该测试依赖大量 Dolt 系统表、函数与存储过程，用于保护 Hosted 工作台不被 Dolt 接口变更破坏，详见 node/README.md）。

小结

integration-tests/mysql-client-tests是 Dolt 保证 MySQL/MariaDB 客户端生态兼容性的核心质量关卡：它以"每 PR 全语言冒烟"为基线，以多阶段 Docker 构建为交付形态，以 BATS + 真实客户端二进制为验证手段，覆盖从基础 CRUD、预编译语句到 Dolt 存储过程、自定义版本握手、binlog 重放、fdw 联邦查询的完整链路。无论是为 Dolt 贡献代码，还是计划在其上构建多语言应用，理解这套套件的运行方式与内部结构，都能帮助你快速定位"协议兼容性"问题的边界与复现路径。

• 数据库
• 关系型数据库
• 后端
• CLI