ShardingSphere-SQL 解析 Issue 处理流程

这是之前给社区写的 SQL 解析 Issue 的处理流程，可以帮助社区用户快速参与到 ShardingSphere-SQL 解析当中。

ShardingSphere SQL 解析 issue 列表

Issue 背景说明

当前 Issue 使用自定义的爬虫脚本从对应的数据库官网上抓取 SQL Cases，然后交给 ShardingSphere 的解析引擎进行解析。对于解析失败的 SQL Case，每 3~5 条 SQL 作为一个 Issue。

  1. 由于是通过爬虫抓取的，所以不保证所有 SQL 本身就是正确的，请按照如下流程处理该 PR。
  2. 有些 SQL Case 可能已经在其他 PR 里被修复，对于已经可以执行的 Case 直接留言忽略即可。
  3. 如果该 SQL Case 已经可以成功运行，没有任何代码改动，那么不需要添加对应的 Test 断言文件。

总体流程

  1. 如果你打算参与该 Issue 的修复，欢迎在 Issue 下方留言，会有社区同学分配该 Issue。

比如留言：Hi, please assign this issue to me. Thank you!

  1. 当认领到 Issue 之后，请在对应数据库的官网上查看该 SQL 的相关语法，并在对应的数据库上执行该 SQL 确保 SQL 本身语法的正确性。

举个例子，对于 Issue: https://github.com/apache/shardingsphere/issues/30305

总共包含 3 条有问题的 SQL Cases。

可以通过 case 下方的 link 查看该条 SQL 在数据库官网上对应的出处。

点开官网链接后，查看相关 SQL 语法。如果链接里不包含对应的 SQL 语法，此时需要您自行搜索相关 SQL 语法。

比如此处官网对应的语法示例如下：

接着把上述有问题的 SQL CASE 放到数据库里执行（可以使用对应数据库的 Docker 镜像快速启动对应数据库，然后使用您熟悉的客户端进行连接），确保 SQL 语法本身没有问题。

ANTLR 语法解析问题修复

确定 SQL 语法正确之后，可以在 ShardingSphere 里验证并修复该语法解析问题。

如果您使用的是 Intellij IDEA，需要先安装 ANTLR 插件。

当插件安装完成之后，在 IDEA 底部菜单栏中找到 ANTLR Preview 菜单。

下面打开第一条 SQL CREATE TABLE 对应的 .g4 文件。目前.g4 规则已经按照 SQL 类型进行分类，比如CREATE TABLE 语法规则在 DDLStatement.g4文件中。

在 DDLStatement.g4 文件里 createTable 这条规则上右键->Test Rule Xxx。然后将有问题的 SQL 粘贴到底部的 ANTLR Preview 窗口中。

此时可以看到 ANTLR 解析报错的信息，根据报错信息对照数据库官方语法尝试修复 .g4 文件，直到 SQL 可以被 ANTLR 正确的解析。

可以在修复.g4 语法过程中，实时通过执行 Test Rule Xxx 在 ANTLR Preview 窗口中观察语法问题是否已经被成功修复。

当 ANTLR Preview 窗口不再有报错信息，表示 ANTLR 已经可以正确解析该条 SQL 了。

Visitor 问题修复

ANTLR 将 SQL 解析成抽象语法树之后，ShardingSphere 会通过 Visitor 访问抽象语法树，提取所需的信息。

如果需要提取 Segment，需要先在 shardingsphere-parser 模块下，执行 mvn -T 2C clean install -DskipTests 编译整个 parser 模块。

然后按需重写 SQLStatementVisitor 里对应的 visit 方法，提取对应的 Segment。

参考 https://github.com/apache/shardingsphere/pull/30258

添加断言测试文件

当上面 SQL 解析问题修复完毕之后，需要添加对应的 Test，步骤如下：

  1. 在 sql/supported 目录下添加对应的 sql-case。
  2. 在 shardingsphere-test-it-parser 模块的 case 目录下添加 case 断言。

  1. 运行 org.apache.shardingsphere.test.it.sql.parser.internal.InternalSQLParserIT，确保 SQL Parser IT 可以正常运行。

InternalSQLParserIT 对于每种数据库方言，提供了对应实现。比如此处运行 InternalSQLServerParserIT。

当 SQL Parser IT 运行成功之后，即可提交 PR。