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/06/23 10:55:05 UTC
[shardingsphere] branch master updated: For #10928,
add English doc of RDL syntax (#10939)
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 b74b8ec For #10928, add English doc of RDL syntax (#10939)
b74b8ec is described below
commit b74b8ecef6233bc3f2d319f9dcd3dac23320f21a
Author: Raigor <ra...@gmail.com>
AuthorDate: Wed Jun 23 18:54:01 2021 +0800
For #10928, add English doc of RDL syntax (#10939)
* For #10928, add English doc of RDL syntax
* For #10928, add English doc of DistSQL usage
---
.../features/dist-sql/syntax/rdl/_index.en.md | 2 +-
.../syntax/rdl/rdl-db-discovery-rule.en.md | 43 +++++++-
.../dist-sql/syntax/rdl/rdl-encrypt-rule.en.md | 51 +++++++++-
.../syntax/rdl/rdl-readwrite-splitting-rule.en.md | 59 ++++++++++-
.../dist-sql/syntax/rdl/rdl-resource.en.md | 36 ++++++-
.../dist-sql/syntax/rdl/rdl-sharding-rule.cn.md | 2 +-
.../dist-sql/syntax/rdl/rdl-sharding-rule.en.md | 112 ++++++++++++++++++++-
.../content/features/dist-sql/usage/_index.en.md | 2 +-
.../features/dist-sql/usage/sharding-rule.en.md | 105 ++++++++++++++++++-
9 files changed, 403 insertions(+), 9 deletions(-)
diff --git a/docs/document/content/features/dist-sql/syntax/rdl/_index.en.md b/docs/document/content/features/dist-sql/syntax/rdl/_index.en.md
index b001fc7..0fcf471 100644
--- a/docs/document/content/features/dist-sql/syntax/rdl/_index.en.md
+++ b/docs/document/content/features/dist-sql/syntax/rdl/_index.en.md
@@ -5,4 +5,4 @@ weight = 1
chapter = true
+++
-# TODO
+This chapter describes the syntax of RDL in detail, and introduce the use of RDL with actual examples.
diff --git a/docs/document/content/features/dist-sql/syntax/rdl/rdl-db-discovery-rule.en.md b/docs/document/content/features/dist-sql/syntax/rdl/rdl-db-discovery-rule.en.md
index 47a9110..6dc510a 100644
--- a/docs/document/content/features/dist-sql/syntax/rdl/rdl-db-discovery-rule.en.md
+++ b/docs/document/content/features/dist-sql/syntax/rdl/rdl-db-discovery-rule.en.md
@@ -3,4 +3,45 @@ title = "DB Discovery"
weight = 5
+++
-## TODO
+## Definition
+
+```sql
+CREATE DB_DISCOVERY RULE databaseDiscoveryRuleDefinition [, databaseDiscoveryRuleDefinition] ...
+
+ALTER DB_DISCOVERY RULE databaseDiscoveryRuleDefinition [, databaseDiscoveryRuleDefinition] ...
+
+DROP DB_DISCOVERY RULE ruleName [, ruleName] ...
+
+databaseDiscoveryRuleDefinition:
+ ruleName(resources, discoveryTypeDefinition)
+
+resources:
+ RESOURCES(resourceName [, resourceName] ...)
+
+discoveryTypeDefinition:
+ TYPE(NAME=discoveryType [, PROPERTIES([algorithmProperties] )] )
+
+algorithmProperties:
+ algorithmProperty [, algorithmProperty] ...
+
+algorithmProperty:
+ key=value
+```
+- `discoveryType` specifies the database discovery service type, `ShardingSphere` has built-in support for `MGR`
+- Duplicate `ruleName` will not be created
+
+## Example
+
+```sql
+CREATE DB_DISCOVERY RULE ha_group_0 (
+RESOURCES(resource_0,resource_1),
+TYPE(NAME=mgr,PROPERTIES(groupName='92504d5b-6dec',keepAliveCron=''))
+);
+
+ALTER DB_DISCOVERY RULE ha_group_0 (
+RESOURCES(resource_0,resource_1,resource_2),
+TYPE(NAME=mgr,PROPERTIES(groupName='92504d5b-6dec' ,keepAliveCron=''))
+);
+
+DROP DB_DISCOVERY RULE ha_group_0;
+```
diff --git a/docs/document/content/features/dist-sql/syntax/rdl/rdl-encrypt-rule.en.md b/docs/document/content/features/dist-sql/syntax/rdl/rdl-encrypt-rule.en.md
index 8fc7ff0..065203c 100644
--- a/docs/document/content/features/dist-sql/syntax/rdl/rdl-encrypt-rule.en.md
+++ b/docs/document/content/features/dist-sql/syntax/rdl/rdl-encrypt-rule.en.md
@@ -3,4 +3,53 @@ title = "Encrypt"
weight = 4
+++
-## TODO
+## Definition
+
+```sql
+CREATE ENCRYPT RULE encryptRuleDefinition [, encryptRuleDefinition] ...
+
+ALTER ENCRYPT RULE encryptRuleDefinition [, encryptRuleDefinition] ...
+
+DROP ENCRYPT RULE tableName [, tableName] ...
+
+encryptRuleDefinition:
+ tableName(COLUMNS(columnDefinition [, columnDefinition] ...))
+
+columnDefinition:
+ (NAME=columnName [, PLAIN=plainColumnName] , CIPHER=cipherColumnName, encryptAlgorithm)
+
+encryptAlgorithm:
+ TYPE(NAME=encryptAlgorithmType [, PROPERTIES([algorithmProperties] )] )
+
+algorithmProperties:
+ algorithmProperty [, algorithmProperty] ...
+
+algorithmProperty:
+ key=value
+```
+- `PLAIN` specifies the plain column, `CIPHER` specifies the cipher column
+- `encryptAlgorithmType` specifies the encryption algorithm type, please refer to [Encryption Algorithm](/en/user-manual/shardingsphere-jdbc/configuration/built-in-algorithm/encrypt/)
+- Duplicate `tableName` will not be created
+
+## Example
+
+```sql
+CREATE ENCRYPT RULE t_encrypt (
+COLUMNS(
+(NAME=user_id,PLAIN=user_plain,CIPHER=user_cipher,TYPE(NAME=AES,PROPERTIES('aes-key-value'=123456abc))),
+(NAME=order_id, CIPHER =order_cipher,TYPE(NAME=MD5))
+)),
+t_encrypt_2 (
+COLUMNS(
+(NAME=user_id,PLAIN=user_plain,CIPHER=user_cipher,TYPE(NAME=AES,PROPERTIES('aes-key-value'=123456abc))),
+(NAME=order_id, CIPHER=order_cipher,TYPE(NAME=MD5))
+));
+
+ALTER ENCRYPT RULE t_encrypt (
+COLUMNS(
+(NAME=user_id,PLAIN=user_plain,CIPHER=user_cipher,TYPE(NAME=AES,PROPERTIES('aes-key-value'=123456abc))),
+(NAME=order_id,CIPHER=order_cipher,TYPE(NAME=MD5))
+));
+
+DROP ENCRYPT RULE t_encrypt,t_encrypt_2;
+```
diff --git a/docs/document/content/features/dist-sql/syntax/rdl/rdl-readwrite-splitting-rule.en.md b/docs/document/content/features/dist-sql/syntax/rdl/rdl-readwrite-splitting-rule.en.md
index 3f1b641..a870413 100644
--- a/docs/document/content/features/dist-sql/syntax/rdl/rdl-readwrite-splitting-rule.en.md
+++ b/docs/document/content/features/dist-sql/syntax/rdl/rdl-readwrite-splitting-rule.en.md
@@ -3,4 +3,61 @@ title = "Readwrite-Splitting"
weight = 3
+++
-## TODO
+## Definition
+
+```sql
+CREATE READWRITE_SPLITTING RULE readwriteSplittingRuleDefinition [, readwriteSplittingRuleDefinition] ...
+
+ALTER READWRITE_SPLITTING RULE readwriteSplittingRuleDefinition [, readwriteSplittingRuleDefinition] ...
+
+DROP READWRITE_SPLITTING RULE ruleName [, ruleName] ...
+
+readwriteSplittingRuleDefinition:
+ ruleName ([staticReadwriteSplittingRuleDefinition | dynamicReadwriteSplittingRuleDefinition]
+ [, loadBanlancerDefinition])
+
+staticReadwriteSplittingRuleDefinition:
+ WRITE_RESOURCE=writeResourceName, READ_RESOURCES(resourceName [, resourceName] ... )
+
+dynamicReadwriteSplittingRuleDefinition:
+ AUTO_AWARE_RESOURCE=resourceName
+
+loadBanlancerDefinition:
+ TYPE(NAME=loadBanlancerType [, PROPERTIES([algorithmProperties] )] )
+
+algorithmProperties:
+ algorithmProperty [, algorithmProperty] ...
+
+algorithmProperty:
+ key=value
+```
+
+- Support the creation of static readwrite-splitting rules and dynamic readwrite-splitting rules
+- Dynamic readwrite-splitting rules rely on database discovery rules
+- `loadBanlancerType` specifies the load balancing algorithm type, please refer to [Load Balance Algorithm](/en/user-manual/shardingsphere-jdbc/configuration/built-in-algorithm/load-balance/)
+- Duplicate `ruleName` will not be created
+
+## Example
+
+```sql
+// Static
+CREATE READWRITE_SPLITTING RULE ms_group_0 (
+WRITE_RESOURCE=write_ds,
+READ_RESOURCES(read_ds_0,read_ds_1),
+TYPE(NAME=random)
+);
+
+// Dynamic
+CREATE READWRITE_SPLITTING RULE ms_group_1 (
+AUTO_AWARE_RESOURCE=group_0,
+TYPE(NAME=random,PROPERTIES(read_weight='2:1'))
+);
+
+ALTER READWRITE_SPLITTING RULE ms_group_1 (
+WRITE_RESOURCE=write_ds,
+READ_RESOURCES(read_ds_0,read_ds_1,read_ds_2),
+TYPE(NAME=random,PROPERTIES(read_weight='2:0'))
+);
+
+DROP READWRITE_SPLITTING RULE ms_group_1;
+```
diff --git a/docs/document/content/features/dist-sql/syntax/rdl/rdl-resource.en.md b/docs/document/content/features/dist-sql/syntax/rdl/rdl-resource.en.md
index 2bbca87..798b94c 100644
--- a/docs/document/content/features/dist-sql/syntax/rdl/rdl-resource.en.md
+++ b/docs/document/content/features/dist-sql/syntax/rdl/rdl-resource.en.md
@@ -3,4 +3,38 @@ title = "Data Source"
weight = 1
+++
-## TODO
+## Definition
+
+```sql
+ADD RESOURCE dataSource [, dataSource] ...
+
+dataSource:
+ dataSourceName(HOST=hostName,PORT=port,DB=dbName,USER=user [, PASSWORD=password])
+
+DROP RESOURCE dataSourceName [, dataSourceName] ...
+```
+
+- Before adding resources, please confirm that a distributed database has been created, and execute the `use` command to successfully select a database
+- Confirm that the added resource can be connected normally, otherwise it will not be added successfully
+- Duplicate `dataSourceName` is not allowed to be added
+- `DROP RESOURCE` will only delete logical resources, not real data sources
+- Resources referenced by rules cannot be deleted
+
+## Example
+
+```sql
+ADD RESOURCE resource_0 (
+ HOST=127.0.0.1,
+ PORT=3306,
+ DB=db0,
+ USER=root,
+ PASSWORD=root
+),resource_1 (
+ HOST=127.0.0.1,
+ PORT=3306,
+ DB=db1,
+ USER=root
+);
+
+DROP RESOURCE resource_0, resource_1;
+```
diff --git a/docs/document/content/features/dist-sql/syntax/rdl/rdl-sharding-rule.cn.md b/docs/document/content/features/dist-sql/syntax/rdl/rdl-sharding-rule.cn.md
index 8f27443..2480f4c 100644
--- a/docs/document/content/features/dist-sql/syntax/rdl/rdl-sharding-rule.cn.md
+++ b/docs/document/content/features/dist-sql/syntax/rdl/rdl-sharding-rule.cn.md
@@ -40,7 +40,7 @@ algorithmProperty:
```
- `RESOURCES` 需使用 RDL 管理的数据源资源
- `shardingAlgorithmType` 指定自动分片算法类型，请参考 [自动分片算法](/cn/user-manual/shardingsphere-jdbc/configuration/built-in-algorithm/sharding/)
-- `keyGenerateStrategyType` 指定分布式主键生成策，请参考 [分布式主键](/cn/user-manual/shardingsphere-jdbc/configuration/built-in-algorithm/keygen/)
+- `keyGenerateStrategyType` 指定分布式主键生成策略，请参考 [分布式主键](/cn/user-manual/shardingsphere-jdbc/configuration/built-in-algorithm/keygen/)
- 重复的 `tableName` 将无法被创建
### Sharding Binding Table Rule
diff --git a/docs/document/content/features/dist-sql/syntax/rdl/rdl-sharding-rule.en.md b/docs/document/content/features/dist-sql/syntax/rdl/rdl-sharding-rule.en.md
index 33e995a..a66dcd3 100644
--- a/docs/document/content/features/dist-sql/syntax/rdl/rdl-sharding-rule.en.md
+++ b/docs/document/content/features/dist-sql/syntax/rdl/rdl-sharding-rule.en.md
@@ -3,4 +3,114 @@ title = "Sharding"
weight = 2
+++
-## TODO
+## Definition
+
+### Sharding Table Rule
+
+```sql
+CREATE SHARDING TABLE RULE shardingTableRuleDefinition [, shardingTableRuleDefinition] ...
+
+ALTER SHARDING TABLE RULE shardingTableRuleDefinition [, shardingTableRuleDefinition] ...
+
+DROP SHARDING TABLE RULE tableName [, tableName] ...
+
+shardingTableRuleDefinition:
+ tableName(resources [, shardingColumn] [, shardingAlgorithm] [, keyGenerateStrategy])
+
+resources:
+ RESOURCES(resourceName [, resourceName] ...))
+
+shardingColumn:
+ SHARDING_COLUMN=columnName
+
+shardingAlgorithm:
+ TYPE(NAME=shardingAlgorithmType [, PROPERTIES([algorithmProperties] )] )
+
+keyGenerateStrategy:
+ GENERATED_KEY(COLUMN=columnName,strategyDefinition)
+
+strategyDefinition:
+ TYPE(NAME=keyGenerateStrategyType [, PROPERTIES([algorithmProperties] )] )
+
+algorithmProperties:
+ algorithmProperty [, algorithmProperty] ...
+
+algorithmProperty:
+ key=value
+```
+- `RESOURCES` needs to use data source resources managed by RDL
+- `shardingAlgorithmType` specifies the type of automatic sharding algorithm, please refer to [Auto Sharding Algorithm](/en/user-manual/shardingsphere-jdbc/configuration/built-in-algorithm/sharding/)
+- `keyGenerateStrategyType` specifies the distributed primary key generation strategy, please refer to [Key Generate Algorithm](/en/user-manual/shardingsphere-jdbc/configuration/built-in-algorithm/keygen/)
+- Duplicate `tableName` will not be created
+
+### Sharding Binding Table Rule
+
+```sql
+CREATE SHARDING BINDING TABLE RULES(bindTableRulesDefinition [, bindTableRulesDefinition] ...)
+
+ALTER SHARDING BINDING TABLE RULES(bindTableRulesDefinition [, bindTableRulesDefinition] ...)
+
+DROP SHARDING BINDING TABLE RULES
+
+bindTableRulesDefinition:
+ (tableName [, tableName] ... )
+```
+- `ALTER` will overwrite the binding table configuration in the database with the new configuration
+
+### Sharding Broadcast Table Rule
+
+```sql
+CREATE SHARDING BROADCAST TABLE RULES (tableName [, tableName] ... )
+
+ALTER SHARDING BROADCAST TABLE RULES (tableName [, tableName] ... )
+
+DROP SHARDING BROADCAST TABLE RULES
+```
+- `ALTER` will overwrite the broadcast table configuration in the database with the new configuration
+
+## Example
+
+### Sharding Table Rule
+
+```sql
+CREATE SHARDING TABLE RULE t_order (
+RESOURCES(resource_0,resource_1),
+SHARDING_COLUMN=order_id,
+TYPE(NAME=hash_mod,PROPERTIES("sharding-count"=4)),
+GENERATED_KEY(COLUMN=another_id,TYPE(NAME=snowflake,PROPERTIES("worker-id"=123)))
+);
+
+ALTER SHARDING TABLE RULE t_order (
+RESOURCES(resource_0,resource_1),
+SHARDING_COLUMN=order_id,
+TYPE(NAME=hash_mod,PROPERTIES("sharding-count"=10)),
+GENERATED_KEY(COLUMN=another_id,TYPE(NAME=snowflake,PROPERTIES("worker-id"=123)))
+);
+
+DROP SHARDING TABLE RULE t_order, t_order_item;
+```
+
+### Sharding Binding Table Rule
+
+```sql
+CREATE SHARDING BINDING TABLE RULES (
+(t_order,t_order_item),
+(t_1,t_2)
+);
+
+ALTER SHARDING BINDING TABLE RULES (
+(t_order,t_order_item)
+);
+
+DROP SHARDING BINDING TABLE RULES;
+```
+
+### Sharding Broadcast Table Rule
+
+```sql
+CREATE SHARDING BROADCAST TABLE RULES (t_b,t_a);
+
+ALTER SHARDING BROADCAST TABLE RULES (t_b,t_a,t_3);
+
+DROP SHARDING BROADCAST TABLE RULES;
+```
diff --git a/docs/document/content/features/dist-sql/usage/_index.en.md b/docs/document/content/features/dist-sql/usage/_index.en.md
index 8524ee8..fb55b68 100644
--- a/docs/document/content/features/dist-sql/usage/_index.en.md
+++ b/docs/document/content/features/dist-sql/usage/_index.en.md
@@ -5,4 +5,4 @@ weight = 2
chapter = true
+++
-## TODO
+This chapter will introduce how to use DistSQL to manage sharding, readwrite-splitting and other rules in a distributed database.
\ No newline at end of file
diff --git a/docs/document/content/features/dist-sql/usage/sharding-rule.en.md b/docs/document/content/features/dist-sql/usage/sharding-rule.en.md
index 4f66602..3808705 100644
--- a/docs/document/content/features/dist-sql/usage/sharding-rule.en.md
+++ b/docs/document/content/features/dist-sql/usage/sharding-rule.en.md
@@ -3,4 +3,107 @@ title = "Sharding"
weight = 1
+++
-## TODO
+## Usage
+
+### Pre-work
+
+1. Start the MySQL service
+2. Create MySQL database (refer to ShardingProxy data source configuration rules)
+3. Create a role or user with creation permission for ShardingProxy
+4. Start Zookeeper service (for persistent configuration)
+
+### Start ShardingProxy
+
+1. Add `governance` and `authentication` configurations to `server.yaml` (please refer to the example of ShardingProxy)
+2. Start ShardingProxy ([Related introduction](/en/quick-start/shardingsphere-proxy-quick-start/))
+
+### Create a distributed database and sharding tables
+
+1. Connect to ShardingProxy
+2. Create a distributed database
+
+```SQL
+CREATE DATABASE sharding_db;
+```
+
+3. Use newly created database
+
+```SQL
+USE sharding_db;
+```
+
+2. Configure data source information
+
+```SQL
+ADD RESOURCE ds_0 (
+HOST=127.0.0.1,
+PORT=3306,
+DB=ds_1,
+USER=root,
+PASSWORD=root
+);
+
+ADD RESOURCE ds_1 (
+HOST=127.0.0.1,
+PORT=3306,
+DB=ds_2,
+USER=root,
+PASSWORD=root
+);
+```
+
+3. Create sharding rules
+
+```SQL
+CREATE SHARDING TABLE RULE t_order(
+RESOURCES(ds_0,ds_1),
+SHARDING_COLUMN=order_id,
+TYPE(NAME=hash_mod,PROPERTIES("sharding-count"=4)),
+GENERATED_KEY(COLUMN=order_id,TYPE(NAME=snowflake,PROPERTIES("worker-id"=123)))
+);
+```
+
+4. Create sharding table
+
+```SQL
+CREATE TABLE `t_order` (
+ `order_id` int NOT NULL,
+ `user_id` int NOT NULL,
+ `status` varchar(45) DEFAULT NULL,
+ PRIMARY KEY (`order_id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4
+```
+
+5. Drop sharding table
+
+```SQL
+DROP TABLE t_order;
+```
+
+6. Drop sharding rule
+
+```SQL
+DROP SHARDING TABLE RULE t_order;
+```
+
+7. Drop resource
+
+```SQL
+DROP RESOURCE ds_0, ds_1;
+```
+
+8. Drop distributed database
+
+```SQL
+DROP DATABASE sharding_db;
+```
+
+### Notice
+
+1. Currently, `DROP DATABASE` will only remove the `logical distributed database`, not the user's actual database (**TODO**).
+2. `DROP TABLE` will delete all logical fragmented tables and actual tables in the database.
+3. `CREATE DATABASE` will only create a `logical distributed database`, so users need to create actual databases in advance (**TODO**).
+4. The `Auto Sharding Algorithm` will continue to increase to cover the user's various sharding scenarios (**TODO**).
+5. Refactor `ShardingAlgorithmPropertiesUtil`(**TODO**).
+6. Ensure that all clients complete RDL execution (**TODO**).
+7. Add support for `ALTER DATABASE` and `ALTER TABLE` (**TODO**).