---
title: "SQL 语法校验工具 - 敏捷诊断工具 V4.3.0 | OceanBase 文档中心"
description: SQL 语法校验工具 自 V4.3.0 起，obdiag 提供 obdiag tool sql_syntax 命令：在已连接的 OceanBase 实例上对 单条 SQL 执行 EXPLAIN <YOUR_SQL> ，用于校验语法及部分语义问题， 不会执行 原始 DML/DDL 语句本身。 说明 本工具用于快速验证「…
image: https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*OSPzQ6GUQF4AAAAAQHAAAAgAeiGDAQ/original
---
切换语言

- 中文站 - 简体中文
- International - English
- 日本站 - 日本語

文档反馈![](https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*5ZXST55u540AAAAAAAAAAAAADiGDAQ/original) 敏捷诊断工具V 4.3.0

# SQL 语法校验工具

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

[编辑](https://github.com/oceanbase/odt-doc/edit/V4.3.0/zh-CN/800.tool/805.sql_syntax.md)  

自 **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 审计分析与规则审核](https://www.oceanbase.com/docs/common-obdiag-cn-1000000005726853)、[SQL 文件审核](https://www.oceanbase.com/docs/common-obdiag-cn-1000000005726845)。

## 功能说明

- 连接成功后，在服务端执行 `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`。

## 命令说明

```shell
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 配置](https://www.oceanbase.com/docs/common-obdiag-cn-1000000005726796)。 |
| --config_password` | 否 | 使用加密配置文件时的解密密码。具体介绍可参见 [配置文件加密](https://www.oceanbase.com/docs/common-obdiag-cn-1000000005726841)。 |
| -h/--help | 否 | 查看帮助。 |
| -v/--verbose | 否 | 详细日志。 |

## 使用示例

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

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

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

  ```shell
  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

  ```

 上一篇 下一篇 ![有帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*y6ocSqN8cqsAAAAAAAAAAAAAARQnAQ)![无帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*BG9IQJyLHF8AAAAAAAAAAAAAARQnAQ)![反馈](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*eTWdQKCRKHwAAAAAAAAAAAAAARQnAQ)[AI](https://www.oceanbase.com/obi) 咨询热线