ShardingSphere-Proxy是透明化的数据库代理，支持任何使用 MySQL、PostgreSQL、openGauss 协议的客户端操作数据，对异构语言、运维场景相对友好。本文将介绍ShardingSphere-Proxy的安装和基本配置，包括安装包的下载及安装，权限配置、属性配置、server的属性配置等。

1.ShardingSphere-Proxy的安装的前提条件

1.ShardingSphere-Proxy可使用docker安装，前提是要安装docker；

2.也可直接使用二进制文件安装，前提是要安装Java JRE 8或以上版本。以下将介绍二级制文件安装方式。

2.ShardingSphere-Proxy的下载

官方下载地址：

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

找到ShardingSphere-Proxy 二进制包: TAR进行下载，当前版本: 5.3.1 ( 发布日期: Jan 10th, 2023 )，这里附上下载链接：

https://www.apache.org/dyn/closer.lua/shardingsphere/5.3.1/apache-shardingsphere-5.3.1-shardingsphere-proxy-bin.tar.gz

如果要下载历史版本，可以到这里找：

https://archive.apache.org/dist/shardingsphere/

3.ShardingSphere-Proxy的安装

1.首先先安装jdk1.8

安装jdk1.8可参考这里：linux安装jdk1.8

2.解压并安装到指定路径上

1
2
3

tar zxvf apache-shardingsphere-5.3.1-shardingsphere-proxy-bin.tar.gz
mv apache-shardingsphere-5.3.1-shardingsphere-proxy-bin shardingsphere-proxy-5.3.1
mv shardingsphere-proxy-5.3.1/ /usr/local/

3.引入依赖包

如果后端连接 PostgreSQL 或 openGauss 数据库，不需要引入额外依赖。

如果后端连接 MySQL 数据库，请下载 mysql-connector-java-5.1.47.jar 或者 mysql-connector-java-8.0.11.jar，并将其放入 %SHARDINGSPHERE_PROXY_HOME%/ext-lib 目录。

我们这里将jar包放到 /usr/local/shardingsphere-proxy-5.3.1/ext-lib

4.ShardingSphere-Proxy的启动停止

1
2
3

cd /usr/local/shardingsphere-proxy-5.3.1/bin/
./start.sh
./stop.sh

注：

默认启动端口为 3307，默认配置文件目录为：%SHARDINGSPHERE_PROXY_HOME%/conf/

1
2
3
4
5
6

#自定义端口和配置文件目录启动
sh %SHARDINGSPHERE_PROXY_HOME%/bin/start.sh ${proxy_port} ${proxy_conf_directory}

#使用 -f 参数强制启动 Proxy，该参数会忽略启动期间异常的数据源，
#强行启动 Proxy，用户可以在 Proxy 启动完成后，通过 DistSQL 移除异常数据源。
sh %SHARDINGSPHERE_PROXY_HOME%/bin/start.sh -f

5.客户端连接ShardingSphere-Proxy

使用 MySQL 客户端连接 ShardingSphere-Proxy：

1

mysql -h${proxy_host} -P${proxy_port} -u${proxy_username} -p${proxy_password}

MySQL 客户端连接，默认是–skip-comments 过滤注释，要使用SQL Hint 功能，需要添加-c 选项保留注释，或–comments，例如：

1

mysql -h10.10.0.101 -P3307 -uroot -p --comments

使用 PostgreSQL 客户端连接 ShardingSphere-Proxy：

1

psql -h ${proxy_host} -p ${proxy_port} -U ${proxy_username}

使用 openGauss 客户端连接 ShardingSphere-Proxy：

1

gsql -r -h ${proxy_host} -p ${proxy_port} -U ${proxy_username} -W ${proxy_password}

6.ShardingSphere-Proxy的配置 – server.yaml

进入到ShardingSphere-Proxy的配置目录：

1
2

cd /usr/local/shardingsphere-proxy-5.3.1/conf
vi server.yaml

server.yaml查看示例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63

#mode:
#  type: Cluster
#  repository:
#    type: ZooKeeper
#    props:
#      namespace: governance_ds
#      server-lists: localhost:2181
#      retryIntervalMilliseconds: 500
#      timeToLiveSeconds: 60
#      maxRetries: 3
#      operationTimeoutMilliseconds: 500
#
authority:
  users:
    - user: root@%
      password: 12345678
    - user: sharding
      password: 12345678
  privilege:
    type: ALL_PERMITTED

transaction:
  defaultType: XA
  providerType: Atomikos

sqlParser:
  sqlCommentParseEnabled: false
  sqlStatementCache:
    initialCapacity: 2000
    maximumSize: 65535
  parseTreeCache:
    initialCapacity: 128
    maximumSize: 1024

cdc:
  enabled: false
  port: 33071

# 参考文档
# https://shardingsphere.apache.org/document/current/cn/user-manual/common-config/props/
# https://shardingsphere.apache.org/document/current/cn/user-manual/shardingsphere-proxy/yaml-config/props/  --  主要是这个
props:
  max-connections-size-per-query: 1
  kernel-executor-size: 16  # Infinite by default.
  proxy-frontend-flush-threshold: 128  # The default value is 128.

#是否允许在 ShardingSphere-Proxy 中使用 Hint。使用 Hint 会将 Proxy 的线程处理模型由 IO 多路复用变更为每个请求一个独立的线程，会降低 Proxy 的吞吐量。
  proxy-hint-enabled: false
  sql-show: true
  check-table-metadata-enabled: false
    # Proxy backend query fetch size. A larger value may increase the memory usage of ShardingSphere Proxy.
    # The default value is -1, which means set the minimum value for different JDBC drivers.
  proxy-backend-query-fetch-size: -1
  proxy-frontend-executor-size: 0 # Proxy frontend executor size. The default value is 0, which means let Netty decide.
    # Available options of proxy backend executor suitable: OLAP(default), OLTP. The OLTP option may reduce time cost of writing packets to client, but it may increase the latency of SQL execution
    # and block other clients if client connections are more than `proxy-frontend-executor-size`, especially executing slow SQL.
  proxy-backend-executor-suitable: OLAP
  proxy-frontend-max-connections: 0 # Less than or equal to 0 means no limitation.
    # Available sql federation type: NONE (default), ORIGINAL, ADVANCED
  sql-federation-type: NONE
  proxy-mysql-default-version: 5.7.22 # In the absence of schema name, the default version will be used.
  proxy-default-port: 3307 # Proxy default port.
  proxy-netty-backlog: 1024 # Proxy netty backlog.

语法说明

!! 表示实例化该类

! 表示自定义别名

  • 表示可以包含一个或多个

[] 表示数组，可以与减号相互替换使用

6.1 ShardingSphere-Proxy的权限配置

格式：

1
2
3
4
5
6

authority:
  users:
    - user: # 用于登录计算节点的用户名和授权主机的组合，格式：<username>@<hostname>，hostname 为 % 或空字符串表示不限制授权主机
      password: # 用户密码
  privilege:
    type: # 权限提供者类型，缺省值为 ALL_PERMITTED

Proxy 提供了两种级别的权限提供者，分别是：

  • ALL_PERMITTED：授予所有权限，不鉴权；

  • DATABASE_PERMITTED：为用户授予指定逻辑库的权限，通过 user-database-mappings 进行映射。

ALL_PERMITTED示例：

1
2
3
4
5
6
7
8

authority:
  users:
    - user: root@localhost
      password: root
    - user: my_user
      password: pwd
  privilege:
    type: ALL_PERMITTED

DATABASE_PERMITTED示例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

authority:
  users:
    - user: root@localhost
      password: root
    - user: my_user
      password: pwd
  privilege:
    type: DATABASE_PERMITTED
    props:
      user-database-mappings: root@localhost=sharding_db, root@localhost=test_db, my_user@=sharding_db

6.2 server.yaml的规则配置说明

SQL 解析

1
2
3
4
5
6
7
8

sqlParser:
  sqlCommentParseEnabled: true
  sqlStatementCache:
    initialCapacity: 2000
    maximumSize: 65535
  parseTreeCache:
    initialCapacity: 128
    maximumSize: 1024

分布式事务

1
2
3

transaction:
  defaultType: XA
  providerType: Atomikos

SQL 翻译

1
2
3

sqlTranslator:
  type:
  useOriginalSQLWhenTranslatingFailed:

6.3 server.yaml的属性参数说明

名称 数据类型 说明 默认值 动态生效
sql-show (?) boolean 是否在日志中打印 SQL。
打印 SQL 可以帮助开发者快速定位系统问题。日志内容包含：逻辑 SQL，真实 SQL 和 SQL 解析结果。
如果开启配置，日志将使用 Topic ShardingSphere-SQL，日志级别是 INFO。 false 是
sql-simple (?) boolean 是否在日志中打印简单风格的 SQL。 false 是
kernel-executor-size (?) int 用于设置任务处理线程池的大小。每个 ShardingSphereDataSource 使用一个独立的线程池，同一个 JVM 的不同数据源不共享线程池。 infinite 否
max-connections-size-per-query (?) int 一次查询请求在每个数据库实例中所能使用的最大连接数。 1 是
check-table-metadata-enabled (?) boolean 在程序启动和更新时，是否检查分片元数据的结构一致性。 false 是
proxy-frontend-flush-threshold (?) int 在 ShardingSphere-Proxy 中设置传输数据条数的 IO 刷新阈值。 128 是
proxy-hint-enabled (?) boolean 是否允许在 ShardingSphere-Proxy 中使用 Hint。使用 Hint 会将 Proxy 的线程处理模型由 IO 多路复用变更为每个请求一个独立的线程，会降低 Proxy 的吞吐量。 false 是
proxy-backend-query-fetch-size (?) int Proxy 后端与数据库交互的每次获取数据行数（使用游标的情况下）。数值增大可能会增加 ShardingSphere Proxy 的内存使用。默认值为 -1，代表设置为 JDBC 驱动的最小值。 -1 是
proxy-frontend-executor-size (?) int Proxy 前端 Netty 线程池线程数量，默认值 0 代表使用 Netty 默认值。 0 否
proxy-backend-executor-suitable (?) String 可选选项：OLAP、OLTP。OLTP 选项可能会减少向客户端写入数据包的时间开销，但如果客户端连接数超过 proxy-frontend-executor-size，尤其是执行慢 SQL 时，它可能会增加 SQL 执行的延迟甚至阻塞其他客户端的连接。 OLAP 是
proxy-frontend-max-connections (?) int 允许连接 Proxy 的最大客户端数量，默认值 0 代表不限制。 0 是
sql-federation-type (?) String 联邦查询执行器类型，包括：NONE，ORIGINAL，ADVANCED。 NONE 是
proxy-mysql-default-version (?) String Proxy 通过配置文件指定 MySQL 的版本号,默认版本：5.7.22。 5.7.22 否
proxy-default-port (?) String Proxy 通过配置文件指定默认端口。 3307 否
proxy-netty-backlog (?) int Proxy 通过配置文件指定默认netty back_log参数。 1024 否
proxy-frontend-database-protocol-type String Proxy 前端协议类型，支持 MySQL, PostgreSQL, openGauss “” 否

属性配置可以通过 DistSQL#RAL 修改。 支持动态修改的属性可以立即生效，不支持动态修改的属性需要重启后生效。