- ShardingSphere-Proxy配置
配置是 ShardingSphere-Proxy 中唯一与应用开发者交互的模块,通过它可以快速清晰的理解 ShardingSphere-Proxy 所提供的功能。
ShardingSphere-Proxy 提供基于 YAML 的配置方式,并使用 DistSQL 进行交互。 通过配置,应用开发者可以灵活的使用数据分片、读写分离、数据加密、影子库等功能,并且能够叠加使用。
规则配置部分与 ShardingSphere-JDBC 的 YAML 配置完全一致。 DistSQL 与 YAML 配置能够相互取代。
- YAML 配置
配置文件路径:$shardingsphere-proxy/conf/server.yaml, 其中:$shardingsphere-proxy为shardingsphere-proxy解压目录,例如:/root/apache-shardingsphere-5.3.2-shardingsphere-proxy-bin
- 模式参数
mode (?): # 不配置则默认单机模式
type: # 运行模式类型。可选配置:Standalone、Cluster
repository (?): # 久化仓库配置
- 单机模式
mode:
type: Standalone
repository:
type: # 持久化仓库类型
props: # 持久化仓库所需属性
foo_key: foo_value
bar_key: bar_value
配置示例:
mode:
type: Standalone
repository:
type: JDBC
- 集群模式
mode:
type: Cluster
repository:
type: # 持久化仓库类型
props: # 持久化仓库所需属性
namespace: # 注册中心命名空间
server-lists: # 注册中心连接地址
foo_key: foo_value
bar_key: bar_value
集群模式示例
mode:
type: Cluster
repository:
type: ZooKeeper
props:
namespace: governance
server-lists: localhost:2181
retryIntervalMilliseconds: 500
timeToLiveSeconds: 60
注意事项
- 生产环境建议使用集群模式部署。
- 集群模式部署推荐使用 ZooKeeper 注册中心。
- ZooKeeper 存在配置信息时,则以 ZooKeeper 中的配置为准。
- 数据源参数
ShardingSphere-Proxy作为数据库代理,配置数据源的参数在$shardingsphere-proxy/conf/*.yaml中,格式如下:
dataSources: # 数据源配置,可配置多个 <data-source-name>
<data_source_name>: # 数据源名称
dataSourceClassName: # 数据源完整类名
driverClassName: # 数据库驱动类名,以数据库连接池自身配置为准
jdbcUrl: # 数据库 URL 连接,以数据库连接池自身配置为准
username: # 数据库用户名,以数据库连接池自身配置为准
password: # 数据库密码,以数据库连接池自身配置为准
# ... 数据库连接池的其它属性
以config-sharding.yaml配置示例
dataSources:
ds_1:
dataSourceClassName: com.zaxxer.hikari.HikariDataSource
driverClassName: com.mysql.jdbc.Driver
jdbcUrl: jdbc:mysql://localhost:3306/ds_1
username: root
password:
ds_2:
dataSourceClassName: com.zaxxer.hikari.HikariDataSource
driverClassName: com.mysql.jdbc.Driver
jdbcUrl: jdbc:mysql://localhost:3306/ds_2
username: root
password:
# 配置其他数据源
配置示例
databaseName: sharding_db
dataSources:
ds_0:
url: jdbc:postgresql://127.0.0.1:54321/demo_ds_0
username: postgres
password: postgres
connectionTimeoutMilliseconds: 30000
idleTimeoutMilliseconds: 60000
maxLifetimeMilliseconds: 1800000
maxPoolSize: 50
minPoolSize: 1
ds_1:
url: jdbc:postgresql://127.0.0.1:54321/demo_ds_1
username: postgres
password: postgres
connectionTimeoutMilliseconds: 30000
idleTimeoutMilliseconds: 60000
maxLifetimeMilliseconds: 1800000
maxPoolSize: 50
minPoolSize: 1
rules:
- !SHARDING
tables:
t_order:
actualDataNodes: ds_${0..1}.t_order_${0..1}
tableStrategy:
standard:
shardingColumn: order_id
shardingAlgorithmName: t_order_inline
keyGenerateStrategy:
column: order_id
keyGeneratorName: snowflake
t_order_item:
actualDataNodes: ds_${0..1}.t_order_item_${0..1}
tableStrategy:
standard:
shardingColumn: order_id
shardingAlgorithmName: t_order_item_inline
keyGenerateStrategy:
column: order_item_id
keyGeneratorName: snowflake
bindingTables:
- t_order,t_order_item
broadcastTables:
- t_address
defaultDatabaseStrategy:
standard:
shardingColumn: user_id
shardingAlgorithmName: database_inline
defaultTableStrategy:
none:
shardingAlgorithms:
database_inline:
type: INLINE
props:
algorithm-expression: ds_${user_id % 2}
allow-range-query-with-inline-sharding: true
t_order_inline:
type: INLINE
props:
algorithm-expression: t_order_${order_id % 2}
t_order_item_inline:
type: INLINE
props:
algorithm-expression: t_order_item_${order_id % 2}
keyGenerators:
snowflake:
type: SNOWFLAKE
- 规则参数
ShardingSphere-Proxy 的规则配置与ShardingSphere-JDBC一致,具体规则请参考下面ShardingSphere-JDBC 规则配置。
- 数据分片
rules:
- !SHARDING
tables: # 数据分片规则配置
<logic_table_name> (+): # 逻辑表名称
actualDataNodes (?): # 由数据源名 + 表名组成(参考 Inline 语法规则)
databaseStrategy (?): # 分库策略,缺省表示使用默认分库策略,以下的分片策略只能选其一
standard: # 用于单分片键的标准分片场景
shardingColumn: # 分片列名称
shardingAlgorithmName: # 分片算法名称
complex: # 用于多分片键的复合分片场景
shardingColumns: # 分片列名称,多个列以逗号分隔
shardingAlgorithmName: # 分片算法名称
hint: # Hint 分片策略
shardingAlgorithmName: # 分片算法名称
none: # 不分片
tableStrategy: # 分表策略,同分库策略
keyGenerateStrategy: # 分布式序列策略
column: # 自增列名称,缺省表示不使用自增主键生成器
keyGeneratorName: # 分布式序列算法名称
auditStrategy: # 分片审计策略
auditorNames: # 分片审计算法名称
- <auditor_name>
- <auditor_name>
allowHintDisable: true # 是否禁用分片审计hint
autoTables: # 自动分片表规则配置
t_order_auto: # 逻辑表名称
actualDataSources (?): # 数据源名称
shardingStrategy: # 切分策略
standard: # 用于单分片键的标准分片场景
shardingColumn: # 分片列名称
shardingAlgorithmName: # 自动分片算法名称
bindingTables (+): # 绑定表规则列表
- <logic_table_name_1, logic_table_name_2, ...>
- <logic_table_name_1, logic_table_name_2, ...>
broadcastTables (+): # 广播表规则列表
- <table_name>
- <table_name>
defaultDatabaseStrategy: # 默认数据库分片策略
defaultTableStrategy: # 默认表分片策略
defaultKeyGenerateStrategy: # 默认的分布式序列策略
defaultShardingColumn: # 默认分片列名称
# 分片算法配置
shardingAlgorithms:
<sharding_algorithm_name> (+): # 分片算法名称
type: # 分片算法类型
props: # 分片算法属性配置
# ...
# 分布式序列算法配置
keyGenerators:
<key_generate_algorithm_name> (+): # 分布式序列算法名称
type: # 分布式序列算法类型
props: # 分布式序列算法属性配置
# ...
# 分片审计算法配置
auditors:
<sharding_audit_algorithm_name> (+): # 分片审计算法名称
type: # 分片审计算法类型
props: # 分片审计算法属性配置
# ...
- 分布式事务
ShardingSphere 提供了三种模式的分布式事务 LOCAL, XA, BASE
参数解释
rules:
- !TRANSACTION
defaultType: # 事务模式,可选值 LOCAL/XA/BASE
providerType: # 指定模式下的具体实现
- SQL 解析
参数解释
rules:
- !SQL_PARSER
sqlCommentParseEnabled: # 是否解析 SQL 注释
sqlStatementCache: # SQL 语句本地缓存配置项
initialCapacity: # 本地缓存初始容量
maximumSize: # 本地缓存最大容量
parseTreeCache: # 解析树本地缓存配置项
initialCapacity: # 本地缓存初始容量
maximumSize: # 本地缓存最大容量
配置示例
rules:
- !SQL_PARSER
sqlCommentParseEnabled: true
sqlStatementCache:
initialCapacity: 2000
maximumSize: 65535
parseTreeCache:
initialCapacity: 128
maximumSize: 1024
- SQL 翻译
rules:
- !SQL_TRANSLATOR
type: # SQL 翻译器类型
useOriginalSQLWhenTranslatingFailed: # SQL 翻译失败是否使用原始 SQL 继续执行
注意事项
与ShardingSphere-JDBC 不同的是,以下规则需要配置在 ShardingSphere-Proxy 的server.yaml 中:
- SQL 解析
sqlParser:
sqlCommentParseEnabled:
true
sqlStatementCache:
initialCapacity:
2000
maximumSize:
65535
parseTreeCache:
initialCapacity:
128
maximumSize:
1024
- 分布式事务
transaction:
defaultType:
XA
providerType:
Atomikos
- SQL 翻译
sqlTranslator:
type:
useOriginalSQLWhenTranslatingFailed:
- JDBC驱动
- Spring Boot
使用步骤:
- 引入maven依赖
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>io.shardingsphere</groupId>
<artifactId>sharding-proxy-example</artifactId>
<version>3.1.0</version>
</parent>
<artifactId>sharding-proxy-boot-mybatis-example</artifactId>
<dependencies>
<dependency>
<groupId>io.shardingsphere</groupId>
<artifactId>mybatis-repository</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>org.mybatis</groupId>
<artifactId>mybatis</artifactId>
</dependency>
<dependency>
<groupId>org.mybatis</groupId>
<artifactId>mybatis-spring</artifactId>
</dependency>
<dependency>
<groupId>org.mybatis.spring.boot</groupId>
<artifactId>mybatis-spring-boot-starter</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-aop</artifactId>
</dependency>
</dependencies>
</project>
- 在application.properties文件中配置spring-boot
mybatis.config-location=classpath:META-INF/mybatis-config.xml
spring.datasource.type=org.apache.commons.dbcp.BasicDataSource
spring.datasource.driver-class-name=org.postgresql.Driver
spring.datasource.url=jdbc:postgresql://192.168.85.155:3307/sharding_db?useServerPrepStmts=true&cachePrepStmts=true
spring.datasource.username=postgres
spring.datasource.password=postgres
- 使用数据源
直接使用该数据源;或者将 ShardingSphereDataSource 配置在 JPA、Hibernate、MyBatis 等 ORM 框架中配合使用。
- 认证和授权
在 ShardingSphere-Proxy 中,通过 authority 来配置用户的认证和授权信息。
得益于 ShardingSphere 的可插拔架构,Proxy 提供了两种级别的权限提供者,分别是:
- ALL_PERMITTED:每个用户都拥有所有权限,无需专门授权;
- DATABASE_PERMITTED:为用户授予指定逻辑库的权限,通过 user-database-mappings 进行定义。
在配置 authority 时,管理员可根据需要选择使用哪一种权限提供者。
参数解释
authority:
users:
- user: # 用于登录计算节点的用户名和授权主机的组合,格式:<username>@<hostname>,hostname 为 % 或空字符串表示不限制授权主机
password: # 用户密码
authenticationMethodName: # 可选项,用于为用户指定密码认证方式
authenticators: # 可选项,默认不需要配置,Proxy 根据前端协议类型自动选择
authenticatorName:
type: # 密码认证类型
defaultAuthenticator: # 可选项,指定一个 authenticatorName 作为默认的密码认证方式
privilege:
type: # 权限提供者类型,缺省值为 ALL_PERMITTED
配置示例:
authority:
users:
- user: root@%
password: root
- user: sharding
password: sharding
说明:
- 定义了两个用户:root@% 和 sharding;
- 未定义 authenticators 和 authenticationMethodName,Proxy 将根据前端协议自动选择;
- 未指定 privilege type,采用默认的 ALL_PERMITTED。
认证配置
自定义认证配置能够满足用户在一些特定场景下的需求。 以 openGauss 作为前端协议类型为例,其默认的认证算法为 scram-sha-256。 如果用户 sharding 需要用旧版本的 psql 客户端(不支持 scram-sha-256)连接 Proxy,则管理员可能允许 sharding 使用 md5 方式进行密码认证。 配置方式如下:
authority:
users:
- user: root@127.0.0.1
password: root
- user: sharding
password: sharding
authenticationMethodName: md5
authenticators:
md5:
type: MD5
privilege:
type: ALL_PERMITTED
说明:
- 定义了两个用户:root@127.0.0.1 和 sharding;
- 为用户 sharding 指定了 MD5 方式进行密码认证;
- 没有为 root@127.0.0.1 指定认证方式,Proxy 将根据前端协议自动选择;
- 指定权限提供者为 ALL_PERMITTED。
授权配置:
ALL_PERMITTED
authority:
users:
- user: root@127.0.0.1
password: root
- user: sharding
password: sharding
privilege:
type: ALL_PERMITTED
说明:
- 定义了两个用户:root@127.0.0.1 和 sharding;
- 未定义 authenticators 和 authenticationMethodName,Proxy 将根据前端协议自动选择;
- 指定权限提供者为 ALL_PERMITTED。
DATABASE_PERMITTED
authority:
users:
- user: root@127.0.0.1
password: root
- user: sharding
password: sharding
privilege:
type: DATABASE_PERMITTED
props:
user-database-mappings: root@127.0.0.1=*, sharding@%=test_db, sharding@%=sharding_db
说明:
- 定义了两个用户:root@127.0.0.1 和 sharding;
- 未定义 authenticators 和 authenticationMethodName,Proxy 将根据前端协议自动选择;
- 指定权限提供者为 DATABASE_PERMITTED,并授权 root@127.0.0.1 用户访问所有逻辑库(*),sharding 用户仅能访问 test_db 和 sharding_db。
- 属性配置
在server.yaml文件配置ShardingSphere-Proxy属性,属性值参考:
名称 | 数据类型 | 说明 | 默认值 | 动态生效 |
system-log-level (?) | String | 系统日志输出级别,支持 DEBUG、INFO、WARN 和 ERROR,默认级别是 INFO。 | false | 是 |
sql-show (?) | boolean | 是否在日志中打印 SQL。 | 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-backend-query-fetch-size (?) | int | Proxy 后端与数据库交互的每次获取数据行数(使用游标的情况下)。数值增大可能会增加 ShardingSphere Proxy 的内存使用。默认值为 -1,代表设置为 JDBC 驱动的最小值。 | -1 | 是 |
proxy-frontend-executor-size (?) | int | Proxy 前端 Netty 线程池线程数量,默认值 0 代表使用 Netty 默认值。 | 0 | 否 |
proxy-frontend-max-connections (?) | int | 允许连接 Proxy 的最大客户端数量,默认值 0 代表不限制。 | 0 | 是 |
sql-federation-type (?) | String | 联邦查询执行器类型,包括:NONE,ORIGINAL,ADVANCED。 | NONE | 是 |
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 | "" | 否 |
proxy-frontend-ssl-enabled (?) | boolean | Proxy 前端启用 SSL/TLS。 | false | 否 |
proxy-frontend-ssl-version (?) | String | 要启用的 SSL/TLS 协议。空白以使用默认值。 | TLSv1.2,TLSv1.3 | 否 |
proxy-frontend-ssl-cipher (?) | String | 按偏好顺序启用的密码套件。用逗号分隔的多密码套件。空白以使用默认值。 | "" | 否 |
- 完整配置文件参考
#
# Licensed to the Apache Software Foundation (ASF) under one or more
# contributor license agreements. See the NOTICE file distributed with
# this work for additional information regarding copyright ownership.
# The ASF licenses this file to You under the Apache License, Version 2.0
# (the "License"); you may not use this file except in compliance with
# the License. You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
######################################################################################################
#
# If you want to configure governance, authorization and proxy properties, please refer to this file.
#
######################################################################################################
#mode:
# type: Cluster
# repository:
# type: ZooKeeper
# props:
# namespace: governance_ds
# server-lists: localhost:2181
# retryIntervalMilliseconds: 500
# timeToLiveSeconds: 60
# maxRetries: 3
# operationTimeoutMilliseconds: 500
# overwrite: false
#
#rules:
# - !AUTHORITY
# users:
# - root@%:root
# - sharding@:sharding
# provider:
# type: ALL_PERMITTED
# - !TRANSACTION
# defaultType: XA
# providerType: Atomikos
# # When the provider type is Narayana, the following properties can be configured or not
# props:
# recoveryStoreUrl: jdbc:mysql://127.0.0.1:3306/jbossts
# recoveryStoreDataSource: com.mysql.jdbc.jdbc2.optional.MysqlDataSource
# recoveryStoreUser: root
# recoveryStorePassword: 12345678
# commitOnePhase: true
# transactionSync: false
# recoveryBackoffPeriod: 1
# defaultTimeout: 180
# expiryScanInterval: 12
# periodicRecoveryPeriod: 120
# createTable: true
# stateStoreCreateTable: true
# communicationStoreCreateTable: true
# - !SQL_PARSER
# sqlCommentParseEnabled: true
# sqlStatementCache:
# initialCapacity: 2000
# maximumSize: 65535
# parseTreeCache:
# initialCapacity: 128
# maximumSize: 1024
#props:
# max-connections-size-per-query: 1
# kernel-executor-size: 16 # Infinite by default.
# proxy-frontend-flush-threshold: 128 # The default value is 128.
# proxy-hint-enabled: false
# sql-show: false
# check-table-metadata-enabled: false
# show-process-list-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
# check-duplicate-table-enabled: false
# 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.
# sql-federation-enabled: false
# # Available proxy backend driver type: JDBC (default), ExperimentalVertx
# proxy-backend-driver-type: JDBC
# 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.