SOAR 测试数据库搭建指南:基于 sakila 与 world_x 构建 init.sql 测试环境
SOAR 测试数据库搭建指南:基于 sakila 与 world_x 构建 init.sql 测试环境
本指南以 test/sql/README.md 为骨架,讲解 SQL Optimizer And Rewriter(SOAR)项目测试数据库的构建方法。文章核心主题是:如何从 MySQL 官方示例库 sakila 与 world_x 出发,经过版本注释调整、文件合并与 gzip 压缩,最终生成项目测试所依赖的 test/sql/init.sql.gz。读者读完本文后,将掌握测试库选型依据、MySQL 版本兼容注释(
/*!50610 */与/*!50708 */)的写法、文件合并命令,以及测试库在 SOAR 自测体系(BATS、golden 文件)中的实际调用方式。
SOAR(SQL Optimizer And Rewriter)是一个面向 MySQL 的 SQL 优化与改写工具,它在开发与自测阶段依赖一套结构完整、覆盖常见 SQL 场景的样例数据库。该数据库并非 SOAR 自行编写,而是直接取材于 MySQL 官方提供的两个示例库——sakila 与 world_x。仓库中 test/sql/README.md 用极简的篇幅记录了这套测试库的构建流程:下载官方包、为特定表补充版本注释、合并文件、最终 gzip 压缩为 test/sql/init.sql.gz。本文将该流程展开为可复现的完整操作指南,并深入仓库源码与测试用例,说明这套测试库在 SOAR 中究竟承担了哪些验证职责。
为什么 SOAR 需要一套专门的测试数据库
SOAR 的定位决定了它必须有一批"有代表性"的 SQL 作为回归测试样本。在 common/cases.go 中可以看到,项目维护了一个名为 TestSQLs 的测试 SQL 大集合,覆盖了单等值、单不等值、多等值、GROUP BY、ORDER BY、各种 JOIN、DELETE/UPDATE/INSERT/REPLACE、子查询、函数包裹条件、ALTER TABLE 加索引等数十种场景,例如:
SELECT * FROM sakila.film WHERE length >= 60; -- 单不等值,可使用索引
SELECT * FROM film WHERE title IS NOT NULL; -- IS NOT NULL 无法使用索引
SELECT a.address, a.postal_code FROM sakila.address a WHERE a.city_id IN (SELECT c.city_id FROM sakila.city c); -- 半连接
这些 SQL 无一例外都以 sakila 库中的 film、address、city、country、customer、actor、inventory、language 等表为执行对象。这正解释了 test/sql/README.md 为何选择 sakila:它提供了足够丰富、彼此关联的表结构与真实业务数据,让 SOAR 的启发式规则、索引建议、改写规则都能在接近真实的表结构上运行。
world_x 则是为另一类能力准备的:它包含 JSON 数据类型,SOAR 使用它来做 JSON 相关测试(详见 test/sql/README.md 的 world_x 一节)。当 SOAR 的配置文件中出现 JSON 字段相关的限制规则时,world_x 的 city、countryinfo 表正好可以作为验证载体。
测试库整体结构
test/sql/ 目录的最终产物非常简单,只包含两个文件:
- test/sql/README.md——构建说明文档;
- test/sql/init.sql.gz——合并压缩后的初始化 SQL,即测试数据库的完整导入文件。
该目录还配套了 test/test_helper.bash 与 test/query.bats 等 BATS 测试脚本,用于把 SOAR 二进制包和 etc/soar.yaml 配置串起来运行整套自测;test/sql/init.sql.gz 解压后即为构建好的初始化 SQL。
第一步:获取 MySQL 官方 sakila 示例库
按 test/sql/README.md 的描述,sakila 的获取方式是下载 MySQL 官方提供的归档包:
http://downloads.mysql.com/docs/sakila-db.tar.gz
该归档包解压后通常包含 sakila-schema.sql 与 sakila-data.sql 两个文件(一个负责建表,一个负责灌数据),需要在本地 MySQL 中先导入 schema、再导入数据,最后把二者合并为一个 sakila.sql 文件,作为后续合并的基础文件之一。
需要特别留意的是 test/sql/README.md 中的一句关键说明:
InnoDB added FULLTEXT support in 5.6.10, you should add version comment
/*!50610 xxx */forfilm_texttable and it's triggers.
sakila 示例库中的 film_text 表及其触发器使用了 FULLTEXT 索引,而 InnoDB 引擎直到 MySQL 5.6.10 才加入 FULLTEXT 支持。为了让这套 SQL 在低版本 MySQL 上也能正常导入(并在高版本上启用增强特性),需要为 film_text 表及其触发器加上版本注释,即写成:
/*!50610 CREATE TABLE film_text (...) */
/*!50610 CREATE TRIGGER ... */
/*!50610 ... */ 是 MySQL 可执行的版本注释语法:50610 表示 MySQL 5.6.10,只有服务器版本号大于等于该值时,注释中的语句才会被执行。通过这种方式,一份 sakila.sql 可以在不同版本的 MySQL 服务器上安全导入。
第二步:获取 world_x 并处理 JSON 数据类型
world_x 同样来自 MySQL 官方归档包:
http://downloads.mysql.com/docs/world_x-db.tar.gz
test/sql/README.md 指出,world_x 的引入目的非常明确——它包含 JSON 数据类型,SOAR 用它来做 JSON 测试:
MySQL support JSON datatype since 5.7.8, you should add version comment
/*!50708 xxx */forcity,countryinfo.
MySQL 从 5.7.8 开始原生支持 JSON 数据类型,因此需要为 world_x 中的 city、countryinfo 两个表加上版本注释:
/*!50708 CREATE TABLE city (...) */
/*!50708 CREATE TABLE countryinfo (...) */
其中 50708 即 MySQL 5.7.8。同样地,该注释保证 JSON 列的定义只在 MySQL 5.7.8 及以上的服务器上生效。
world_x 的 JSON 能力在 SOAR 配置层有直接呼应:默认配置 etc/soar.yaml 中定义了 column-not-allow-type 规则,将 json 列列为不建议使用的类型之一:
column-not-allow-type:
- json
- text
- boolean
也就是说,当 SOAR 对包含 JSON 列的 SQL 做启发式检查时,world_x 的 city、countryinfo 就是验证该规则输出是否正确的现实素材。
第三步:合并与压缩,生成 init.sql.gz
sakila 与 world_x 两份 SQL 准备好之后,按照 test/sql/README.md 的步骤合并:
# 将 sakila.sql 与 world_x.sql 合并成一个 init.sql
# 例如:cat sakila.sql world_x.sql > init.sql
# 最后 gzip 压缩
gzip init.sql
两条命令完成后即得到仓库中实际存在的 test/sql/init.sql.gz。压缩是为了让仓库体积更小、克隆与 CI 拉取更快;使用时先解压再导入数据库:
gzip -d init.sql.gz
mysql -u root -p < init.sql
合并顺序上,README 明确要求先合并 sakila 再合并 world_x,最终产物同时包含两张库的表结构与数据,供 SOAR 的各个测试场景按 库名.表名 的方式引用。
测试库在 SOAR 自测体系中的调用方式
搭建好的测试库并非孤立存在,它深度参与了 SOAR 的整套回归测试。理解这一点,有助于真正理解 README 中那句"SOAR use this database for JSON testing"背后更大的价值。
1. -list-test-sqls 与测试库绑定
SOAR 提供 -list-test-sqls 命令行参数,用于打印 common/cases.go 中定义的测试 SQL 集合。其实现位于 advisor/rules.go:
// ListTestSQLs 打印测试用的SQL,方便测试,对应命令行参数-list-test-sqls
func ListTestSQLs() {
for _, sql := range common.TestSQLs {
fmt.Println(sql)
}
}
命令行参数在 common/config.go 中注册,并在 cmd/soar/tool.go 中被调用。BATS 测试脚本 test/query.bats 正是将 -list-test-sqls 的输出作为 SQL 管道输入,再喂给 SOAR 的 -report-type tables 等报告类型做全量回归,例如:
${SOAR_BIN} -list-test-sqls | ${SOAR_BIN} -report-type tables > ${BATS_TMP_DIRNAME}/${BATS_TEST_NAME}.golden
${SOAR_BIN} -list-test-sqls | ${SOAR_BIN} -report-type tables -test-dsn "/sakila" >> ${BATS_TMP_DIRNAME}/${BATS_TEST_NAME}.golden
注意第二行中的 -test-dsn "/sakila"——它通过 test-dsn 指定默认库为 sakila,保证 SQL 中的 SELECT * FROM sakila.film ... 或省略库名的 SELECT * FROM film ... 都能被正确解析与执行。
2. golden 文件见证测试库的实际效果
test/fixture/ 下的大量 golden 文件记录了测试库支撑下的真实输出。以 test/fixture/test_Run_all_test_cases.golden 为例,其中频繁出现针对 sakila 库各表的索引建议输出,如:
## 为sakila库的film表添加索引
* **Case:** ALTER TABLE `sakila`.`film` add index `idx_length` (`length`) ;
又例如 test/fixture/test_Check_get_tables_from_SQL.golden 展示了 SOAR 从 SQL 中提取表名的能力,结果同样大量落在 sakila.address、sakila.city、sakila.country、sakila.film 等表上。
golden 测试机制在 test/test_helper.bash 中有明确定义——把本次运行输出与 fixture 中保存的期望输出做 diff:
golden_diff() {
diff "${BATS_TMP_DIRNAME}/${BATS_TEST_NAME}.golden" "${BATS_FIXTURE_DIRNAME}/${BATS_TEST_NAME}.golden"
}
这意味着:如果测试数据库的表结构或数据发生不可预期的变化,导致 SOAR 对同样 SQL 的检查、改写、索引建议结果改变,golden diff 会立即失败。测试库的稳定可复现性,是整套回归测试可信度的根基。
3. 配置层对测试库的引用
etc/soar.yaml 是仓库内的示例配置,其中 online-dsn 与 test-dsn 的默认 schema 均指向 sakila:
online-dsn:
addr: 127.0.0.1:3306
schema: sakila
user: root
password: "1tIsB1g3rt"
disable: false
test-dsn:
addr: 127.0.0.1:3306
schema: sakila
user: root
password: "1tIsB1g3rt"
disable: false
这两个配置项在 common/config.go 中被解析。也就是说,只要用户在自己的 MySQL 中导入了 test/sql/init.sql.gz,并按此配置填好连接信息,SOAR 就能在真实数据库环境中执行 EXPLAIN、采样、表结构检查等依赖元数据的操作,测试 SQL 中的 sakila.film、world_x 相关表也才有据可依。
常见问题与注意事项
- 版本注释别写错:
film_text用/*!50610 */(MySQL 5.6.10),city/countryinfo用/*!50708 */(MySQL 5.7.8)。数字代表"该版本号及以上的服务器才执行这段语句",写错会导致低版本导入报错或高版本缺少功能。 - 合并前确认 SQL 文件完整性:README 要求将 sakila 的 schema 与数据先合并为
sakila.sql,再与world_x.sql合并为init.sql,顺序不可颠倒。 - 导入环境要求:world_x 的 JSON 列在低于 MySQL 5.7.8 的服务器上会被版本注释屏蔽;如果你要在低版本环境完整测试 JSON 相关规则,需要额外评估。
- 测试库是只读基准:仓库只读、测试库文件也不应修改;若需调整测试 SQL,应走项目自身的 PR/评审流程,而不是直接改
init.sql.gz。
小结
test/sql/README.md 虽然只有寥寥数行,却定义了 SOAR 测试基础设施的关键一环:sakila 提供业务表结构与数据,world_x 提供 JSON 数据类型支撑,两者经版本注释适配、合并、gzip 压缩后,成为 test/sql/init.sql.gz。结合 common/cases.go、test/query.bats、test/test_helper.bash 与 etc/soar.yaml 可以看到,这套测试库贯穿了 SQL 集合定义、报告生成、golden 回归、DSN 配置的全流程。如果你想在本地完整复现 SOAR 的自测环境,只需按本文流程构建 init.sql 并导入 MySQL,即可获得与项目 CI 一致的测试基座。