ShardingSphere-Proxy 入门教程之一
大纲
- ShardingSphere-Proxy 入门教程之一、ShardingSphere-Proxy 入门教程之二、ShardingSphere-Proxy 入门教程之三
- ShardingSphere-Proxy 入门教程之四、ShardingSphere-Proxy 入门教程之五、ShardingSphere-Proxy 入门教程之六
- ShardingSphere-Proxy 入门教程之七
前言
学习资源
- ShardingSphere 官方项目(GitHub)
- ShardingSphere 官方网站(中文站点)
- ShardingSphere 官方文档(最新版本)
- ShardingSphere 官方文档(5.1.1 版本)
ShardingSphere-Proxy 安装
安装方式
目前 ShardingSphere-Proxy 官方提供了三种安装方式:
- Docker
- Helm(K8s)
- 二进制发布包
安装步骤
ShardingSphere-Proxy 配置
两种配置方式
- ShardingSphere-Proxy 支持两种规则配置与治理方式:
- YAML 配置文件,适用于启动期静态配置。
- DistSQL(Distributed SQL),适用于运行期动态治理。
特别注意
DistSQL 只能用于 ShardingSphere-Proxy,而 ShardingSphere-JDBC 暂不提供支持。无论 ShardingSphere-Proxy 是使用 YAML 配置 还是 DistSQL 配置,都必须注意 ShardingSphere-Proxy 的版本差异。不同版本之间支持的 DistSQL 命令、YAML 配置语法以及参数格式可能存在较大差异,同一份配置在不同版本下可能无法直接执行或行为不一致,因此在编写和迁移配置时必须结合 ShardingSphere-Proxy 具体版本进行验证。
DistSQL 的介绍
DistSQL 的基本定位
- DistSQL(Distributed SQL) 是 ShardingSphere 提供的一套分布式数据库治理语言。
- DistSQL 用于在线管理和调整 ShardingSphere-Proxy 的规则、资源及算法配置,并非用于查询或操作业务数据。
- 当 ShardingSphere-Proxy 识别到 DistSQL 时:
- 不会将该 SQL 转发给后端 MySQL
- 而是由 ShardingSphere-Proxy 自身解析并执行
- 执行结果存储在 ShardingSphere 的元数据 / 治理上下文中
DistSQL 出现之前的配置模式(静态配置时代)
- 在没有 DistSQL 的情况下,ShardingSphere-Proxy 的配置方式具有明显限制:
- 修改规则(如分片、读写分离)
→ 必须修改 YAML 配置文件 - 调整负载均衡策略
→ 必须修改 YAML 配置文件 - 配置变更后,需要重启 ShardingSphere-Proxy
- 重启 ShardingSphere-Proxy 会导致:
- 客户端连接全部断开
- 在生产环境中存在明显风险
- 修改规则(如分片、读写分离)
- 配置调整与服务可用性强耦合
- 在没有 DistSQL 的情况下,ShardingSphere-Proxy 的配置方式具有明显限制:
DistSQL 引入后的变化(在线治理能力)
- DistSQL 的引入,使 ShardingSphere-Proxy 具备了运行期动态治理能力:
- 新增或修改数据源
→ 不需要重启 ShardingSphere-Proxy - 创建、修改读写分离规则
→ 不需要重启 ShardingSphere-Proxy - 配置或切换负载均衡算法
→ 不需要重启 ShardingSphere-Proxy - 动态调整从库权重等参数
→ 不需要重启 ShardingSphere-Proxy
- 新增或修改数据源
- 配置变更即时生效,业务连接无感知
- DistSQL 的引入,使 ShardingSphere-Proxy 具备了运行期动态治理能力:
DistSQL 的三大语法
RDL(Resource Definition Language,资源定义语法)
- 作用:
- 定义、修改和管理数据库资源
- 特点:
- 面向 ShardingSphere-Proxy 运行时的资源管理
- 对应 YAML 中的
dataSources配置 - 可在线添加、修改、删除资源,无需重启 ShardingSphere-Proxy
- 用途:
- 创建 / 删除数据源
- 修改数据源属性(如连接池大小)
- 创建 / 修改分片规则或读写分离规则
- 作用:
RQL(Resource Query Language,资源查询语法)
- 作用:
- 查询 ShardingSphere-Proxy 内部资源、规则和状态信息
- 特点:
- 类似 SQL 查询语法,但不操作业务数据
- 返回 ShardingSphere-Proxy 内部元数据
- 用于监控和验证配置是否生效
- 用途:
- 查询已配置的数据源
- 查询读写分离规则
- 查询分片规则
- 查看负载均衡算法
- 作用:
RAL(Resource Administration Language,资源管理语法)
- 作用:
- 管理 ShardingSphere-Proxy 运行时状态和执行操作
- 特点:
- 类似运维命令
- 可动态调整 ShardingSphere-Proxy 规则和资源
- 不影响业务 SQL 执行,不访问后端数据
- 用途:
- 启用 / 禁用数据源
- 刷新表或分片规则元数据
- 修改读写分离规则的负载均衡算法
- 在线调整分片表规则
- 作用:
| 语法 | 作用 | 核心命令示例 | 对应 YAML 配置 |
|---|---|---|---|
| RDL 语法 | 定义 / 修改资源(数据源、分片表、规则) | ADD RESOURCE / CREATE SHARDING TABLE RULE | dataSources / rules |
| RQL 语法 | 查询资源 / 规则状态 | SHOW RESOURCES / SHOW READWRITE_SPLITTING RULES | 无直接 YAML 对应,用于验证 |
| RAL 语法 | 管理运行时状态 | ENABLE / DISABLE RESOURCE / REFRESH TABLE METADATA | 对应 YAML 中规则的动态修改 |
DistSQL 对系统的影响
在拥有 DistSQL 以前,用户一边使用 SQL 语句操作数据,一边使用 YAML 文件来管理 ShardingSphere-Proxy 的配置,如下图:

这时用户不得不面对以下几个问题:
- 需要通过不同类型的客户端来操作数据和管理 ShardingSphere-Proxy 规则;
- 多个逻辑库需要多个 YAML 文件;
- 修改 YAML 需要文件的编辑权限;
- 修改 YAML 后需要重启 ShardingSphere-Proxy。
随着 DistSQL 的出现,对 ShardingSphere-Proxy 的操作方式也得到了改变,如下图:

现在,用户的使用体验得到了巨大改善:
- 使用相同的客户端来管理数据和 ShardingSphere-Proxy 配置;
- 不再额外创建 YAML 文件,通过 DistSQL 管理逻辑库;
- 不再需要文件的编辑权限,通过 DistSQL 来管理配置;
- 配置的变更实时生效,无需重启 ShardingSphere-Proxy。
DistSQL 与 YAML 的关系
DistSQL 与 YAML 的职责划分
- YAML 配置
- 适合定义:
- 数据源基础信息
- 初始规则结构
- 在 ShardingSphere-Proxy 启动时加载
- 适合定义:
- DistSQL
- 适合运行期治理:
- 规则变更
- 算法切换
- 权重调整
- 状态查看
- 支持不停机操作
- 适合运行期治理:
- YAML 配置
DistSQL 与 YAML 不是对立的,而是分工明确。
| 场景 | 推荐方式 |
|---|---|
| 初始启动 | YAML |
| 运行期调整 | DistSQL |
| 生产环境 | YAML + DistSQL |
| 动态治理 | DistSQL |
DistSQL 与普通 SQL 的区别
| 对比项 | 普通 SQL | DistSQL |
|---|---|---|
| 操作对象 | 表 / 行 | 规则 / 数据源 / 算法 |
| 执行位置 | 数据库 | ShardingSphere-Proxy 内部 |
| 是否影响业务数据 | 不影响 | 不影响 |
| 是否持久化 | 数据表 | ShardingSphere-Proxy 元数据 |
| 是否需要重启 | 不需要重启 | 不需要重启 |
ShardingSphere-Proxy 使用
读写分离使用案例
提示
本节将演示 SpringBoot + MyBatis Plus 如何基于 ShardingSphere-Proxy 实现 读写分离,整体架构如下图所示。完整的案例代码可以直接从 GitHub 下载对应章节 shardingsphere-proxy-lesson-01。

准备工作
版本说明
本案例所使用的组件版本如下表所示:
| 组件 | 版本说明 |
|---|---|
| JDK | 11 |
| MySQL | 8.0.29 |
| SpringBoot | 2.7.18 |
| MyBatis-Plus | 3.3.1 |
| ShardingSphere-Proxy | 5.1.1 |
数据库规划
本案例是在 MySQL 一主二从的架构(请自行搭建 MySQL 主从复制环境)上实现的,数据库的规划如下图所示:

| 数据库服务器 | 主从角色 | IP | 端口 | 库的名称 | 表的名称 |
|---|---|---|---|---|---|
| 主服务器 | 主库(master) | 192.168.2.191 | 3306 | db_user | t_user |
| 从服务器一 | 从库(slave1) | 192.168.2.191 | 3307 | db_user | t_user |
| 从服务器二 | 从库(slave2) | 192.168.2.191 | 3308 | db_user | t_user |
| ShardingSphere-Proxy 服务器 | 192.168.2.191 | 3309 | readwrite_splitting_db(逻辑库) | t_user(逻辑表) |
MySQL 主从同步环境搭建
MySQL 基于日志点实现主从复制的教程可以看 这里。
数据库初始化
- 在 MySQL 主库(
master)中,执行以下 SQL 语句:
1 | -- 创建数据库 |
ShardingSphere-Proxy 配置
读写分离配置
ShardingSphere-Proxy 支持两种配置模式,包括 YAML 和 DistSQL,任意选择一种即可。
特别注意
无论 ShardingSphere-Proxy 是使用 YAML 配置 还是 DistSQL 配置,都必须注意 ShardingSphere-Proxy 的版本差异。不同版本之间支持的 DistSQL 命令、YAML 配置语法以及参数格式可能存在较大差异,同一份配置在不同版本下可能无法直接执行或行为不一致,因此在编写和迁移配置时必须结合 ShardingSphere-Proxy 具体版本进行验证。
YAML 模式
- 创建或编辑 ShardingSphere-Proxy 的
conf/config-readwrite-splitting.yaml配置文件,添加以下读写分离的配置内容:
1 | # 逻辑数据库(Schema)的名称 |
- ShardingSphere-Proxy 读写分离的配置内容添加完成后,需要重启 ShardingSphere-Proxy 服务(假设这里是通过 Docker 部署 ShardingSphere-Proxy 服务),否则配置不会生效
1 | # 重启 Docker 容器 |
- 验证 ShardingSphere-Proxy 中的配置规则是否生效(ShardingSphere-Proxy 启动时会从 YAML 配置文件中加载规则)
1 | # 远程连接 ShardingSphere-Proxy |
1 | -- 切换到逻辑数据库(Schema) |
DistSQL 模式
- 远程连接 ShardingSphere-Proxy
1 | mysql -h192.168.2.191 -P3309 -uroot -p |
- 创建逻辑数据库(Schema)
1 | -- 创建逻辑数据库(Schema) |
- 添加数据源
1 | -- 添加写数据源 |
1 | -- 添加读数据源一 |
1 | -- 添加读数据源二 |
- 创建读写分离规则(
TYPE用于指定负载均衡算法,可选:random、round_robin、weight)
1 | CREATE READWRITE_SPLITTING RULE readwrite_ds ( |
- 验证配置规则是否生效(使用 DistSQL 定义数据源和读写分离规则后,不需要重启 ShardingSphere-Proxy 服务,默认会自动生效)
1 | -- 查询所有数据库 |
查看日志信息
- 查看 ShardingSphere-Proxy 运行的实时日志信息
1 | # 进入容器内,其中环境变量 "env LANG=C.UTF-8" 用于避免容器内显示中文乱码的问题 |
特别注意
在开发或者测试环境中,若希望 ShardingSphere-Proxy 输出详细的日志信息,需要在其 conf/server.yml 配置文件中添加 sql-show: true 配置项。
远程访问测试
- 远程连接 ShardingSphere-Proxy
1 | mysql -h192.168.2.191 -P3309 -uroot -p |
- 查看所有数据库
1 | mysql> show databases; |
- 切换数据库
1 | mysql> use readwrite_splitting_db; |
- 查看所有表
1 | mysql> show tables; |
- 插入数据
1 | mysql> insert into t_user(uname) values('wang5'); |
- 查询数据(第一次)
1 | mysql> select * from t_user; |
- 查询数据(第二次)
1 | mysql> select * from t_user; |
提示
执行完上述 insert、select 操作后,可以在 ShardingSphere-Proxy 的日志信息中,查看对应的逻辑 SQL 和真实 SQL,以此判断读写分离是否生效。
SpringBoot 实战使用案例
案例代码
添加依赖
1 | <properties> |
创建实体类
1 | import com.baomidou.mybatisplus.annotation.IdType; |
创建 Mapper
1 | import com.baomidou.mybatisplus.core.mapper.BaseMapper; |
配置数据源
- 创建配置文件(
application.properties),配置数据源
1 | # 应用名称 |
测试代码
读写分离测试
1 |
|
测试代码运行后,ShardingSphere-Proxy 运行输出的日志信息如下:
1 | 16:00:07.139 [ShardingSphere-Command-17] INFO ShardingSphere-SQL - Logic SQL: INSERT INTO t_user ( uname ) VALUES ( '张三丰' ) |
事务一致性测试
为了保证主从库间的事务一致性,避免跨库的分布式事务, 在 ShardingSphere-Proxy 的主从模型中,事务内的数据读写均使用主库。
- 不添加
@Transactional注解时:insert语句对主库操作,select语句对从库操作 - 添加
@Transactional注解时:insert语句和select语句均对主库操作 - 注意: 在 JUnit 环境下使用
@Transactional注解,默认情况下会对事务进行回滚(即使在没有使用@Rollback注解的情况下,也会对事务进行回滚);如果不希望回滚事务,可以额外使用@Rollback(false)
1 |
|
测试代码运行后,ShardingSphere-Proxy 运行输出的日志信息如下:
1 | 15:57:23.174 [ShardingSphere-Command-3] INFO ShardingSphere-SQL - Logic SQL: INSERT INTO t_user ( uname ) VALUES ( '李思思' ) |
负载均衡测试
1 |
|
测试代码运行后,ShardingSphere-Proxy 运行输出的日志信息如下:
1 | 16:48:01.373 [ShardingSphere-Command-2] INFO ShardingSphere-SQL - Logic SQL: SELECT id,uname FROM t_user |
