SQL 解析器指南 | SQL Parser Guide

中文

Druid SQL 解析器是一个高性能、支持多方言的 SQL 解析引擎，可将 SQL 文本解析为 AST（抽象语法树），支持 SQL 格式化、Schema 分析、SQL 改写等多种场景。

快速入门

解析 SQL

java

import com.alibaba.druid.sql.SQLUtils;
import com.alibaba.druid.sql.ast.SQLStatement;
import com.alibaba.druid.DbType;

String sql = "SELECT u.id, u.name, o.amount "
           + "FROM users u JOIN orders o ON u.id = o.user_id "
           + "WHERE o.amount > 100 ORDER BY o.amount DESC";

// 解析为 AST
List<SQLStatement> stmts = SQLUtils.parseStatements(sql, DbType.mysql);
SQLStatement stmt = stmts.get(0);

格式化 SQL

java

String ugly = "select id,name from users where age>18 and status='active' order by name";

// 格式化输出
String formatted = SQLUtils.format(ugly, DbType.mysql);
// 输出:
// SELECT id, name
// FROM users
// WHERE age > 18
//   AND status = 'active'
// ORDER BY name

// 带配置的格式化
SQLUtils.FormatOption option = new SQLUtils.FormatOption();
option.setUppCase(true);     // 关键字大写（注意：API 方法名 setUppCase 双 p 是源码中的已有拼写）
option.setPrettyFormat(true); // 美化格式
String result = SQLUtils.format(ugly, DbType.mysql, option);

Schema 分析

java

import com.alibaba.druid.sql.visitor.SchemaStatVisitor;

String sql = "SELECT u.name, o.total FROM users u "
           + "JOIN orders o ON u.id = o.user_id "
           + "WHERE u.age > 18";

List<SQLStatement> stmts = SQLUtils.parseStatements(sql, DbType.mysql);
SchemaStatVisitor visitor = SQLUtils.createSchemaStatVisitor(DbType.mysql);
stmts.get(0).accept(visitor);

// 获取表信息
System.out.println("Tables: " + visitor.getTables());
// 输出: {users=Select, orders=Select}

// 获取列信息
System.out.println("Columns: " + visitor.getColumns());
// 输出: [users.name, orders.total, users.id, orders.user_id, users.age]

// 获取 WHERE 条件
System.out.println("Conditions: " + visitor.getConditions());
// 输出: [users.id = orders.user_id, users.age > 18]

核心 API

SQLUtils — 入口工具类

方法	说明
`parseStatements(sql, dbType)`	解析 SQL 文本为语句列表
`parseSingleStatement(sql, dbType, features...)`	解析单条 SQL 语句（可传入 `SQLParserFeature` 可变参数）
`format(sql, dbType)`	格式化 SQL
`format(sql, dbType, option)`	带选项格式化 SQL
`toSQLString(sqlObject, dbType)`	AST 节点输出为 SQL 文本
`createSchemaStatVisitor(dbType)`	创建 Schema 统计访问者

AST 核心节点

节点类型	基类	说明
语句	`SQLStatement`	一条完整的 SQL 语句（SELECT、INSERT、CREATE TABLE 等）
表达式	`SQLExpr`	表达式节点（列引用、常量、函数调用、运算等）
表源	`SQLTableSource`	FROM 子句中的表引用
数据类型	`SQLDataType`	列的数据类型定义

常见 SQLStatement 子类：

类	对应 SQL
`SQLSelectStatement`	SELECT
`SQLInsertStatement`	INSERT
`SQLUpdateStatement`	UPDATE
`SQLDeleteStatement`	DELETE
`SQLCreateTableStatement`	CREATE TABLE
`SQLAlterTableStatement`	ALTER TABLE
`SQLDropTableStatement`	DROP TABLE
`SQLCreateIndexStatement`	CREATE INDEX

常见 SQLExpr 子类：

类	说明	示例
`SQLIdentifierExpr`	标识符	`name`、`users`
`SQLPropertyExpr`	属性表达式	`u.name`、`db.table`
`SQLIntegerExpr`	整数常量	`42`
`SQLCharExpr`	字符串常量	`'hello'`
`SQLBinaryOpExpr`	二元运算	`a > 10`、`x + y`
`SQLMethodInvokeExpr`	函数调用	`COUNT(*)`、`NOW()`
`SQLInListExpr`	IN 列表	`id IN (1, 2, 3)`
`SQLBetweenExpr`	BETWEEN	`age BETWEEN 18 AND 30`

Visitor 模式

Druid 使用 Visitor 模式遍历 AST。核心访问者接口：

Visitor	功能
`SQLASTVisitor`	基础访问者接口
`SQLASTOutputVisitor`	SQL 输出（AST → SQL 文本）
`SchemaStatVisitor`	Schema 统计（提取表、列、条件信息）
Dialect-specific Visitors	各方言特化的访问者

自定义 Visitor 示例

java

import com.alibaba.druid.sql.visitor.SQLASTVisitorAdapter;
import com.alibaba.druid.sql.ast.expr.SQLBinaryOpExpr;

// 统计所有二元运算表达式
public class BinaryOpCounter extends SQLASTVisitorAdapter {
    private int count = 0;

    @Override
    public boolean visit(SQLBinaryOpExpr x) {
        count++;
        return true;  // 继续遍历子节点
    }

    public int getCount() { return count; }
}

// 使用
BinaryOpCounter counter = new BinaryOpCounter();
stmt.accept(counter);
System.out.println("Binary ops: " + counter.getCount());

SQL 改写

通过操作 AST 实现 SQL 改写：

java

// 添加 WHERE 条件
String sql = "SELECT * FROM users";
SQLSelectStatement stmt = (SQLSelectStatement) SQLUtils.parseSingleStatement(sql, DbType.mysql);
SQLSelectQueryBlock queryBlock = stmt.getSelect().getQueryBlock();

// 添加 tenant_id 条件
SQLBinaryOpExpr condition = new SQLBinaryOpExpr(
    new SQLIdentifierExpr("tenant_id"),
    SQLBinaryOperator.Equality,
    new SQLIntegerExpr(123)
);
queryBlock.addWhere(condition);

System.out.println(SQLUtils.toSQLString(stmt, DbType.mysql));
// 输出: SELECT * FROM users WHERE tenant_id = 123

方言特定解析

不同方言有特定的语法扩展。使用正确的 DbType 以获得最佳解析结果：

java

// MySQL 特有语法
SQLUtils.parseStatements("SELECT * FROM t LIMIT 10, 20", DbType.mysql);

// PostgreSQL 特有语法
SQLUtils.parseStatements("SELECT * FROM t LIMIT 20 OFFSET 10", DbType.postgresql);

// Oracle 特有语法
SQLUtils.parseStatements("SELECT * FROM t WHERE ROWNUM <= 20", DbType.oracle);

性能建议

重用 Parser — 在高频场景中避免重复创建 Parser 对象
选择正确的 DbType — 使用精确的方言类型，避免使用通用解析模式
按需遍历 — 使用 return false 跳过不需要遍历的子树

English

The Druid SQL Parser is a high-performance, multi-dialect SQL parsing engine that converts SQL text into AST (Abstract Syntax Tree), supporting SQL formatting, schema analysis, SQL rewriting and more.

Quick Start

java

// Parse SQL
List<SQLStatement> stmts = SQLUtils.parseStatements(sql, DbType.mysql);

// Format SQL
String formatted = SQLUtils.format(sql, DbType.mysql);

// Schema analysis
SchemaStatVisitor visitor = SQLUtils.createSchemaStatVisitor(DbType.mysql);
stmts.get(0).accept(visitor);
System.out.println("Tables: " + visitor.getTables());
System.out.println("Columns: " + visitor.getColumns());

Core API

SQLUtils.parseStatements(sql, dbType) — Parse SQL text into statement list
SQLUtils.format(sql, dbType) — Format SQL
SQLUtils.toSQLString(ast, dbType) — Convert AST back to SQL text
SQLUtils.createSchemaStatVisitor(dbType) — Create schema analysis visitor

AST Node Hierarchy

SQLStatement — Complete SQL statements (SELECT, INSERT, CREATE TABLE, etc.)
SQLExpr — Expressions (column refs, constants, function calls, operations)
SQLTableSource — Table references in FROM clauses
SQLDataType — Column data type definitions

Visitor Pattern

Use the Visitor pattern to traverse and transform the AST:

SQLASTVisitor — Base visitor interface
SQLASTOutputVisitor — SQL output generation
SchemaStatVisitor — Schema statistics extraction
Custom visitors — Extend SQLASTVisitorAdapter for custom logic

SQL Rewriting

Manipulate the AST to rewrite SQL:

java

SQLSelectStatement stmt = (SQLSelectStatement) SQLUtils.parseSingleStatement(sql, DbType.mysql);
SQLSelectQueryBlock queryBlock = stmt.getSelect().getQueryBlock();
queryBlock.addWhere(new SQLBinaryOpExpr(
    new SQLIdentifierExpr("tenant_id"),
    SQLBinaryOperator.Equality,
    new SQLIntegerExpr(123)
));
String rewritten = SQLUtils.toSQLString(stmt, DbType.mysql);