SQL 语法校验工具 - 敏捷诊断工具 V4.3.0

SQL 语法校验工具

更新时间：2026-07-23 16:36:01

自 V4.3.0 起，obdiag 提供 obdiag tool sql_syntax 命令：在已连接的 OceanBase 实例上对单条 SQL 执行 EXPLAIN <YOUR_SQL>，用于校验语法及部分语义问题，不会执行原始 DML/DDL 语句本身。

说明

本工具用于快速验证「能否解析/能否生成计划」，与 obdiag gather plan_monitor（按 trace 收集计划与统计信息等）用途不同。
本工具与基于规则的批量 SQL 审核不同：obdiag analyze sql/obdiag analyze sql_review 走内置 Review 规则并出报告。具体介绍可参见 SQL 审计分析与规则审核、SQL 文件审核。

功能说明

连接成功后，在服务端执行 EXPLAIN；若 OceanBase 数据库返回语法类错误（如错误码 1064），则报告 SYNTAX ERROR 并输出详情。
其它错误可能归类为语义/权限等，输出中会标明 VALID (syntax OK, but semantic error …) 等提示，便于区分「纯语法」与「其它执行前错误」。

限制与约束

仅支持单条语句：若 SQL 中含分号且后面仍有非空内容（多语句），命令执行会被拒绝。
需有效连接：通过 --env 提供 host、port、user、database，或依赖 -c 指定的 config.yml 文件中的 obcluster.db_host、db_port、tenant_sys.user、db 等。其中，host、port 和 user 必须提供，database/db 为可选项。
末尾分号：工具会自动去掉末尾分号再拼接 EXPLAIN。

注意事项

请确保账户对目标库有执行 EXPLAIN 的权限。
若连接信息不完整，命令会提示通过 --env 或配置文件补全 host/port/user。

命令说明

obdiag tool sql_syntax [options]

选项名	是否必选	说明
--sql	是	待校验的单条 SQL。
--env	否	指定执行 SQL 所用租户的连接信息，可多次指定，格式 `--env key=value`。常用键：`host`、`port`、`user`、`password`/`pwd`、`database`/`db`。若 `--env` 中已给出完整连接信息，优先使用 `--env`；未配置 `--env` 的情况下将使用 `-c` 选项指定的配置文件。
-c	否	配置文件路径，默认 `~/.obdiag/config.yml`。
--config	否	需被 obdiag 诊断的集群的配置，格式：`--config key1=value1 --config key2=value2`。支持通过该选项配置的参数可参见 obdiag 配置。
--config_password`	否	使用加密配置文件时的解密密码。具体介绍可参见配置文件加密。
-h/--help	否	查看帮助。
-v/--verbose	否	详细日志。

使用示例

使用配置文件中的集群连接（仅需提供 SQL）：

obdiag tool sql_syntax --sql "SELECT * FROM t1 WHERE id = 1"

使用 --env 覆盖连接信息：

obdiag tool sql_syntax \
  --sql "SELECT * FROM dual" \
  --env host=127.0.0.1 \
  --env port=2881 \
  --env user=root@sys \
  --env password=******
  --env database=test