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 8e30ce2 Update shadow docs (#12993)
8e30ce2 is described below
commit 8e30ce234bfccb8246c297be6f527bebfcc10175
Author: gin <[email protected]>
AuthorDate: Mon Oct 11 22:14:14 2021 +0800
Update shadow docs (#12993)
---
.../document/content/features/shadow/concept.cn.md | 4 +
.../content/features/shadow/principle.cn.md | 137 +++++++++++++++++++--
.../content/features/shadow/principle.en.md | 19 +++
docs/document/static/img/shadow/execute.png | Bin 53553 -> 70280 bytes
docs/document/static/img/shadow/rule_cn.png | Bin 49363 -> 254987 bytes
docs/document/static/img/shadow/rule_en.png | Bin 50901 -> 220352 bytes
6 files changed, 150 insertions(+), 10 deletions(-)
diff --git a/docs/document/content/features/shadow/concept.cn.md
b/docs/document/content/features/shadow/concept.cn.md
index 75be271..dba301b 100644
--- a/docs/document/content/features/shadow/concept.cn.md
+++ b/docs/document/content/features/shadow/concept.cn.md
@@ -4,6 +4,10 @@ title = "核心概念"
weight = 1
+++
+## 影子库开关
+
+影子库开关。压力测试是一个特定时段的需求，在需要时开启即可。
+
## 生产数据库
生产数据使用的数据库。
diff --git a/docs/document/content/features/shadow/principle.cn.md
b/docs/document/content/features/shadow/principle.cn.md
index c2e9937..f224778 100644
--- a/docs/document/content/features/shadow/principle.cn.md
+++ b/docs/document/content/features/shadow/principle.cn.md
@@ -4,28 +4,145 @@ title = "实现原理"
weight = 2
+++
-### 整体架构
+## 整体架构
-Apache ShardingSphere 通过解析 SQL，根据配置文件中用户设置的影子规则，对传入的 SQL
进行路由并改写，删除影子字段与字段值。用户无需关注具体过程，
-使用时仅对 SQL 进行相应改造，添加影子字段与相应的配置即可。
+Apache ShardingSphere 通过解析 SQL，对传入的 SQL 进行影子判定，根据配置文件中用户设置的影子规则，路由到生产库或者影子库。
-### 影子规则
+## 影子规则
-影子规则包含影子字段及映射关系。
+影子规则包含影子数据源映射关系，影子表以及影子算法。
-### 处理过程
+## 路由过程
以 INSERT 语句为例，在写入数据时，Apache ShardingSphere 会对 SQL
进行解析，再根据配置文件中的规则，构造一条路由链。在当前版本的功能中，
影子功能处于路由链中的最后一个执行单元，即，如果有其他需要路由的规则存在，如分片，Apache ShardingSphere
会首先根据分片规则，路由到某一个数据库，再
-执行影子路由，将影子数据路由到与之对应的影子库，生产数据则维持不变。
+执行影子路由判定流程，判定执行SQL满足影子规则的配置，数据路由到与之对应的影子库，生产数据则维持不变。
-接着对 SQL 进行改写，由于影子字段为逻辑字段，在数据库中实际不存在，所以在改写过程中会删除这个字段及其对应的参数。
+## 影子判定流程
+影子库开关开启时，会对执行的 SQL 语句进行影子判定。影子判定目前支持两种类型算法，用户可根据实际业务需求选择一种或者组合使用。
-DML 语句的处理过程同理，对于非 DML 语句，如创建数据表等，会在生产数据库与影子数据库分别执行。
+### DML 语句
-
+支持两种算法。影子判定会首先判断执行 SQL
关联的表是否和影子表有交集。如果有交集，对交集部分影子表关联的影子算法依次判定。如果影子表关联影子算法有任何一个判定成功。SQL 语句路由到影子库。
+没有交集或者影子算法判定不成功，SQL 语句路由到生产库。
+举例说明，一个电商网站要对下单业务进行压测，对订单表 `t_order`
进行压测。生产数据执行到生产库，即：ds。测试数据执行到影子库，即：ds-shadow。
+
+1. 使用列影子算法
+
+假设 `t_order` 表中包含字段下单用户ID的 `user_id`。 如果实现的效果，当用户ID为 `0`
的用户创建订单产生的数据，即：`INSERT INTO t_order (order_id, user_id, ...) VALUES (xxx..., 0,
...)` 会执行到影子库，其他数据执行到生产库。
+
+建议配置如下（YAML 格式展示）：
+
+```yaml
+enable: true
+ data-sources:
+ shadow-data-source:
+ source-data-source-name: ds
+ shadow-data-source-name: ds-shadow
+tables:
+ t_order:
+ data-source-names: shadow-data-source
+ shadow-algorithm-names:
+ - user-id-match-algorithm
+shadow-algorithms:
+ user-id-match-algorithm:
+ type: COLUMN_REGEX_MATCH
+ props:
+ operation: insert
+ column: user_id
+ regex: "[0]"
+```
+无需修改任何 SQL 或者代码，只需要对压力测试的数据进行控制就可以实现在线的压力测试。
+
+2. 使用注解影子算法
+
+假设 `t_order` 表中没有存储可以对值进行控制的列。或者控制的值不包含在执行 SQL 的中。可以添加一条注解到执行的 SQL 中，即：`SELECT
* FROM t_order WHERE order_id = xxx /*shadow:true,foo:bar,...*/` 会执行到影子库。
+
+建议配置如下（YAML 格式展示）：
+
+```yaml
+enable: true
+ data-sources:
+ shadow-data-source:
+ source-data-source-name: ds
+ shadow-data-source-name: ds-shadow
+tables:
+ t_order:
+ data-source-names: shadow-data-source
+ shadow-algorithm-names:
+ - simple-note-algorithm
+shadow-algorithms:
+ simple-note-algorithm:
+ type: SIMPLE_NOTE
+ props:
+ shadow: true
+ foo: bar
+
+props:
+ sql-comment-parse-enabled: true
+```
+注意：使用注解影子算法，需配合开起 SQL 注解解析。
+
+### 3. 混用模式
+
+假设对 `t_order` 表压测以上两种场景都需要覆盖。即，`INSERT INTO t_order (order_id, user_id, ...)
VALUES (xxx..., 0, ...)` 和 `SELECT * FROM t_order WHERE order_id = xxx
/*shadow:true,foo:bar,...*/` 都执行到影子库。
+
+建议配置如下（YAML 格式展示）：
+
+```yaml
+enable: true
+ data-sources:
+ shadow-data-source:
+ source-data-source-name: ds
+ shadow-data-source-name: ds-shadow
+tables:
+ t_order:
+ data-source-names: shadow-data-source
+ shadow-algorithm-names:
+ - user-id-match-algorithm
+ - simple-note-algorithm
+shadow-algorithms:
+ user-id-match-algorithm:
+ type: COLUMN_REGEX_MATCH
+ props:
+ operation: insert
+ column: user_id
+ regex: "[0]"
+ simple-note-algorithm:
+ type: SIMPLE_NOTE
+ props:
+ shadow: true
+ foo: bar
+
+props:
+ sql-comment-parse-enabled: true
+```
+对复杂场景压力测试支持度高。
+
+### DDL 语句
+
+仅支持影子算法。一般不会对 DDL 语句的压力测试。主要为影子库环境的初始化或者影子表调整时执行。
+
+影子判定会首先判断执行 SQL 是否包含注解，如果包含注解对影子规则中的注解影子算法依次判定。如果注解影子算法有任何一个判定成功。SQL 语句路由到影子库。
+没有 SQL 不包含注解或者注解影子算法判定不成功，路由到生产库。
+
+假设需要在影子库创建 `t_order` 表。即：`CREATE TABLE t_order (order_id INT(11) primary key,
user_id int(11) not null, ...) /*shadow:true,foo:bar,...*/` 执行到影子库。
+
+影子规则配置只需包含（YAML 格式展示）：
+
+```yaml
+shadow-algorithms:
+ simple-note-algorithm:
+ type: SIMPLE_NOTE
+ props:
+ shadow: true
+ foo: bar
+
+props:
+ sql-comment-parse-enabled: true
+```
diff --git a/docs/document/content/features/shadow/principle.en.md
b/docs/document/content/features/shadow/principle.en.md
index a7594be..3dbe189 100644
--- a/docs/document/content/features/shadow/principle.en.md
+++ b/docs/document/content/features/shadow/principle.en.md
@@ -4,5 +4,24 @@ title = "Principle"
weight = 2
+++
+## Overall Architecture
+
+TODO
+
+## Shadow Rule
+
+TODO
+
+## Routing Process
+
TODO
+## Shadow Judgment Process
+
+### DML Statement
+
+TODO
+
+### DDL Statement
+
+TODO
diff --git a/docs/document/static/img/shadow/execute.png
b/docs/document/static/img/shadow/execute.png
index 261f8ac..bd9179c 100644
Binary files a/docs/document/static/img/shadow/execute.png and
b/docs/document/static/img/shadow/execute.png differ
diff --git a/docs/document/static/img/shadow/rule_cn.png
b/docs/document/static/img/shadow/rule_cn.png
index 012682a..70edf0c 100644
Binary files a/docs/document/static/img/shadow/rule_cn.png and
b/docs/document/static/img/shadow/rule_cn.png differ
diff --git a/docs/document/static/img/shadow/rule_en.png
b/docs/document/static/img/shadow/rule_en.png
index 78726fa..941e67a 100644
Binary files a/docs/document/static/img/shadow/rule_en.png and
b/docs/document/static/img/shadow/rule_en.png differ
