sandynz commented on a change in pull request #14062: URL: https://github.com/apache/shardingsphere/pull/14062#discussion_r767276432
########## File path: docs/document/content/user-manual/shardingsphere-scaling/build.cn.md ########## @@ -18,7 +18,61 @@ mvn clean install -Dmaven.javadoc.skip=true -Dcheckstyle.skip=true -Drat.skip=tr 或者通过[下载页面]( https://shardingsphere.apache.org/document/current/cn/downloads/ )获取安装包。 -2. 解压缩 proxy 发布包，修改配置文件 `conf/server.yaml`，这里主要是开启 `scaling` 和 `mode` 配置： +> Scaling还是实验性质的功能，在持续进化中，建议使用master分支最新版本，点击此处[下载最新版本]( http://117.48.121.24:8080/Proxy/ ) + +2. 解压缩 proxy发布包，修改配置文件`conf/sharding.yaml`，配置`schemaName`，`dataSources`，`rules`里的`shardingAlgorithms`和`keyGenerators`，以下示例可供参考： +```yaml +schemaName: sharding_db + +dataSources: + ds_0: + url: jdbc:mysql://127.0.0.1:3308/account?serverTimezone=UTC&useSSL=false + username: root + password: root + connectionTimeoutMilliseconds: 30000 + idleTimeoutMilliseconds: 60000 + maxLifetimeMilliseconds: 1800000 + maxPoolSize: 50 + minPoolSize: 1 + +rules: +- !SHARDING + tables: + user: + actualDataNodes: ds_0.user + databaseStrategy: + standard: + shardingColumn: id + shardingAlgorithmName: database_inline + tableStrategy: + standard: + shardingColumn: id + shardingAlgorithmName: user_inline + keyGenerateStrategy: + column: id + keyGeneratorName: snowflake + + shardingAlgorithms: + database_inline: + type: INLINE + props: + algorithm-expression: ds_0 + user_inline: + type: INLINE + props: + algorithm-expression: user_${id % 16} + + keyGenerators: + snowflake: + type: SNOWFLAKE + props: + worker-id: 123 +``` + +3. 解压缩 proxy 发布包，修改配置文件 `conf/server.yaml`，这里主要是开启 `scaling` 和 `mode` 配置： +如果配置的Mode是Cluster，需要提前启动对应的配置中心。 Review comment: Every english work between Chinese words should be surounded by blank. It's mostly called `注册中心` in our document, but not `配置中心`. ########## File path: docs/document/content/user-manual/shardingsphere-scaling/usage.cn.md ########## @@ -185,12 +207,25 @@ mysql> show scaling status 660152090995195904; | RUNNING | 运行中 | | EXECUTE_INVENTORY_TASK | 全量迁移中 | | EXECUTE_INCREMENTAL_TASK | 增量迁移中 | -| ALMOST_FINISHED | 基本完成 | -| FINISHED | 已完成 | +| ALMOST_FINISHED | 基本完成(偏内部使用的状态，不用特别在意这个状态。目前的设置逻辑：数据校验完成之后、切换配置之前) | +| FINISHED | 已完成（整个流程完成了，新规则已生效） | | PREPARING_FAILURE | 准备阶段失败 | | EXECUTE_INVENTORY_TASK_FAILURE | 全量迁移阶段失败 | | EXECUTE_INCREMENTAL_TASK_FAILURE | 增量迁移阶段失败 | +如果`status`出现失败的情况，可以查看`Sharding-Proxy`的日志查看错误堆栈分析问题。 Review comment: We could just use `proxy` instead of `Sharding-Proxy`. ########## File path: docs/document/content/user-manual/shardingsphere-scaling/build.cn.md ########## @@ -18,7 +18,61 @@ mvn clean install -Dmaven.javadoc.skip=true -Dcheckstyle.skip=true -Drat.skip=tr 或者通过[下载页面]( https://shardingsphere.apache.org/document/current/cn/downloads/ )获取安装包。 -2. 解压缩 proxy 发布包，修改配置文件 `conf/server.yaml`，这里主要是开启 `scaling` 和 `mode` 配置： +> Scaling还是实验性质的功能，在持续进化中，建议使用master分支最新版本，点击此处[下载最新版本]( http://117.48.121.24:8080/Proxy/ ) Review comment: It's better not put cn community response here. Seems the http url ip is hard-coded. ########## File path: docs/document/content/user-manual/shardingsphere-scaling/usage.cn.md ########## @@ -134,11 +156,11 @@ GENERATED_KEY(COLUMN=order_id,TYPE(NAME=snowflake,PROPERTIES("worker-id"=123))) ); ``` -**注意**：当前版本不支持通过修改`TableRule`触发迁移。 +**注意**：当前版本不支持通过修改`TableRule`触发迁移。对于同一个逻辑表，不能混合使用这2种格式。 #### 查询所有迁移任务 -详情请参见[RAL#弹性伸缩](/cn/user-manual/shardingsphere-proxy/usage/distsql/syntax/ral/ral/#%E5%BC%B9%E6%80%A7%E4%BC%B8%E7%BC%A9)。 +详情请参见[RAL#弹性伸缩](/cn/user-manual/shardingsphere-proxy/usage/distsql/syntax/ral/#弹性伸缩)。 Review comment: It's not recommend to use Chinese word in http url. ########## File path: docs/document/content/user-manual/shardingsphere-scaling/build.cn.md ########## @@ -18,7 +18,61 @@ mvn clean install -Dmaven.javadoc.skip=true -Dcheckstyle.skip=true -Drat.skip=tr 或者通过[下载页面]( https://shardingsphere.apache.org/document/current/cn/downloads/ )获取安装包。 -2. 解压缩 proxy 发布包，修改配置文件 `conf/server.yaml`，这里主要是开启 `scaling` 和 `mode` 配置： +> Scaling还是实验性质的功能，在持续进化中，建议使用master分支最新版本，点击此处[下载最新版本]( http://117.48.121.24:8080/Proxy/ ) + +2. 解压缩 proxy发布包，修改配置文件`conf/sharding.yaml`，配置`schemaName`，`dataSources`，`rules`里的`shardingAlgorithms`和`keyGenerators`，以下示例可供参考： Review comment: Does `conf/sharding.yaml` mean `conf/config-sharding.yaml`? ########## File path: docs/document/content/user-manual/shardingsphere-scaling/build.cn.md ########## @@ -18,7 +18,61 @@ mvn clean install -Dmaven.javadoc.skip=true -Dcheckstyle.skip=true -Drat.skip=tr 或者通过[下载页面]( https://shardingsphere.apache.org/document/current/cn/downloads/ )获取安装包。 -2. 解压缩 proxy 发布包，修改配置文件 `conf/server.yaml`，这里主要是开启 `scaling` 和 `mode` 配置： +> Scaling还是实验性质的功能，在持续进化中，建议使用master分支最新版本，点击此处[下载最新版本]( http://117.48.121.24:8080/Proxy/ ) + +2. 解压缩 proxy发布包，修改配置文件`conf/sharding.yaml`，配置`schemaName`，`dataSources`，`rules`里的`shardingAlgorithms`和`keyGenerators`，以下示例可供参考： +```yaml +schemaName: sharding_db + +dataSources: + ds_0: + url: jdbc:mysql://127.0.0.1:3308/account?serverTimezone=UTC&useSSL=false + username: root + password: root + connectionTimeoutMilliseconds: 30000 + idleTimeoutMilliseconds: 60000 + maxLifetimeMilliseconds: 1800000 + maxPoolSize: 50 + minPoolSize: 1 + +rules: +- !SHARDING + tables: + user: + actualDataNodes: ds_0.user + databaseStrategy: + standard: + shardingColumn: id + shardingAlgorithmName: database_inline + tableStrategy: + standard: + shardingColumn: id + shardingAlgorithmName: user_inline + keyGenerateStrategy: + column: id + keyGeneratorName: snowflake + + shardingAlgorithms: + database_inline: + type: INLINE + props: + algorithm-expression: ds_0 + user_inline: + type: INLINE + props: + algorithm-expression: user_${id % 16} + + keyGenerators: + snowflake: + type: SNOWFLAKE + props: + worker-id: 123 +``` Review comment: Could we just put a relative link here? which explain how to configure`config-sharding.yaml`. ########## File path: docs/document/content/user-manual/shardingsphere-scaling/usage.cn.md ########## @@ -185,12 +207,25 @@ mysql> show scaling status 660152090995195904; | RUNNING | 运行中 | | EXECUTE_INVENTORY_TASK | 全量迁移中 | | EXECUTE_INCREMENTAL_TASK | 增量迁移中 | -| ALMOST_FINISHED | 基本完成 | -| FINISHED | 已完成 | +| ALMOST_FINISHED | 基本完成(偏内部使用的状态，不用特别在意这个状态。目前的设置逻辑：数据校验完成之后、切换配置之前) | +| FINISHED | 已完成（整个流程完成了，新规则已生效） | | PREPARING_FAILURE | 准备阶段失败 | | EXECUTE_INVENTORY_TASK_FAILURE | 全量迁移阶段失败 | | EXECUTE_INCREMENTAL_TASK_FAILURE | 增量迁移阶段失败 | +如果`status`出现失败的情况，可以查看`Sharding-Proxy`的日志查看错误堆栈分析问题。 + + +#### 手动模式 +`Sharding-Scaling`提供了一些命令，可以手动执行。详情可见：[RAL#弹性伸缩](/cn/user-manual/shardingsphere-proxy/distsql/syntax/ral/#弹性伸缩)。 +``` +check scaling {jobId}; +``` + +check和checkout是给手动模式使用的，就是clusterAutoSwitchAlgorithm没配置的情况。并且各自有使用条件。 +check做数据一致性校验，那需要判断全量和增量都完成的情况下执行才有可能校验通过。目前的默认实现是对两端的全量数据进行CRC32计算、然后比对结果 +checkout是让新规则生效，前置步骤没完成是不会执行成功的。 Review comment: It could be put to another paragraph, at the same hierarchy level of auto mode. More DistSQL could be put here to replace spoken words. ########## File path: docs/document/content/user-manual/shardingsphere-scaling/usage.cn.md ########## @@ -110,7 +126,13 @@ ADD RESOURCE ds_2 ( 详情请参见[RDL#数据分片](/cn/user-manual/shardingsphere-proxy/usage/distsql/syntax/rdl/rdl-sharding-rule/)。 -`SHARDING TABLE RULE`支持2种类型：`TableRule`和`AutoTableRule`。对于同一个逻辑表，不能混合使用这2种格式。 +`SHARDING TABLE RULE`支持2种类型：`TableRule`和`AutoTableRule`。对于同一个逻辑表，不能混合使用这2种格式，以下是两种分片规则的对比： +| 名称 | AutoTableRule（自动分片） | TableRule（自定义分片） | +| ------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | +| 定义 | 5.x版本之后，引入的自动分片技术交由 ShardingSphere 自动管理分片，用户只需要指定分片数量和使用的数据源，无需再关心表的具体分布详情可参见：https://shardingsphere.apache.org/document/current/cn/features/sharding/concept/sharding/#自动化分片算法 | 需要自定义分片配置，可设置物理数据节点，数据分片、表分片等 | +| 推荐使用场景 | 不需要关心实际表在哪个库、哪个库有几张表等问题只需考虑：SHARDING_COLUMN：设置用作分片键的列TYPE：设置分片算法和数量GENERATED_KEY：设置分布式自增ID | 需要设置以下参数：DATANODES：物理数据节点表达式DATABASE_STRATEGY：数据库分片策略TABLE_STRATEGY：表分片策略GENERATED_KEY：设置分布式自增ID | +| 示例 | `ALTER SHARDING TABLE RULE t_order ( RESOURCES(ds_2, ds_3, ds_4), SHARDING_COLUMN=order_id, TYPE(NAME=hash_mod,PROPERTIES("sharding-count"=10)), GENERATED_KEY(COLUMN=another_id,TYPE(NAME=snowflake,PROPERTIES("worker-id"=123))) );` | `ALTER SHARDING TABLE RULE t_order ( DATANODES("ds_${2..4}.t_order_${0..1}"), DATABASE_STRATEGY(TYPE=standard,SHARDING_COLUMN=user_id,SHARDING_ALGORITHM=database_inline), TABLE_STRATEGY(TYPE=standard,SHARDING_COLUMN=order_id,SHARDING_ALGORITHM=t_order_inline), GENERATED_KEY(COLUMN=order_id,TYPE(NAME=snowflake,PROPERTIES("worker-id"=123))) );` | Review comment: Could we put relative links here? which will explain `TableRule` and `AutoTableRule`. ########## File path: docs/document/content/user-manual/shardingsphere-scaling/usage.cn.md ########## @@ -185,12 +207,25 @@ mysql> show scaling status 660152090995195904; | RUNNING | 运行中 | | EXECUTE_INVENTORY_TASK | 全量迁移中 | | EXECUTE_INCREMENTAL_TASK | 增量迁移中 | -| ALMOST_FINISHED | 基本完成 | -| FINISHED | 已完成 | +| ALMOST_FINISHED | 基本完成(偏内部使用的状态，不用特别在意这个状态。目前的设置逻辑：数据校验完成之后、切换配置之前) | Review comment: It's not recommend to put spoken words here. If it's hard to understand, we could remove `ALMOST_FINISHED`, it's used internally. ########## File path: docs/document/content/user-manual/shardingsphere-scaling/build.cn.md ########## @@ -50,13 +104,22 @@ mode: 可以通过`ScalingClusterAutoSwitchAlgorithm`接口自定义一个SPI实现，通过`ScalingDataConsistencyCheckAlgorithm`接口自定义一个SPI实现。详情请参见[开发者手册#弹性伸缩](/cn/dev-manual/scaling/)。 +overwrite字段含义为：控制配置文件是否覆盖 zk 元数据，一般可在测试时使用。 Review comment: Not only for zk, could be any registry center. ########## File path: docs/document/content/user-manual/shardingsphere-scaling/build.cn.md ########## @@ -67,8 +130,13 @@ sh bin/start.sh ## 应用配置项 应用现有配置项如下，相应的配置可在 `conf/server.yaml` 中修改： - -| 名称 | 说明 | 默认值 | -| -------------- | -------------------------------------- | ------ | -| blockQueueSize | 数据传输通道队列大小 | 10000 | -| workerThread | 工作线程池大小，允许同时运行的迁移任务线程数 | 40 | +| 一级Key | 二级Key | 三级Key | 说明 | 默认值 | +| ------- | ----------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | --------- | +| Scaling | | blockQueueSize | 数据传输通道队列大小 | 10000 | +| | | workerThread | 工作线程池大小，允许同时运行的迁移任务线程数 | 40 | +| | clusterAutoSwitchAlgorithm | type | 开启自动检测任务是否完成及切换配置，目前系统提供了IDLE类型实现 | - | +| | | props:incremental-task-idle-minute-threshold | 增量同步空闲时间最大值，超过该值，进入下一状态 | 30 (分钟) | +| | dataConsistencyCheckAlgorithm | type | 配置设置数据校验算法，关闭该配置系统将不进行数据校验。目前系统提供了DEFAULT类型实现，DEFAULT算法目前支持的数据库：MySQL。其他数据库还不能打开这个配置项，相关支持还在开发中可以通过ScalingClusterAutoSwitchAlgorithm接口自定义一个SPI实现，通过ScalingDataConsistencyCheckAlgorithm接口自定义一个SPI实现。详情请参见[开发者手册#弹性伸缩](https://shardingsphere.apache.org/document/current/cn/dev-manual/scaling/)。 | - | Review comment: Could we simplify it? It's better to use http relative link. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
