You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@shardingsphere.apache.org by pa...@apache.org on 2021/03/17 02:59:23 UTC
[shardingsphere] branch master updated: Add JAVA-API each versions
of the document (#9660)
This is an automated email from the ASF dual-hosted git repository.
panjuan pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/shardingsphere.git
The following commit(s) were added to refs/heads/master by this push:
new d19da7b Add JAVA-API each versions of the document (#9660)
d19da7b is described below
commit d19da7bb57a8860f17d5536bf58b11358e0e10b3
Author: xiaoshen11 <34...@qq.com>
AuthorDate: Wed Mar 17 10:58:49 2021 +0800
Add JAVA-API each versions of the document (#9660)
* Add JAVA-API each versions of the document
* remove blank line and transfer chinese comment to english
---
.../configuration/java-api/change-history.cn.md | 200 ++++++++++++++++++++-
.../configuration/java-api/change-history.en.md | 192 +++++++++++++++++++-
2 files changed, 390 insertions(+), 2 deletions(-)
diff --git a/docs/document/content/user-manual/shardingsphere-jdbc/configuration/java-api/change-history.cn.md b/docs/document/content/user-manual/shardingsphere-jdbc/configuration/java-api/change-history.cn.md
index a1a2e03b3..36cdcd2 100644
--- a/docs/document/content/user-manual/shardingsphere-jdbc/configuration/java-api/change-history.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-jdbc/configuration/java-api/change-history.cn.md
@@ -31,4 +31,202 @@ weight = 7
| replicaDataSourceNames (+) | Collection\<String\> | 从库数据源名称列表 | - |
| loadBalancerName (?) | String | 从库负载均衡算法名称 | 轮询负载均衡算法 |
-算法类型的详情，请参见[内置负载均衡算法列表](/cn/user-manual/shardingsphere-jdbc/configuration/built-in-algorithm/load-balance)。
+算法类型的详情，请参见[内置负载均衡算法列表](/docs/document/content/user-manual/shardingsphere-jdbc/configuration/built-in-algorithm/load-balance.cn.md)。
+
+## ShardingSphere-4.x
+
+### 读写分离
+
+#### MasterSlaveDataSourceFactory
+
+读写分离的数据源创建工厂。
+
+| *名称* | *数据类型* | *说明* |
+| :-------------------- | :--------------------------- | :------------------- |
+| dataSourceMap | Map<String, DataSource> | 数据源与其名称的映射 |
+| masterSlaveRuleConfig | MasterSlaveRuleConfiguration | 读写分离规则 |
+| props (?) | Properties | 属性配置 |
+
+#### MasterSlaveRuleConfiguration
+
+读写分离规则配置对象。
+
+| *名称* | *数据类型* | *说明* |
+| :----------------------- | :------------------------------ | :----------------- |
+| name | String | 读写分离数据源名称 |
+| masterDataSourceName | String | 主库数据源名称 |
+| slaveDataSourceNames | Collection<String> | 从库数据源名称列表 |
+| loadBalanceAlgorithm (?) | MasterSlaveLoadBalanceAlgorithm | 从库负载均衡算法 |
+
+#### Properties
+
+属性配置项，可以为以下属性。
+
+| *名称* | *数据类型* | *说明* |
+| :--------------------------------- | :--------- | :----------------------------------------------------- |
+| sql.show (?) | boolean | 是否打印SQL解析和改写日志，默认值: false |
+| executor.size (?) | int | 用于SQL执行的工作线程数量，为零则表示无限制。默认值: 0 |
+| max.connections.size.per.query (?) | int | 每个物理数据库为每次查询分配的最大连接数量。默认值: 1 |
+| check.table.metadata.enabled (?) | boolean | 是否在启动时检查分表元数据一致性，默认值: false |
+
+## ShardingSphere-3.x
+
+### 读写分离
+
+#### MasterSlaveDataSourceFactory
+
+读写分离的数据源创建工厂。
+
+| *名称* | *数据类型* | *说明* |
+| :-------------------- | :--------------------------- | :------------------- |
+| dataSourceMap | Map<String, DataSource> | 数据源与其名称的映射 |
+| masterSlaveRuleConfig | MasterSlaveRuleConfiguration | 读写分离规则 |
+| configMap (?) | Map<String, Object> | 用户自定义配置 |
+| props (?) | Properties | 属性配置 |
+
+#### MasterSlaveRuleConfiguration
+
+读写分离规则配置对象。
+
+| *名称* | *数据类型* | *说明* |
+| :----------------------- | :------------------------------ | :----------------- |
+| name | String | 读写分离数据源名称 |
+| masterDataSourceName | String | 主库数据源名称 |
+| slaveDataSourceNames | Collection<String> | 从库数据源名称列表 |
+| loadBalanceAlgorithm (?) | MasterSlaveLoadBalanceAlgorithm | 从库负载均衡算法 |
+
+#### configMap
+
+用户自定义配置。
+
+#### PropertiesConstant
+
+属性配置项，可以为以下属性。
+
+| *名称* | *数据类型* | *说明* |
+| :--------------------------------- | :--------- | :----------------------------------------------------- |
+| sql.show (?) | boolean | 是否打印SQL解析和改写日志，默认值: false |
+| executor.size (?) | int | 用于SQL执行的工作线程数量，为零则表示无限制。默认值: 0 |
+| max.connections.size.per.query (?) | int | 每个物理数据库为每次查询分配的最大连接数量。默认值: 1 |
+| check.table.metadata.enabled (?) | boolean | 是否在启动时检查分表元数据一致性，默认值: false |
+
+## ShardingSphere-2.x
+
+### 读写分离
+
+#### 概念
+
+为了缓解数据库压力，将写入和读取操作分离为不同数据源，写库称为主库，读库称为从库，一主库可配置多从库。
+
+#### 支持项
+
+1. 提供了一主多从的读写分离配置，可独立使用，也可配合分库分表使用。
+2. 独立使用读写分离支持SQL透传。
+3. 同一线程且同一数据库连接内，如有写入操作，以后的读操作均从主库读取，用于保证数据一致性。
+4. Spring命名空间。
+5. 基于Hint的强制主库路由。
+
+#### 不支持范围
+
+1. 主库和从库的数据同步。
+2. 主库和从库的数据同步延迟导致的数据不一致。
+3. 主库双写或多写。
+
+#### 代码开发示例
+
+##### 仅读写分离
+
+```java
+// 构建读写分离数据源, 读写分离数据源实现了DataSource接口, 可直接当做数据源处理. masterDataSource, slaveDataSource0, slaveDataSource1等为使用DBCP等连接池配置的真实数据源
+Map<String, DataSource> dataSourceMap = new HashMap<>();
+dataSourceMap.put("masterDataSource", masterDataSource);
+dataSourceMap.put("slaveDataSource0", slaveDataSource0);
+dataSourceMap.put("slaveDataSource1", slaveDataSource1);
+
+// 构建读写分离配置
+MasterSlaveRuleConfiguration masterSlaveRuleConfig = new MasterSlaveRuleConfiguration();
+masterSlaveRuleConfig.setName("ms_ds");
+masterSlaveRuleConfig.setMasterDataSourceName("masterDataSource");
+masterSlaveRuleConfig.getSlaveDataSourceNames().add("slaveDataSource0");
+masterSlaveRuleConfig.getSlaveDataSourceNames().add("slaveDataSource1");
+
+DataSource dataSource = MasterSlaveDataSourceFactory.createDataSource(dataSourceMap, masterSlaveRuleConfig);
+```
+
+##### 分库分表 + 读写分离
+
+```java
+// 构建读写分离数据源, 读写分离数据源实现了DataSource接口, 可直接当做数据源处理. masterDataSource0, slaveDataSource00, slaveDataSource01等为使用DBCP等连接池配置的真实数据源
+Map<String, DataSource> dataSourceMap = new HashMap<>();
+dataSourceMap.put("masterDataSource0", masterDataSource0);
+dataSourceMap.put("slaveDataSource00", slaveDataSource00);
+dataSourceMap.put("slaveDataSource01", slaveDataSource01);
+
+dataSourceMap.put("masterDataSource1", masterDataSource1);
+dataSourceMap.put("slaveDataSource10", slaveDataSource10);
+dataSourceMap.put("slaveDataSource11", slaveDataSource11);
+
+// 构建读写分离配置
+MasterSlaveRuleConfiguration masterSlaveRuleConfig0 = new MasterSlaveRuleConfiguration();
+masterSlaveRuleConfig0.setName("ds_0");
+masterSlaveRuleConfig0.setMasterDataSourceName("masterDataSource0");
+masterSlaveRuleConfig0.getSlaveDataSourceNames().add("slaveDataSource00");
+masterSlaveRuleConfig0.getSlaveDataSourceNames().add("slaveDataSource01");
+
+MasterSlaveRuleConfiguration masterSlaveRuleConfig1 = new MasterSlaveRuleConfiguration();
+masterSlaveRuleConfig1.setName("ds_1");
+masterSlaveRuleConfig1.setMasterDataSourceName("masterDataSource1");
+masterSlaveRuleConfig1.getSlaveDataSourceNames().add("slaveDataSource10");
+masterSlaveRuleConfig1.getSlaveDataSourceNames().add("slaveDataSource11");
+
+// 通过ShardingSlaveDataSourceFactory继续创建ShardingDataSource
+ShardingRuleConfiguration shardingRuleConfig = new ShardingRuleConfiguration();
+shardingRuleConfig.getMasterSlaveRuleConfigs().add(masterSlaveRuleConfig0);
+shardingRuleConfig.getMasterSlaveRuleConfigs().add(masterSlaveRuleConfig1);
+
+DataSource dataSource = ShardingDataSourceFactory.createDataSource(dataSourceMap, shardingRuleConfig);
+```
+
+## ShardingSphere-1.x
+
+### 读写分离
+
+#### 概念
+
+为了缓解数据库压力，将写入和读取操作分离为不同数据源，写库称为主库，读库称为从库，一主库可配置多从库。
+
+#### 支持项
+
+1. 提供了一主多从的读写分离配置，可独立使用，也可配合分库分表使用。
+2. 同一线程且同一数据库连接内，如有写入操作，以后的读操作均从主库读取，用于保证数据一致性。
+3. Spring命名空间。
+4. 基于Hint的强制主库路由。
+
+#### 不支持范围
+
+1. 主库和从库的数据同步。
+2. 主库和从库的数据同步延迟导致的数据不一致。
+3. 主库双写或多写。
+
+#### 代码开发示例
+
+```java
+// 构建读写分离数据源, 读写分离数据源实现了DataSource接口, 可直接当做数据源处理. masterDataSource0, slaveDataSource00, slaveDataSource01等为使用DBCP等连接池配置的真实数据源
+Map<String, DataSource> slaveDataSourceMap0 = new HashMap<>();
+slaveDataSourceMap0.put("slaveDataSource00", slaveDataSource00);
+slaveDataSourceMap0.put("slaveDataSource01", slaveDataSource01);
+// 可选择主从库负载均衡策略, 默认是ROUND_ROBIN, 还有RANDOM可以选择, 或者自定义负载策略
+DataSource masterSlaveDs0 = MasterSlaveDataSourceFactory.createDataSource("ms_0", "masterDataSource0", masterDataSource0, slaveDataSourceMap0, MasterSlaveLoadBalanceStrategyType.ROUND_ROBIN);
+
+Map<String, DataSource> slaveDataSourceMap1 = new HashMap<>();
+slaveDataSourceMap1.put("slaveDataSource10", slaveDataSource10);
+slaveDataSourceMap1.put("slaveDataSource11", slaveDataSource11);
+DataSource masterSlaveDs1 = MasterSlaveDataSourceFactory.createDataSource("ms_1", "masterDataSource1", masterDataSource1, slaveDataSourceMap1, MasterSlaveLoadBalanceStrategyType.ROUND_ROBIN);
+
+// 构建分库分表数据源
+Map<String, DataSource> dataSourceMap = new HashMap<>();
+dataSourceMap.put("ms_0", masterSlaveDs0);
+dataSourceMap.put("ms_1", masterSlaveDs1);
+
+// 通过ShardingDataSourceFactory继续创建ShardingDataSource
+```
\ No newline at end of file
diff --git a/docs/document/content/user-manual/shardingsphere-jdbc/configuration/java-api/change-history.en.md b/docs/document/content/user-manual/shardingsphere-jdbc/configuration/java-api/change-history.en.md
index f48181b..7b8902e 100644
--- a/docs/document/content/user-manual/shardingsphere-jdbc/configuration/java-api/change-history.en.md
+++ b/docs/document/content/user-manual/shardingsphere-jdbc/configuration/java-api/change-history.en.md
@@ -31,4 +31,194 @@ Attributes:
| replicaDataSourceNames (+) | Collection\<String\> | Replica sources source name list | - |
| loadBalancerName (?) | String | Load balance algorithm name of replica sources | Round robin load balance algorithm |
-Please refer to [Built-in Load Balance Algorithm List](/en/user-manual/shardingsphere-jdbc/configuration/built-in-algorithm/load-balance) for more details about type of algorithm.
+Please refer to [Built-in Load Balance Algorithm List](/docs/document/content/user-manual/shardingsphere-jdbc/configuration/built-in-algorithm/load-balance.en.md) for more details about type of algorithm.
+
+## ShardingSphere-4.x
+
+### Read-Write Split
+
+#### MasterSlaveDataSourceFactory
+
+| *Name* | *DataType* | *Explanation* |
+| :-------------------- | :--------------------------- | :---------------------------------- |
+| dataSourceMap | Map<String, DataSource> | Mapping of data source and its name |
+| masterSlaveRuleConfig | MasterSlaveRuleConfiguration | Master slave rule configuration |
+| props (?) | Properties | Property configurations |
+
+#### MasterSlaveRuleConfiguration
+
+| *Name* | *DataType* | *Explanation* |
+| :----------------------- | :------------------------------ | :-------------------------------- |
+| name | String | Read-write split data source name |
+| masterDataSourceName | String | Master database source name |
+| slaveDataSourceNames | Collection<String> | Slave database source name list |
+| loadBalanceAlgorithm (?) | MasterSlaveLoadBalanceAlgorithm | Slave database load balance |
+
+#### Properties
+
+Property configuration items, can be of the following properties.
+
+| *Name* | *Data Type* | *Explanation* |
+| :--------------------------------- | :---------- | :----------------------------------------------------------- |
+| sql.show (?) | boolean | Print SQL parse and rewrite log or not, default value: false |
+| executor.size (?) | int | Be used in work thread number implemented by SQL; no limits if it is 0. default value: 0 |
+| max.connections.size.per.query (?) | int | The maximum connection number allocated by each query of each physical database, default value: 1 |
+| check.table.metadata.enabled (?) | boolean | Check meta-data consistency or not in initialization, default value: false |
+
+## ShardingSphere-3.x
+
+### Read-Write Split
+
+#### MasterSlaveDataSourceFactory
+
+| *Name* | *DataType* | *Description* |
+| :-------------------- | :--------------------------- | :---------------------------------- |
+| dataSourceMap | Map<String, DataSource> | Map of data sources and their names |
+| masterSlaveRuleConfig | MasterSlaveRuleConfiguration | Master slave rule configuration |
+| configMap (?) | Map<String, Object> | Config map |
+| props (?) | Properties | Properties |
+
+#### MasterSlaveRuleConfiguration
+
+| *Name* | *DataType* | *Description* |
+| :----------------------- | :------------------------------ | :------------------------------- |
+| name | String | Name of master slave data source |
+| masterDataSourceName | String | Name of master data source |
+| slaveDataSourceNames | Collection<String> | Names of Slave data sources |
+| loadBalanceAlgorithm (?) | MasterSlaveLoadBalanceAlgorithm | Load balance algorithm |
+
+#### configMap
+
+User-defined arguments.
+
+#### PropertiesConstant
+
+Enumeration of properties.
+
+| *Name* | *DataType* | *Description* |
+| :--------------------------------- | :--------- | :----------------------------------------------------------- |
+| sql.show (?) | boolean | To show SQLS or not, default value: false |
+| executor.size (?) | int | The number of working threads, default value: CPU count |
+| max.connections.size.per.query (?) | int | Max connection size for every query to every actual database. default value: 1 |
+| check.table.metadata.enabled (?) | boolean | Check the metadata consistency of all the tables, default value : false |
+
+## ShardingSphere-2.x
+
+### Read-Write Split
+
+#### concept
+
+In order to relieve the pressure on the database, the write and read operations are separated into different data sources. The write library is called the master library, and the read library is called the slave library. One master library can be configured with multiple slave libraries.
+
+#### Support item
+
+1. Provides a read-write separation configuration with one master and multiple slaves, which can be used independently or with sub-databases and sub-meters.
+2. Independent use of read-write separation to support SQL transparent transmission.
+3. In the same thread and the same database connection, if there is a write operation, subsequent read operations will be read from the main library to ensure data consistency.
+4. Spring namespace.
+5. Hint-based mandatory main library routing.
+
+#### Unsupported item
+
+1. Data synchronization between the master library and the slave library.
+2. Data inconsistency caused by the data synchronization delay of the master library and the slave library.
+3. Double writing or multiple writing in the main library.
+
+#### Code development example
+
+##### only read-write split
+
+```java
+// Constructing a read-write separation data source, the read-write separation data source implements the DataSource interface, which can be directly processed as a data source. masterDataSource, slaveDataSource0, slaveDataSource1, etc. are real data sources configured using connection pools such as DBCP
+Map<String, DataSource> dataSourceMap = new HashMap<>();
+dataSourceMap.put("masterDataSource", masterDataSource);
+dataSourceMap.put("slaveDataSource0", slaveDataSource0);
+dataSourceMap.put("slaveDataSource1", slaveDataSource1);
+
+// Constructing read-write separation configuration
+MasterSlaveRuleConfiguration masterSlaveRuleConfig = new MasterSlaveRuleConfiguration();
+masterSlaveRuleConfig.setName("ms_ds");
+masterSlaveRuleConfig.setMasterDataSourceName("masterDataSource");
+masterSlaveRuleConfig.getSlaveDataSourceNames().add("slaveDataSource0");
+masterSlaveRuleConfig.getSlaveDataSourceNames().add("slaveDataSource1");
+
+DataSource dataSource = MasterSlaveDataSourceFactory.createDataSource(dataSourceMap, masterSlaveRuleConfig);
+```
+
+##### sharding table and database + read-write split
+
+```java
+// Constructing a read-write separation data source, the read-write separation data source implements the DataSource interface, which can be directly processed as a data source. masterDataSource, slaveDataSource0, slaveDataSource1, etc. are real data sources configured using connection pools such as DBCP
+Map<String, DataSource> dataSourceMap = new HashMap<>();
+dataSourceMap.put("masterDataSource0", masterDataSource0);
+dataSourceMap.put("slaveDataSource00", slaveDataSource00);
+dataSourceMap.put("slaveDataSource01", slaveDataSource01);
+
+dataSourceMap.put("masterDataSource1", masterDataSource1);
+dataSourceMap.put("slaveDataSource10", slaveDataSource10);
+dataSourceMap.put("slaveDataSource11", slaveDataSource11);
+
+// Constructing read-write separation configuration
+MasterSlaveRuleConfiguration masterSlaveRuleConfig0 = new MasterSlaveRuleConfiguration();
+masterSlaveRuleConfig0.setName("ds_0");
+masterSlaveRuleConfig0.setMasterDataSourceName("masterDataSource0");
+masterSlaveRuleConfig0.getSlaveDataSourceNames().add("slaveDataSource00");
+masterSlaveRuleConfig0.getSlaveDataSourceNames().add("slaveDataSource01");
+
+MasterSlaveRuleConfiguration masterSlaveRuleConfig1 = new MasterSlaveRuleConfiguration();
+masterSlaveRuleConfig1.setName("ds_1");
+masterSlaveRuleConfig1.setMasterDataSourceName("masterDataSource1");
+masterSlaveRuleConfig1.getSlaveDataSourceNames().add("slaveDataSource10");
+masterSlaveRuleConfig1.getSlaveDataSourceNames().add("slaveDataSource11");
+
+// Continue to create ShardingDataSource through ShardingSlaveDataSourceFactory
+ShardingRuleConfiguration shardingRuleConfig = new ShardingRuleConfiguration();
+shardingRuleConfig.getMasterSlaveRuleConfigs().add(masterSlaveRuleConfig0);
+shardingRuleConfig.getMasterSlaveRuleConfigs().add(masterSlaveRuleConfig1);
+
+DataSource dataSource = ShardingDataSourceFactory.createDataSource(dataSourceMap, shardingRuleConfig);
+```
+
+## ShardingSphere-1.x
+
+### Read-Write Split
+
+#### concept
+
+In order to relieve the pressure on the database, the write and read operations are separated into different data sources. The write library is called the master library, and the read library is called the slave library. One master library can be configured with multiple slave libraries.
+
+#### Support item
+
+1. Provides a read-write separation configuration with one master and multiple slaves, which can be used independently or with sub-databases and sub-meters.
+2. In the same thread and the same database connection, if there is a write operation, subsequent read operations will be read from the main library to ensure data consistency.
+3. Spring namespace.
+4. Hint-based mandatory main library routing.
+
+#### Unsupported item
+
+1. Data synchronization between the master library and the slave library.
+2. Data inconsistency caused by the data synchronization delay of the master library and the slave library.
+3. Double writing or multiple writing in the main library.
+
+#### Code development example
+
+```java
+// Constructing a read-write separation data source, the read-write separation data source implements the DataSource interface, which can be directly processed as a data source. masterDataSource, slaveDataSource0, slaveDataSource1, etc. are real data sources configured using connection pools such as DBCP
+Map<String, DataSource> slaveDataSourceMap0 = new HashMap<>();
+slaveDataSourceMap0.put("slaveDataSource00", slaveDataSource00);
+slaveDataSourceMap0.put("slaveDataSource01", slaveDataSource01);
+// You can choose the master-slave library load balancing strategy, the default is ROUND_ROBIN, and there is RANDOM to choose from, or customize the load strategy
+DataSource masterSlaveDs0 = MasterSlaveDataSourceFactory.createDataSource("ms_0", "masterDataSource0", masterDataSource0, slaveDataSourceMap0, MasterSlaveLoadBalanceStrategyType.ROUND_ROBIN);
+
+Map<String, DataSource> slaveDataSourceMap1 = new HashMap<>();
+slaveDataSourceMap1.put("slaveDataSource10", slaveDataSource10);
+slaveDataSourceMap1.put("slaveDataSource11", slaveDataSource11);
+DataSource masterSlaveDs1 = MasterSlaveDataSourceFactory.createDataSource("ms_1", "masterDataSource1", masterDataSource1, slaveDataSourceMap1, MasterSlaveLoadBalanceStrategyType.ROUND_ROBIN);
+
+// Constructing read-write separation configuration
+Map<String, DataSource> dataSourceMap = new HashMap<>();
+dataSourceMap.put("ms_0", masterSlaveDs0);
+dataSourceMap.put("ms_1", masterSlaveDs1);
+
+// Continue to create ShardingDataSource through ShardingSlaveDataSourceFactory
+```
\ No newline at end of file