[shardingsphere] branch master updated: Add Scaling IT docs (#18524)

[zh...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

zhonghongsheng 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 51bc0781c0e Add Scaling IT docs (#18524)
51bc0781c0e is described below

commit 51bc0781c0e12b51830e508a07265209dec3f975
Author: azexcy <10...@users.noreply.github.com>
AuthorDate: Thu Jun 23 11:51:05 2022 +0800

    Add Scaling IT docs (#18524)
    
    * Add Scaling IT docs
    
    * Update codestyles
---
 .../test/scaling-integration-test/_index.cn.md     | 95 ++++++++++++++++++++++
 .../test/scaling-integration-test/_index.en.md     | 94 +++++++++++++++++++++
 2 files changed, 189 insertions(+)

diff --git a/docs/document/content/reference/test/scaling-integration-test/_index.cn.md b/docs/document/content/reference/test/scaling-integration-test/_index.cn.md
new file mode 100644
index 00000000000..2a3065bfb4b
--- /dev/null
+++ b/docs/document/content/reference/test/scaling-integration-test/_index.cn.md
@@ -0,0 +1,95 @@
++++
+title = "Scaling 集成测试"
+weight = 4
++++
+
+## 测试目的
+
+验证 Scaling 自身功能和依赖模块的正确性。
+
+## 测试环境
+
+环境准备方式分为 Native 和 Docker，不论哪种环境，本地都需要预先安装Docker。
+
+- Native 环境 用于本地调试，可以使用 IDE 的 debug 模式进行调试。
+- Docker 环境  环境由 Maven 运行，适用于云编译环境和测试 ShardingSphere-Proxy 的场景，如：GitHub Action。
+
+当前默认采用 Docker 环境，涉及到的 ShardingSphere-Proxy， Zookeeper， 数据库实例(MySQL，PostgreSQL)， 都通过Docker自动启动。
+
+数据库类型目前支持 MySQL、PostgreSQL、openGauss。
+
+## 使用指南
+
+模块路径：`shardingsphere-test/shardingsphere-integration-test/shardingsphere-integration-test-scaling`
+
+测试的Class分布如下：
+
+核心用例：
+- MySQLGeneralScalingIT: 覆盖的测试场景最多，包括部分表迁移，表字段最多样等。
+- PostgreSQLGeneralScalingIT: 类似，只不过数据库类型是 PostgreSQL/openGauss，包含自定义schema迁移场景。
+
+主键用例：
+
+- TextPrimaryKeyScalingIT: 支持主键为文本类型的表迁移。
+
+
+### 配置文件
+
+目录：`resources/env/`
+- /common: 存放scaling过程中用到的 DistSQL。
+- /{SQL-TYPE}: 存放数据库级别的配置文件。
+- /scenario: 存放测试的场景的配置文件，主要是 SQL，不同数据库可能写法不一样。
+
+### 运行测试引擎
+
+所有的属性值都可以通过 Maven 命令行 `-D` 的方式动态注入。
+
+`${image-name}` 表示合法 docker image 名称，比如：mysql:5.7， 多个的话用逗号隔开。
+`-Dit.env.postgresql.version=${image-name}` 表示需要测试的 PostgreSQL 版本。
+`-Dit.env.mysql.version=${image-name}` 表示需要测试的 MySQL 版本。
+
+#### Native 环境启动
+
+Native 环境要求本地自行启动 ShardingSphere-Proxy（以及其自身依赖的 Cluster，比如 Zookeeper），同时要求 ShardingSphere-Proxy 的端口是3307，数据库会根据用户的配置自行启动，但是对应的端口都是数据库的默认端口（MySQL=3306，PostgreSQL=5432）。
+
+因此 Native 模式下不支持运行多个 Case，每次跑完需要自行清理 Zookeeper 中的信息，以及重启 ShardingSphere-Proxy。
+
+启动方式如下: 找到需要测试的 Case，比如 MySQLGeneralScalingIT， 在启动之前配置对应的 VM Option，新增如下配置。
+
+```
+-Dit.cluster.env.type=native -Dit.env.mysql.version=${image-name}
+```
+
+在 IDE 下使用 Junit 的方式启动即可。
+
+#### Docker 环境启动
+
+第一步：打包镜像
+
+```bash
+./mvnw -B clean install -am -pl shardingsphere-test/shardingsphere-integration-test/shardingsphere-integration-test-scaling -Pit.env.docker -DskipTests
+```
+
+运行以上命令会构建出一个用于集成测试的 Docker 镜像 `apache/shardingsphere-proxy-test:latest`。
+如果仅修改了测试代码，可以复用已有的测试镜像，无须重新构建。
+
+**Docker 环境配置为 ShardingSphere-Proxy 提供了远程调试端口，默认是3308。**
+可以在 ShardingSphereProxyDockerContainer 中自行修改。
+
+#### 运行用例
+
+和 Native 一样，只需要改一个参数。
+
+```
+-Dit.cluster.env.type=docker
+```
+
+可以和 Native 一样使用 IDE 的方式运行用例，或者使用 maven 的方式运行用例。
+
+```bash
+./mvnw -nsu -B install -f shardingsphere-test/shardingsphere-integration-test/shardingsphere-integration-test-scaling/pom.xml -Dit.cluster.env.type=DOCKER -Dit.env.mysql.version=${image-name}
+```
+
+#### 注意事项
+
+Scaling集成测试中的命令基本都是只连接 ShardingSphere-Proxy 中执行的，所以如果运行失败，多数情况是需要对 ShardingSphere-Proxy 进行Debug，日志中带有 `:Scaling-Proxy `前缀的，都是从 ShardingSphere-Proxy 容器中输出的日志。
diff --git a/docs/document/content/reference/test/scaling-integration-test/_index.en.md b/docs/document/content/reference/test/scaling-integration-test/_index.en.md
new file mode 100644
index 00000000000..4a74bfb2ada
--- /dev/null
+++ b/docs/document/content/reference/test/scaling-integration-test/_index.en.md
@@ -0,0 +1,94 @@
++++
+title = "Scaling Integration Test"
+weight = 4
++++
+
+## Objective
+
+Verify the correctness of Scaling's own functionality and dependent modules.
+
+## Environment
+
+There are two types of environment preparation: Native and Docker, either of which requires Docker to be pre-installed locally.
+
+- Native Environment: For local debugging, you can use the IDE's debug mode for debugging
+- Docker Environment: Environment run by Maven for cloud compiled environments and testing ShardingSphere-Proxy scenarios, e.g. GitHub Action
+
+The current default Docker environment, involving ShardingSphere-Proxy, Zookeeper, database instances (MySQL, PostgreSQL), are automatically started via Docker.
+
+Database type currently supports MySQL, PostgreSQL, openGauss
+
+## Guide
+
+Module path: `shardingsphere-test/shardingsphere-integration-test/shardingsphere-integration-test-scaling`
+
+The Class distribution of the test is as follows.
+
+Core Case：
+- MySQLGeneralScalingIT: Covered the most test scenarios, including part of the table migration, most variety of table fields, etc.
+- PostgreSQLGeneralScalingIT: Similar, except that the database type is PostgreSQL/openGauss and includes custom schema migration scenarios.
+
+Primary Key Case：
+
+- TextPrimaryKeyScalingIT: Support migration of tables with primary key of text type(e.g. UUID).
+
+### Configuration File
+
+Catalog：`resources/env/`
+- /common: The Dist SQL used in the scaling process.
+- /{SQL-TYPE}: database-level configuration files.
+- /scenario: The configuration file for the test scenario, mainly SQL, may be written differently for different databases.
+
+### Run Test Cases
+
+All property values can be dynamically injected by means of the Maven command line `-D`.
+
+`${image-name}` Indicates a legal docker image name, e.g., mysql:5.7, separated by commas if multiple.
+`-Dit.env.postgresql.version=${image-name}` Indicates the version of PostgreSQL that needs to be tested.
+`-Dit.env.mysql.version=${image-name}` Indicates the version of MySQL that needs to be tested.
+
+#### Native Environment Startup
+
+Native environments require that ShardingSphere-Proxy (and its own dependent Cluster, such as Zookeeper) be started locally, and that ShardingSphere-Proxy be started on port 3307, while the database will be started according to the user's configuration, but the corresponding ports are the default ports for the database (MySQL=3306, PostgreSQL=5432).
+
+Therefore, Native mode does not support running multiple cases, and you need to clean up the information in Zookeeper and restart ShardingSphere-Proxy after each run.
+
+The startup method is as follows: Find the Case you need to test, such as MySQLGeneralScalingIT, and configure the corresponding VM Option before startup, add the following configuration.
+
+```
+-Dit.cluster.env.type=native -Dit.env.mysql.version=${image-name}
+```
+
+Just start it under the IDE using the Junit.
+
+#### Docker Environment Startup
+
+Step 1: Packaging Image
+
+```bash
+./mvnw -B clean install -am -pl shardingsphere-test/shardingsphere-integration-test/shardingsphere-integration-test-scaling -Pit.env.docker -DskipTests
+```
+
+Running the above command will build a Docker image `apache/shardingsphere-proxy-test:latest` for integration testing.
+If you have only modified the test code, you can reuse the existing test image without rebuilding it.
+
+**Docker environment configuration provides remote debugging port for ShardingSphere-Proxy, the default is 3308.**
+You can change it yourself in ShardingSphereProxyDockerContainer.
+
+#### Running Case
+
+As with Native, only one parameter needs to be changed.
+
+```
+-Dit.cluster.env.type=docker
+```
+
+You can run the use case using the same IDE as Native, or you can run it using maven.
+
+```shell
+./mvnw -nsu -B install -f shardingsphere-test/shardingsphere-integration-test/shardingsphere-integration-test-scaling/pom.xml -Dit.cluster.env.type=DOCKER -Dit.env.mysql.version=${image-name}
+```
+
+#### Attentions
+
+The commands in the Scaling integration test are basically executed in the ShardingSphere-Proxy, so if they fail, most of them require a debug of the ShardingSphere-Proxy, and the logs with the `:Scaling-Proxy ` prefix are from the The logs with the prefix `:Scaling-Proxy` are the logs output from the ShardingSphere-Proxy container.
\ No newline at end of file