ShardingSphere 5.2.1 发布｜新增系统库、强制分片路由、一致性校验

Apache ShardingSphere 本周迎来了 5.2.1 版本的发布，该版本历时一个半月，共合并了来自全球的团队和个人累计 614 个 PR，新版本在功能、性能、测试、文档、示例等方面都进行了大量的优化。

本次 5.2.1 版本带来了如下亮点功能：

• ShardingSphere 系统库

• SQL HINT 强制分片路由

• 异步数据一致性校验

为了打造完善的 ShardingSphere 分布式数据库能力，5.2.1 版本引入了新的 ShardingSphere 系统库，旨在为分布式数据库提供基础的统计信息。通过 ShardingSphere 系统库提供的统计信息，可以辅助 SQL Federation 执行引擎估算执行代价，选择代价最小的执行计划。此外，ShardingSphere 系统库还可提供数据分片后的分布信息，为自动化的分片扩缩容管理提供参考依据。

SQL HINT 是 ShardingSphere 5.x 版本提供的重要功能，用户可以通过 SQL 注释的方式来灵活控制路由。本次 5.2.1 版本对 SQL Hint 的能力进行了增强，支持了数据分片强制路由，用户添加

/* SHARDINGSPHERE_HINT: t_order.SHARDING_DATABASE_VALUE=1, t_order.SHARDING_TABLE_VALUE=1 */ 格式的注释，就可以将分片值传递给 ShardingSphere 路由引擎，相比之前版本的 HintManager 方式，SQL HINT 方式更加灵活，无需用户编写代码。

本次 5.2.1 版本还对数据迁移功能中的数据一致性校验进行了增强，允许异步执行数据一致性校验，用户可以通过 DistSQL 查看数据迁移的进度，数据迁移功能的易用性大大提升。5.2.1 版本还增加了治理中心对 Consul 和 Nacos 的支持，为用户提供了更多的选择，SQL 支持度也进行了大幅度地提升，读写分离功能对从库禁用后 Proxy 的启动进行了优化，支持用户使用 -f 参数进行强制启动。本文将为大家详细介绍 ShardingSphere 5.2.1 版本的更新内容。

新亮点介绍

• ShardingSphere 系统库

为了打造更加完善的分布式数据库，ShardingSphere 5.2.1 版本新增了系统库功能，ShardingSphere 系统库和 MySQL、PostgreSQL 的系统库类似，都是用于对数据库的元数据进行管理。ShardingSphere 系统库存储的信息主要包括了动态元数据和静态元数据。动态元数据是指会频繁动态更新的数据，例如分布式数据库的统计信息，动态元数据需要通过内置的调度任务定时进行收集维护；静态元数据则是指在用户不修改的情况下，不会发生变更的数据，例如用户对 ShardingSphere 分布式数据库设置的状态参数，这些数据只需要存储在元数据库中提供查询即可。

由于 ShardingSphere 系统库目前还是实验性功能，因此在使用该功能时，需要通过如下配置开启元数据收集：

proxy-metadata-collector-enabled: true

通过命令行连接 Proxy，然后执行 SHOW DATABASES 语句，我们可以看到新增的 shardingsphere 数据库，该库中存储了分布式数据库的元数据信息。

目前，shardingsphere 数据库中增加了 sharding_table_statistics 表，用于对分片表的分布信息进行统计，包括了 row_count 和 size 等信息。

通过 ShardingSphere 系统库提供的统计信息，可以辅助 SQL Federation 执行引擎估算执行代价，选择合适的关联顺序和方式，达到高效执行的目的。此外，ShardingSphere 还可以根据数据分布信息以及存储节点负载信息，自动化地完成分片扩缩容，减少用户的运维管理成本。

• SQL HINT 强制分片路由

在某些特殊的业务场景中，用户用于分片的字段不存在 SQL 和数据库表结构中，而存在于外部业务逻辑中，此时需要使用 Hint 的方式传入分片键值来完成分片路由。在 5.2.1 之前的版本中，有两种使用 Hint 的方式可供选择，一种是在 JDBC 接入端，通过 HintManager 的方式来使用，而另一种则是在 Proxy 接入端，通过开启 proxy-hint-enabled 参数来使用该功能。

JDBC 接入端使用 HintManager 方式如下，用户需要编写代码调用 addDatabaseShardingValue 和 addTableShardingValue 方法来设置分库和分表的值。HintManager 编写代码的方式需要用户对原有逻辑进行改造，有一定的改造成本。

// Sharding database and table with using HintManagerString sql = "SELECT * FROM t_order";
try (HintManager hintManager = HintManager.getInstance();
     Connection conn = dataSource.getConnection();
     PreparedStatement preparedStatement = conn.prepareStatement(sql)) {
    hintManager.addDatabaseShardingValue("t_order", 1);
    hintManager.addTableShardingValue("t_order", 2);
    try (ResultSet rs = preparedStatement.executeQuery()) {
        while (rs.next()) {
            // ...        }
    }
}

Proxy 接入端使用 Hint 功能，需要先开启 proxy-hint-enabled 参数，然后通过如下的 DistSQL 设置和清除分片值。Proxy 接入端这种方式，会将 Proxy 的线程处理模型由 IO 多路复用变更为每个请求一个独立的线程，会降低 Proxy 的吞吐量，需要用户进行权衡。

-- 针对当前连接，为表 xx 添加分片值 yy，xx：逻辑表名称，yy：数据库分片值
ADD SHARDING HINT DATABASE_VALUE t_order= 100;
 
-- 针对当前连接，为表 xx 添加分片值 yy，xx：逻辑表名称，yy：表分片值
ADD SHARDING HINT TABLE_VALUE t_order = 100;
 
-- 针对当前连接，清除 sharding hint 设置
CLEAR SHARDING HINT;

为了解决 JDBC 接入端 HintManager 和 Proxy 接入端 DistSQL 这两种使用方式存在的问题，5.2.1 版本增加了 SQL Hint 强制分片路由的功能，允许用户通过 SQL 注释的方式来灵活控制路由，无需改造原有代码逻辑，也不会对 Proxy 接入端的线程处理模型产生影响。

使用 SQL Hint 强制路由分片功能需要用户提前开启解析注释的配置，设置 sqlCommentParseEnabled 为 true。注释格式暂时只支持 /* */，内容需要以 SHARDINGSPHERE_HINT: 开始，可选的属性包括：

• {table}.SHARDING_DATABASE_VALUE：用于添加 {table} 对应的数据源分片键值，多个属性使用逗号分隔；

• {table}.SHARDING_TABLE_VALUE：用于添加 {table} 对应的表分片键值，多个属性使用逗号分隔。

分库不分表情况下，强制路由至某一个分库时，可使用 SHARDING_DATABASE_VALUE 方式添加分片，无需指定 {table}。

下面是使用 HINT_INLINE 算法的示例：

rules:
- !SHARDING
  tables:
    t_order:
      actualDataNodes: ds_${0..1}.t_order_${0..1}
      databaseStrategy:
        hint:
          shardingAlgorithmName: database_hint_inline
      tableStrategy:
        hint:
          shardingAlgorithmName: t_order_hint_inline
  defaultDatabaseStrategy:
    none:
  defaultTableStrategy:
    none:
 
  shardingAlgorithms:
    database_hint_inline:
      type: HINT_INLINE
      props:
        algorithm-expression: ds_${value % 2}
    t_order_hint_inline:
      type: HINT_INLINE
      props:
        algorithm-expression: t_order_${value % 2}

我们可以通过 SQL Hint 的方式传入 t_order 表对应的分片值，通过 PREVIEW 语句我们可以看到，虽然 SQL 语句中没有指定分片键，但是 SQL Hint 传入的分片键值对，同样达到了分片路由的效果。

/* SHARDINGSPHERE_HINT: t_order.SHARDING_DATABASE_VALUE=1, t_order.SHARDING_TABLE_VALUE=1 */
SELECT * FROM t_order;
 
PREVIEW /* SHARDINGSPHERE_HINT: t_order.SHARDING_DATABASE_VALUE=1, t_order.SHARDING_TABLE_VALUE=1 */ SELECT * FROM t_order;
+------------------+----------------------------------------------------------------------------------------------------------------------+
| data_source_name | actual_sql                                                                                                           |
+------------------+----------------------------------------------------------------------------------------------------------------------+
| ds_1             | /* SHARDINGSPHERE_HINT: t_order.SHARDING_DATABASE_VALUE=1, t_order.SHARDING_TABLE_VALUE=1 */ SELECT * FROM t_order_1 |
+------------------+----------------------------------------------------------------------------------------------------------------------+

• 异步数据一致性校验

5.2.1 之前版本中，用户在执行 DistSQL 进行数据一致性校验时，需要同步地等待服务端返回校验结果，有时会因校验的耗时等原因，导致数据库客户端的 session 出现超时，此时用户无法观察到校验结果，只能去日志里查看，对用户非常不友好。因此，5.2.1 版本提供了数据一致性校验的异步执行能力，并提供了查询校验进度、开启校验作业、关闭校验作业等一套 DistSQL，方便用户对数据迁移进行管理。

如下是数据一致性校验异步执行相关的 DistSQL：

• CHECK MIGRATION jobId——异步校验数据一致性

• SHOW MIGRATION CHECK STATUS jobId——查询一致性校验进度

• START MIGRATION CHECK jobId——开启校验作业

• STOP MIGRATION CHECK jobId——关闭校验作业

通过这些 DistSQL，用户可以方便地对数据迁移进行管理，下面是异步一致性校验功能的使用示例：

-- 执行一致性校验
mysql> CHECK MIGRATION 'j0101270cbb6714cff0d7d13db9fa23c7c0a1' BY TYPE (NAME='DATA_MATCH');
Query OK, 0 rows affected (0.24 sec)
 
-- 查看一致性校验进度
mysql> SHOW MIGRATION CHECK STATUS 'j0101270cbb6714cff0d7d13db9fa23c7c0a1';
+---------+--------+---------------------+-------------------+-------------------------+----------------+------------------+---------------+
| tables  | result | finished_percentage | remaining_seconds | check_begin_time        | check_end_time | duration_seconds | error_message |
+---------+--------+---------------------+-------------------+-------------------------+----------------+------------------+---------------+
| t_order | false  | 0                   | 2450              | 2022-10-12 16:07:17.082 |                | 14               |               |
+---------+--------+---------------------+-------------------+-------------------------+----------------+------------------+---------------+
1 row in set (0.02 sec)
 
-- 关闭一致性校验
mysql> STOP MIGRATION CHECK 'j0101270cbb6714cff0d7d13db9fa23c7c0a1';
Query OK, 0 rows affected (0.06 sec)
 
-- 开启一致性校验
mysql> START MIGRATION CHECK 'j0101270cbb6714cff0d7d13db9fa23c7c0a1';
Query OK, 0 rows affected (5.13 sec)

更多关于异步数据一致性校验功能的使用，可参考官方文档及后续 技术文章解读（https://shardingsphere.apache.org/document/current/cn/user-manual/shardingsphere-proxy/migration/usage/）。

已有能力提升

内核

本次更新社区优化了 Oracle 和 PostgreSQL 数据库的 SQL 解析，大大提升了 ShardingSphere 的 SQL 兼容能力，在更新日志部分可以看到详细的 SQL 解析优化内容。SQL 解析支持度提升是 ShardingSphere 社区的长期重点任务，欢迎感兴趣的同学参与进来。

5.2.1 版本还支持了读写分离功能，在从库禁用后支持 ShardingSphere-Proxy 启动，并且允许用户使用 -f 参数对 Proxy 进行强制启动，以保证在部分存储节点不可用时，仍然能够启动 Proxy 进行运维管理。此外，内核功能中还增强了 SHOW PROCESSLIST 语句的展示结果，增加了 Sleep 状态的线程展示。通过优化单播路由的逻辑，尽可能复用缓存的数据库连接，使得 ShardingSphere 的执行性能得到提升。

弹性伸缩

弹性伸缩模块，本次支持了对只有唯一键的表进行数据迁移，同时允许表迁移到新的表名。此外还优化了数据迁移功能的线程池使用，数据一致性校验支持可中断，大大提升了用户对数据迁移功能的管控能力。

分布式治理

分布式治理功能中，本次增加了对 Consul 和 Nacos 治理中心的支持，为用户提供了更多的选择。同时，单机模式场景下，使用了内置的 H2 数据库支持持久化元数据信息。在运行模式中，移除了 overwrite 配置项，元数据信息以治理中心的数据为准，用户可以通过 DistSQL 对规则和配置进行动态修改。

更新日志

以下为 ShardingSphere 5.2.1 的全部更新日志，为了提升用户的使用体验，本次更新中调整了部分功能的 API，调整项具体参考本文更新日志的 API 调整部分。

新特性

• 新增 ShardingSphere 默认系统库以支持全局元数据管理

• 数据一致性校验支持异步执行

• 增加 Consul 治理中心的支持

• 增加 Nacos 治理中心的支持

• 新增治理中心对视图功能的支持

优化

• SQL Federation 新增 ADVANCED 执行器并适配 openGauss 数据库

• 读写分离从库禁用后支持 ShardingSphere-Proxy 启动

• SQL HINT 支持强制分片路由

• Show processlist 支持展示 Proxy 连接（sleep、active）

• 优化 ShardingSphere-JDBC 数据源配置错误提示

• ShardingSphere-JDBC 支持 SpringBoot 3.x 版本

• 支持加载 MySQL，PostgreSQL，openGauss 和 SQL Server 视图元数据

• 升级 Snakeyaml 到 1.33 并打开 YAML 3MB 限制

• 单播路由时尽可能复用缓存的数据库连接

• 支持 Oracle ALTER ROLE 语句解析

• 支持 Oracle ALTER RESOURCE COST 语句解析

• 支持 Oracle Drop Materialized View 语句解析

• 支持 Oracle DROP LIBRARY 语句解析

• 支持 Oracle DROP JAVA 语句解析

• 支持 Oracle DROP PLUGGABLE DATABASE 语句解析

• 支持 Oracle DROP INDEX TYPE 语句解析

• 支持 Oracle ALTER PACKAGE 语句解析

• 支持 Oracle openGauss select offset，count 语句解析并删除 PostgreSQL 中的错误语法

• 支持 openGauss max_size 语法解析

• 优化 alter view/drop view 解析逻辑

• ParseCancellationException 添加解析异常详细信息

• 支持 PostgreSQL OptOnConflict 语法解析

• 增加 PostgreSQL ALTER TABLE 和 ALTER VIEW 语句解析

• 为 PostgreSQL Declare 语句增加缺失的 keyword

• 支持 MySQL json function 解析

• ShardingSphere-Proxy Docker 环境自动适应 cgroup 内存限制

• 迁移详情新增错误消息字段

• 迁移详情新增已处理记录数字段

• 增量同步兼容 MySQL 8 caching_sha2_password 认证方式

• 改进迁移流程配置删除逻辑

• 支持只有唯一键的表迁移

• 支持表迁移到新的表名

• 优化线程池使用

• 数据一致性校验支持可中断

• DistSQL：创建或修改读写分离规则时，检查重复的写库或读库

• DistSQL：为 `ALTER SHARDING BINDING TABLE RULES` 增加有效性校验

• 单机模式 H2 支持持久化元数据信息

• 事务内支持 Postgresql/openGauss cursor 语法

• 新增事务相关异常

问题修复

• 修复 PostgreSQL 占位符改写后语法错误的问题

• 修复 openGauss update set 语句解析异常

• 修复 insert values 中包含负数时解析异常

• 修复 OracleDataSourceMetaData 中错误的 connectDescriptorUrlPattern

• 修复 Insert 语句在特定条件下改写出错的问题

• 修复执行 select * from information_schema.tables 时的异常

• 修复执行 alter view rename 时的异常

• 修复 InlineShardingAlgorithm 算法分片值超出 Integer 时出现的路由异常

• 修复使用 PostgreSQL rolsuper 情况下的数据源权限校验

• DistSQL：修复无数据源时 `REFRESH TABLE METADATA` 发生 NPE 的问题

• 修复修改规则时未修饰表元数据信息

• 修复数据库发现 MySQL.NORMAL_REPLICATION 算法无法发现主库问题

• 修复使用 Etcd 搭建集群事件不感知

• 修复事务管理器重建期间空指针异常

API 调整

• SQL HINT 语法格式调整为 SQL 风格格式

• DistSQL：移除语法 `COUNT DATABASE RULES`

• 运行模式移除 overwrite 配置项

• Agent: agent.yaml 配置方式优化

相关链接

🔗 下载链接：

https://shardingsphere.apache.org/document/current/cn/downloads/

🔗 更新日志：

https://github.com/apache/shardingsphere/blob/master/RELEASE-NOTES.md

🔗 项目地址：

https://shardingsphere.apache.org/

🔗 Cloud 子项目地址：

https://github.com/apache/shardingsphere-on-cloud

社区建设

此次 Apache ShardingSphere 5.2.1 版本的发布，共有 38 位 Contributor 提交了 614 个 PR，感谢社区伙伴们的大力支持。