You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@shardingsphere.apache.org by so...@apache.org on 2022/07/28 02:00:34 UTC
[shardingsphere] branch master updated: modify according to new module (#19616)
This is an automated email from the ASF dual-hosted git repository.
soulasuna 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 35d68ef3908 modify according to new module (#19616)
35d68ef3908 is described below
commit 35d68ef3908f86a0d74136b1154030b04bc45f3e
Author: Mike0601 <40...@users.noreply.github.com>
AuthorDate: Thu Jul 28 10:00:27 2022 +0800
modify according to new module (#19616)
* Refactor document
Remove concepts document
* refactor
* update feature sharding
* update according new module
* update according to new module
* update according to new module
* update according to new module
* modify according to new module
---
.../builtin-algorithm/keygen.cn.md | 51 +++++++++++++++++--
.../builtin-algorithm/keygen.en.md | 57 ++++++++++++++++++++--
2 files changed, 100 insertions(+), 8 deletions(-)
diff --git a/docs/document/content/user-manual/shardingsphere-jdbc/builtin-algorithm/keygen.cn.md b/docs/document/content/user-manual/shardingsphere-jdbc/builtin-algorithm/keygen.cn.md
index df2e5c9a80a..4199824b922 100644
--- a/docs/document/content/user-manual/shardingsphere-jdbc/builtin-algorithm/keygen.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-jdbc/builtin-algorithm/keygen.cn.md
@@ -3,7 +3,15 @@ title = "分布式序列算法"
weight = 3
+++
-## 雪花算法
+## 背景信息
+
+传统数据库软件开发中，主键自动生成技术是基本需求。而各个数据库对于该需求也提供了相应的支持，比如 MySQL 的自增键，Oracle 的自增序列等。 数据分片后，不同数据节点生成全局唯一主键是非常棘手的问题。同一个逻辑表内的不同实际表之间的自增键由于无法互相感知而产生重复主键。 虽然可通过约束自增主键初始值和步长的方式避免碰撞，但需引入额外的运维规则，使解决方案缺乏完整性和可扩展性。
+
+目前有许多第三方解决方案可以完美解决这个问题，如 UUID 等依靠特定算法自生成不重复键，或者通过引入主键生成服务等。为了方便用户使用、满足不同用户不同使用场景的需求， Apache ShardingSphere 不仅提供了内置的分布式主键生成器，例如 UUID、SNOWFLAKE，还抽离出分布式主键生成器的接口，方便用户自行实现自定义的自增主键生成器。
+
+## 参数解释
+
+### 雪花算法
类型：SNOWFLAKE
@@ -14,13 +22,19 @@ weight = 3
| max-vibration-offset (?) | int | 最大抖动上限值，范围[0, 4096)。注：若使用此算法生成值作分片值，建议配置此属性。此算法在不同毫秒内所生成的 key 取模 2^n (2^n一般为分库或分表数) 之后结果总为 0 或 1。为防止上述分片问题，建议将此属性值配置为 (2^n)-1 | 1 |
| max-tolerate-time-difference-milliseconds (?) | long | 最大容忍时钟回退时间，单位：毫秒 | 10 毫秒 |
-## UUID
+### NanoID
+
+类型：NANOID
+
+可配置属性： 无
+
+### UUID
类型：UUID
可配置属性：无
-## CosId
+### CosId
类型: COSID
@@ -31,7 +45,7 @@ weight = 3
| id-name | String | ID 生成器名称 | `__share__` |
| as-string | bool | 是否生成字符串类型ID: 将 `long` 类型 ID 转换成 62 进制 `String` 类型（`Long.MAX_VALUE` 最大字符串长度11位），并保证字符串 ID 有序性 | `false` |
-## CosId-Snowflake
+### CosId-Snowflake
类型: COSID_SNOWFLAKE
@@ -42,3 +56,32 @@ weight = 3
| epoch | String | 雪花 ID 算法的 EPOCH | `1477929600000` |
| as-string | bool | 是否生成字符串类型ID: 将 `long` 类型 ID 转换成 62 进制 `String` 类型（`Long.MAX_VALUE` 最大字符串长度11位），并保证字符串 ID 有序性 | `false` |
+## 操作步骤
+
+1. 配置数据分片规则时为列配置分布式主键生成策略
+
+## 配置示例
+
+- 雪花算法
+
+```yaml
+keyGenerators:
+ snowflake:
+ type: SNOWFLAKE
+```
+
+- NanoID
+
+```yaml
+keyGenerators:
+ nanoid:
+ type: NANOID
+```
+
+- UUID
+
+```yaml
+keyGenerators:
+ nanoid:
+ type: UUID
+```
\ No newline at end of file
diff --git a/docs/document/content/user-manual/shardingsphere-jdbc/builtin-algorithm/keygen.en.md b/docs/document/content/user-manual/shardingsphere-jdbc/builtin-algorithm/keygen.en.md
index 6c8a2557047..78ec11c1751 100644
--- a/docs/document/content/user-manual/shardingsphere-jdbc/builtin-algorithm/keygen.en.md
+++ b/docs/document/content/user-manual/shardingsphere-jdbc/builtin-algorithm/keygen.en.md
@@ -3,7 +3,20 @@ title = "Key Generate Algorithm"
weight = 3
+++
-## Snowflake
+## Background
+
+In traditional database software development, automatic primary key generation is a basic requirement and various databases provide support for this requirement, such as MySQL's self-incrementing keys, Oracle's self-incrementing sequences, etc.
+
+After data sharding, it is a very tricky problem to generate global unique primary keys from different data nodes. Self-incrementing keys between different actual tables within the same logical table generate duplicate primary keys because they are not mutually perceived.
+
+Although collisions can be avoided by constraining the initial value and step size of self-incrementing primary keys, additional O&M rules must to be introduced, making the solution lack completeness and scalability.
+
+There are many third-party solutions that can perfectly solve this problem, such as UUID, which relies on specific algorithms to generate non-duplicate keys, or by introducing primary key generation services.
+
+In order to cater to the requirements of different users in different scenarios, Apache ShardingSphere not only provides built-in distributed primary key generators, such as UUID, SNOWFLAKE, but also abstracts the interface of distributed primary key generators to facilitate users to implement their own customized primary key generators.
+
+## Parameters
+### Snowflake
Type: SNOWFLAKE
@@ -14,13 +27,19 @@ Attributes:
| max-tolerate-time-difference-milliseconds (?) | long | The max tolerate time for different server's time difference in milliseconds | 10 milliseconds |
| max-vibration-offset (?) | int | The max upper limit value of vibrate number, range `[0, 4096)`. Notice: To use the generated value of this algorithm as sharding value, it is recommended to configure this property. The algorithm generates key mod `2^n` (`2^n` is usually the sharding amount of tables or databases) in different milliseconds and the result is always `0` or `1`. To prevent the above sharding problem, it is recommended to configure this property, [...]
-## UUID
+### Nano ID
+
+Type:NANOID
+
+Configurable Property:none
+
+### UUID
Type: UUID
Attributes: None
-## CosId
+### CosId
Type: COSID
@@ -31,7 +50,7 @@ Attributes：
| id-name | String | ID generator name | `__share__` |
| as-string | bool | Whether to generate a string type ID: Convert `long` type ID to Base-62 `String` type (`Long.MAX_VALUE` maximum string length is 11 digits), and ensure the ordering of string IDs | `false` |
-## CosId-Snowflake
+### CosId-Snowflake
Type: COSID_SNOWFLAKE
@@ -42,3 +61,33 @@ Attributes：
| epoch | String | EPOCH of Snowflake ID Algorithm | `1477929600000` |
| as-string | bool | Whether to generate a string type ID: Convert `long` type ID to Base-62 `String` type (`Long.MAX_VALUE` maximum string length is 11 digits), and ensure the ordering of string IDs | `false` |
+## Procedure
+
+1. Policy of distributed primary key configurations is for columns when configuring data sharding rules.
+
+## Sample
+
+- Snowflake Algorithms
+
+```PlainText
+keyGenerators:
+ snowflake:
+ type: SNOWFLAKE
+```
+
+- NanoID
+
+```PlainText
+keyGenerators:
+ nanoid:
+ type: NANOID
+```
+
+- UUID
+
+```PlainText
+keyGenerators:
+ nanoid:
+ type: UUID
+
+```
\ No newline at end of file