sandynz commented on code in PR #28889: URL: https://github.com/apache/shardingsphere/pull/28889#discussion_r1375641608
########## docs/document/content/user-manual/shardingsphere-proxy/cdc/build.cn.md: ########## @@ -0,0 +1,270 @@ ++++ +title = "运行部署" +weight = 1 ++++ + +## 背景信息 + +ShardingSphere CDC 分为两个部分，一个是 CDC Server，另一个是 CDC Client。 CDC Server 和 ShardingSphere-Proxy 目前是一同部署的。 + +用户可以在自己的项目中引入 CDC Client，实现数据的消费逻辑。 + +## 约束条件 + +- 纯 JAVA 开发，JDK 建议 1.8 或以上版本。 +- CDC Server 要求 SharingSphere-Proxy 使用集群模式，目前支持 ZooKeeper 作为注册中心。 +- CDC 只同步数据，不会同步表结构，目前也不支持 DDL 的语句同步。 +- CDC 增量会按照事务的维度输出数据， 如果要开启 XA 事务的兼容，则 openGauss 和 ShardingSphere-Proxy 都需要 GLT 模块 + +## CDC 功能介绍 + +CDC 服务端的逻辑可以参考 https://github.com/apache/shardingsphere/tree/master/kernel/data-pipeline/scenario/cdc/core 中的实现。 + +### CDC 协议 + +CDC 协议使用 Protobuf，对应的 Protobuf 类型是根据 Java 中的类型来映射的，CDC 的数据类型和 openGauss 之间的映射关系如下 + +CDC 协议的数据类型和 openGauss 之间的映射关系如下 + +| openGauss 类型 | Java 数据类型 | CDC 对应的 protobuf 类型 | 备注 | +|-------------------------------------|--------------------|---------------------|--------------------------| +| INT1、INT2、INT4 | Integer | int32 | | +| INT8 | Long | int64 | | +| NUMERIC | BigDecimal | string | | +| FLOAT4 | Float | float | | +| FLOAT8 | Double | double | | +| BOOLEAN | Boolean | bool | | +| CHAR、VARCHAR、TEXT、CLOB | String | string | | +| BLOB、RAW、BYTEA | byte[] | bytes | | +| DATE | java.util.Date | Timestamp | | +| DATE | java.sql.Date | int64 | 这种情况下返回从1970-01-01 以来的天数 | Review Comment: Could we verify it? Looks DATE will return different types ########## docs/document/content/user-manual/shardingsphere-proxy/cdc/usage.cn.md: ########## @@ -0,0 +1,393 @@ ++++ +title = "使用手册" +weight = 2 ++++ + +## openGauss 使用手册 + +### 环境要求 + +支持的 openGauss 版本：2.x ~ 3.x。 + +### 权限要求 + +1. 调整源端 WAL 配置。 + +`postgresql.conf` 示例配置： +``` +wal_level = logical +max_wal_senders = 10 +max_replication_slots = 10 +wal_sender_timeout = 0 +max_connections = 600 +``` + +详情请参见 [Write Ahead Log](https://docs.opengauss.org/en/docs/2.0.1/docs/Developerguide/settings.html) 和 [Replication](https://docs.opengauss.org/en/docs/2.0.1/docs/Developerguide/sending-server.html)。 + +2. 赋予源端 openGauss 账号 replication 权限。 + +`pg_hba.conf` 示例配置： + +``` +host replication repl_acct 0.0.0.0/0 md5 +# 0.0.0.0/0 表示允许任意 IP 地址访问，可以根据实际情况调整成 CDC Server 的 IP 地址 +``` + +详情请参见 [Configuring Client Access Authentication](https://docs.opengauss.org/en/docs/2.0.1/docs/Developerguide/configuring-client-access-authentication.html) 和 [Example: Logic Replication Code](https://docs.opengauss.org/en/docs/2.0.1/docs/Developerguide/example-logic-replication-code.html)。 + +3. 赋予 openGauss 账号 DDL DML 权限。 + +如果使用非超级管理员账号，要求该账号在用到的数据库上，具备 CREATE 和 CONNECT 的权限。 + +示例： +```sql +GRANT CREATE, CONNECT ON DATABASE source_ds TO cdc_user; +``` + +还需要账号对迁移的表和 schema 具备访问权限，以 test schema 下的 t_order 表为例。 + +```sql +\c source_ds + +GRANT USAGE ON SCHEMA test TO GROUP cdc_user; +GRANT SELECT ON TABLE test.t_order TO cdc_user; +``` + +openGauss 有 OWNER 的概念，如果是数据库，SCHEMA，表的 OWNER，则可以省略对应的授权步骤。 + +openGauss 不允许普通账户在 public schema 下操作。所以如果迁移的表在 public schema 下，需要额外授权。 + +```sql +GRANT ALL PRIVILEGES TO cdc_user; +``` + +详情请参见 [openGauss GRANT](https://docs.opengauss.org/zh/docs/2.0.1/docs/Developerguide/GRANT.html) + + +### 完整流程示例 + +#### 前提条件 + +1. 在 MySQL 已准备好源端库、表、数据。 + +```sql +DROP DATABASE IF EXISTS migration_ds_0; +CREATE DATABASE migration_ds_0 DEFAULT CHARSET utf8; + +USE migration_ds_0; + +CREATE TABLE t_order (order_id INT NOT NULL, user_id INT NOT NULL, status VARCHAR(45) NULL, PRIMARY KEY (order_id)); + +INSERT INTO t_order (order_id, user_id, status) VALUES (1,2,'ok'),(2,4,'ok'),(3,6,'ok'),(4,1,'ok'),(5,3,'ok'),(6,5,'ok'); +``` + +2. 在 MySQL 准备目标端库。 + +```sql +DROP DATABASE IF EXISTS migration_ds_10; +CREATE DATABASE migration_ds_10 DEFAULT CHARSET utf8; + +DROP DATABASE IF EXISTS migration_ds_11; +CREATE DATABASE migration_ds_11 DEFAULT CHARSET utf8; + +DROP DATABASE IF EXISTS migration_ds_12; +CREATE DATABASE migration_ds_12 DEFAULT CHARSET utf8; +``` + +#### 操作步骤 + +1. 在 proxy 新建逻辑数据库并配置好存储单元和规则。 + +```sql +CREATE DATABASE sharding_db; + +USE sharding_db + +REGISTER STORAGE UNIT ds_2 ( + URL="jdbc:mysql://127.0.0.1:3306/migration_ds_10?serverTimezone=UTC&useSSL=false", + USER="root", + PASSWORD="root", + PROPERTIES("minPoolSize"="1","maxPoolSize"="20","idleTimeout"="60000") +), ds_3 ( + URL="jdbc:mysql://127.0.0.1:3306/migration_ds_11?serverTimezone=UTC&useSSL=false", + USER="root", + PASSWORD="root", + PROPERTIES("minPoolSize"="1","maxPoolSize"="20","idleTimeout"="60000") +), ds_4 ( + URL="jdbc:mysql://127.0.0.1:3306/migration_ds_12?serverTimezone=UTC&useSSL=false", + USER="root", + PASSWORD="root", + PROPERTIES("minPoolSize"="1","maxPoolSize"="20","idleTimeout"="60000") +); + +CREATE SHARDING TABLE RULE t_order( +STORAGE_UNITS(ds_2,ds_3,ds_4), +SHARDING_COLUMN=order_id, +TYPE(NAME="hash_mod",PROPERTIES("sharding-count"="6")), +KEY_GENERATE_STRATEGY(COLUMN=order_id,TYPE(NAME="snowflake")) +); +``` + +如果是迁移到异构数据库，那目前需要在 proxy 执行建表语句。 + +2. 在 proxy 配置源端存储单元。 + +```sql +REGISTER MIGRATION SOURCE STORAGE UNIT ds_0 ( + URL="jdbc:mysql://127.0.0.1:3306/migration_ds_0?serverTimezone=UTC&useSSL=false", + USER="root", + PASSWORD="root", + PROPERTIES("minPoolSize"="1","maxPoolSize"="20","idleTimeout"="60000") +); +``` + +3. 启动数据迁移。 + +```sql +MIGRATE TABLE ds_0.t_order INTO t_order; +``` + +或者指定目标端逻辑库： Review Comment: Could we remove unnecessary blocks ########## docs/document/content/user-manual/shardingsphere-proxy/cdc/build.cn.md: ########## @@ -0,0 +1,270 @@ ++++ +title = "运行部署" +weight = 1 ++++ + +## 背景信息 + +ShardingSphere CDC 分为两个部分，一个是 CDC Server，另一个是 CDC Client。 CDC Server 和 ShardingSphere-Proxy 目前是一同部署的。 + +用户可以在自己的项目中引入 CDC Client，实现数据的消费逻辑。 + +## 约束条件 + +- 纯 JAVA 开发，JDK 建议 1.8 或以上版本。 +- CDC Server 要求 SharingSphere-Proxy 使用集群模式，目前支持 ZooKeeper 作为注册中心。 +- CDC 只同步数据，不会同步表结构，目前也不支持 DDL 的语句同步。 +- CDC 增量会按照事务的维度输出数据， 如果要开启 XA 事务的兼容，则 openGauss 和 ShardingSphere-Proxy 都需要 GLT 模块 + +## CDC 功能介绍 + +CDC 服务端的逻辑可以参考 https://github.com/apache/shardingsphere/tree/master/kernel/data-pipeline/scenario/cdc/core 中的实现。 + +### CDC 协议 + +CDC 协议使用 Protobuf，对应的 Protobuf 类型是根据 Java 中的类型来映射的，CDC 的数据类型和 openGauss 之间的映射关系如下 + +CDC 协议的数据类型和 openGauss 之间的映射关系如下 + +| openGauss 类型 | Java 数据类型 | CDC 对应的 protobuf 类型 | 备注 | +|-------------------------------------|--------------------|---------------------|--------------------------| +| INT1、INT2、INT4 | Integer | int32 | | +| INT8 | Long | int64 | | +| NUMERIC | BigDecimal | string | | +| FLOAT4 | Float | float | | +| FLOAT8 | Double | double | | +| BOOLEAN | Boolean | bool | | +| CHAR、VARCHAR、TEXT、CLOB | String | string | | +| BLOB、RAW、BYTEA | byte[] | bytes | | +| DATE | java.util.Date | Timestamp | | +| DATE | java.sql.Date | int64 | 这种情况下返回从1970-01-01 以来的天数 | +| TIMESTAMP，TIMESTAMPTZ、SMALLDATETIME | java.sql.Timestamp | Timestamp | 不带时区信息 | +| TIME，TIMETZ | java.sql.Time | int64 | 代表当天的纳秒数（时区无关） | +| INTERVAL、reltime、abstime | String | string | | +| point、lseg、box、path、polygon、circle | String | string | | +| cidr、inet、macaddr | String | string | | +| tsvector | String | string | | +| UUID | String | string | | +| JSON、JSONB | String | string | | +| HLL | String | string | | +| 范围类型（int4range等） | String | string | | +| HASH16、HASH32 | String | string | | + +> 需要注意对时间类型的处理，为了屏蔽时区的差异，CDC 返回的数据都是时区无关的 + +CDC Server 中 Java 类型转 Protobuf 类型的工具类：ColumnValueConvertUtils，[源码地址](https://github.com/apache/shardingsphere/blob/master/kernel/data-pipeline/scenario/cdc/core/src/main/java/org/apache/shardingsphere/data/pipeline/cdc/util/ColumnValueConvertUtils.java) + +对应的 CDC Client 中有 Protobuf 类型转换成 Java 类型的工具类 ProtobufAnyValueConverter，[源码地址](https://github.com/apache/shardingsphere/blob/master/kernel/data-pipeline/scenario/cdc/client/src/main/java/org/apache/shardingsphere/data/pipeline/cdc/client/util/ProtobufAnyValueConverter.java) + +## CDC Server 部署步骤 + +这里以 openGauss 数据库为例，介绍 CDC Server 的部署步骤。 + +由于 CDC Server 内置于 ShardingSphere-Proxy，所以需要获取 ShardingSphere-Proxy。详情请参见 [proxy 启动手册](/cn/user-manual/shardingsphere-proxy/startup/bin/)。 + +### 配置 GLT 模块（可选） + +官网发布的二进制包默认不包含 GLT 模块，不保证跨库事务完整性，如果使用的是包含 GLT 功能的 openGauss 数据库，则可以额外引入 GLT 模块，保证跨库事务的完整性。 + +目前有两种方式引入 GLT 模块，并且需要在 server.yaml 中也进行相应的配置。 + +#### 1. 源码编译安装 + +1. 准备代码环境，提前下载或者使用 Git clone，从 Github 下载 [ShardingSphere](https://github.com/apache/shardingsphere.git) 源码。 +2. 删除 kernel/global-clock/type/tso/core/pom.xml 中 shardingsphere-global-clock-tso-provider-redis 依赖的 `<scope>provided</scope>` 标签和 kernel/global-clock/type/tso/provider/redis/pom.xml 中 jedis 的 `<scope>provided</scope>` 标签 +3. 编译 ShardingSphere-Proxy，具体编译步骤请参考 [ShardingSphere 编译手册](https://github.com/apache/shardingsphere/wiki#build-apache-shardingsphere)。 + +#### 2. 直接引入 GLT 依赖 + +可以从 maven 仓库中引入 + +1. [shardingsphere-global-clock-tso-provider-redis](https://mvnrepository.com/artifact/io.github.greycode/shardingsphere-global-clock-tso-provider-redis)，需要和 ShardingSphere-Proxy 版本一致 +2. [jedis](https://mvnrepository.com/artifact/redis.clients/jedis), 推荐使用 4.3.1 版本 Review Comment: Could we use Maven official url? ########## docs/document/content/user-manual/shardingsphere-proxy/cdc/build.cn.md: ########## @@ -0,0 +1,270 @@ ++++ +title = "运行部署" +weight = 1 ++++ + +## 背景信息 + +ShardingSphere CDC 分为两个部分，一个是 CDC Server，另一个是 CDC Client。 CDC Server 和 ShardingSphere-Proxy 目前是一同部署的。 + +用户可以在自己的项目中引入 CDC Client，实现数据的消费逻辑。 + +## 约束条件 + +- 纯 JAVA 开发，JDK 建议 1.8 或以上版本。 +- CDC Server 要求 SharingSphere-Proxy 使用集群模式，目前支持 ZooKeeper 作为注册中心。 +- CDC 只同步数据，不会同步表结构，目前也不支持 DDL 的语句同步。 +- CDC 增量会按照事务的维度输出数据， 如果要开启 XA 事务的兼容，则 openGauss 和 ShardingSphere-Proxy 都需要 GLT 模块 + +## CDC 功能介绍 + +CDC 服务端的逻辑可以参考 https://github.com/apache/shardingsphere/tree/master/kernel/data-pipeline/scenario/cdc/core 中的实现。 + +### CDC 协议 + +CDC 协议使用 Protobuf，对应的 Protobuf 类型是根据 Java 中的类型来映射的，CDC 的数据类型和 openGauss 之间的映射关系如下 + +CDC 协议的数据类型和 openGauss 之间的映射关系如下 + +| openGauss 类型 | Java 数据类型 | CDC 对应的 protobuf 类型 | 备注 | +|-------------------------------------|--------------------|---------------------|--------------------------| +| INT1、INT2、INT4 | Integer | int32 | | +| INT8 | Long | int64 | | +| NUMERIC | BigDecimal | string | | +| FLOAT4 | Float | float | | +| FLOAT8 | Double | double | | +| BOOLEAN | Boolean | bool | | +| CHAR、VARCHAR、TEXT、CLOB | String | string | | +| BLOB、RAW、BYTEA | byte[] | bytes | | +| DATE | java.util.Date | Timestamp | | +| DATE | java.sql.Date | int64 | 这种情况下返回从1970-01-01 以来的天数 | +| TIMESTAMP，TIMESTAMPTZ、SMALLDATETIME | java.sql.Timestamp | Timestamp | 不带时区信息 | +| TIME，TIMETZ | java.sql.Time | int64 | 代表当天的纳秒数（时区无关） | +| INTERVAL、reltime、abstime | String | string | | +| point、lseg、box、path、polygon、circle | String | string | | +| cidr、inet、macaddr | String | string | | +| tsvector | String | string | | +| UUID | String | string | | +| JSON、JSONB | String | string | | +| HLL | String | string | | +| 范围类型（int4range等） | String | string | | +| HASH16、HASH32 | String | string | | + +> 需要注意对时间类型的处理，为了屏蔽时区的差异，CDC 返回的数据都是时区无关的 + +CDC Server 中 Java 类型转 Protobuf 类型的工具类：ColumnValueConvertUtils，[源码地址](https://github.com/apache/shardingsphere/blob/master/kernel/data-pipeline/scenario/cdc/core/src/main/java/org/apache/shardingsphere/data/pipeline/cdc/util/ColumnValueConvertUtils.java) + +对应的 CDC Client 中有 Protobuf 类型转换成 Java 类型的工具类 ProtobufAnyValueConverter，[源码地址](https://github.com/apache/shardingsphere/blob/master/kernel/data-pipeline/scenario/cdc/client/src/main/java/org/apache/shardingsphere/data/pipeline/cdc/client/util/ProtobufAnyValueConverter.java) + +## CDC Server 部署步骤 + +这里以 openGauss 数据库为例，介绍 CDC Server 的部署步骤。 + +由于 CDC Server 内置于 ShardingSphere-Proxy，所以需要获取 ShardingSphere-Proxy。详情请参见 [proxy 启动手册](/cn/user-manual/shardingsphere-proxy/startup/bin/)。 + +### 配置 GLT 模块（可选） + +官网发布的二进制包默认不包含 GLT 模块，不保证跨库事务完整性，如果使用的是包含 GLT 功能的 openGauss 数据库，则可以额外引入 GLT 模块，保证跨库事务的完整性。 + +目前有两种方式引入 GLT 模块，并且需要在 server.yaml 中也进行相应的配置。 + +#### 1. 源码编译安装 + +1. 准备代码环境，提前下载或者使用 Git clone，从 Github 下载 [ShardingSphere](https://github.com/apache/shardingsphere.git) 源码。 +2. 删除 kernel/global-clock/type/tso/core/pom.xml 中 shardingsphere-global-clock-tso-provider-redis 依赖的 `<scope>provided</scope>` 标签和 kernel/global-clock/type/tso/provider/redis/pom.xml 中 jedis 的 `<scope>provided</scope>` 标签 +3. 编译 ShardingSphere-Proxy，具体编译步骤请参考 [ShardingSphere 编译手册](https://github.com/apache/shardingsphere/wiki#build-apache-shardingsphere)。 + +#### 2. 直接引入 GLT 依赖 + +可以从 maven 仓库中引入 + +1. [shardingsphere-global-clock-tso-provider-redis](https://mvnrepository.com/artifact/io.github.greycode/shardingsphere-global-clock-tso-provider-redis)，需要和 ShardingSphere-Proxy 版本一致 +2. [jedis](https://mvnrepository.com/artifact/redis.clients/jedis), 推荐使用 4.3.1 版本 + +### CDC Server 使用手册 + +1. 修改配置文件 `conf/server.yaml`，打开 CDC 功能。 目前 `mode` 必须是 `Cluster`，需要提前启动对应的注册中心。如果 GLT provider 使用 Redis，需要提前启动 Redis。 + +配置示例： + +```yaml +mode: + type: Cluster + repository: + type: ZooKeeper + props: + namespace: open_cdc + server-lists: localhost:2181 + retryIntervalMilliseconds: 500 + timeToLiveSeconds: 60 + maxRetries: 3 + operationTimeoutMilliseconds: 500 + +authority: + users: + # 这里的用户名和密码在 CDC Client 的认证中也会用到 + - user: root@% + password: root + - user: proxy + password: Proxy@123 + privilege: + type: ALL_PERMITTED + +# 开启 GLT 的时候也需要打开分布式事务 +#transaction: +# defaultType: XA +# providerType: Atomikos + +# GLT 模块配置，如果不需要 GLT 模块，可以不配置 +#globalClock: +# enabled: true +# type: TSO +# provider: redis +# props: +# host: 127.0.0.1 +# port: 6379 + + +props: + cdc-server-port: 33071 # CDC Server 端口，必须配置 + proxy-frontend-database-protocol-type: openGauss + # 省略其他配置 + ...... +``` + +2. 引入 JDBC 驱动。 + +proxy 已包含 PostgreSQL JDBC 驱动。 + +如果后端连接以下数据库，请下载相应 JDBC 驱动 jar 包，并将其放入 `${shardingsphere-proxy}/ext-lib` 目录。 + +| 数据库 | JDBC 驱动 | 参考 | +|-----------|---------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------| +| MySQL | [mysql-connector-java-5.1.49.jar]( https://repo1.maven.org/maven2/mysql/mysql-connector-java/5.1.49/mysql-connector-java-5.1.49.jar ) | [Connector/J Versions]( https://dev.mysql.com/doc/connector-j/5.1/en/connector-j-versions.html ) | Review Comment: Could we update table with latest content? And also update mysql connector java version to 8.x ########## docs/document/content/user-manual/shardingsphere-proxy/cdc/build.cn.md: ########## @@ -0,0 +1,270 @@ ++++ +title = "运行部署" +weight = 1 ++++ + +## 背景信息 + +ShardingSphere CDC 分为两个部分，一个是 CDC Server，另一个是 CDC Client。 CDC Server 和 ShardingSphere-Proxy 目前是一同部署的。 + +用户可以在自己的项目中引入 CDC Client，实现数据的消费逻辑。 + +## 约束条件 + +- 纯 JAVA 开发，JDK 建议 1.8 或以上版本。 +- CDC Server 要求 SharingSphere-Proxy 使用集群模式，目前支持 ZooKeeper 作为注册中心。 +- CDC 只同步数据，不会同步表结构，目前也不支持 DDL 的语句同步。 +- CDC 增量会按照事务的维度输出数据， 如果要开启 XA 事务的兼容，则 openGauss 和 ShardingSphere-Proxy 都需要 GLT 模块 + +## CDC 功能介绍 + +CDC 服务端的逻辑可以参考 https://github.com/apache/shardingsphere/tree/master/kernel/data-pipeline/scenario/cdc/core 中的实现。 + +### CDC 协议 + +CDC 协议使用 Protobuf，对应的 Protobuf 类型是根据 Java 中的类型来映射的，CDC 的数据类型和 openGauss 之间的映射关系如下 + +CDC 协议的数据类型和 openGauss 之间的映射关系如下 + +| openGauss 类型 | Java 数据类型 | CDC 对应的 protobuf 类型 | 备注 | +|-------------------------------------|--------------------|---------------------|--------------------------| +| INT1、INT2、INT4 | Integer | int32 | | +| INT8 | Long | int64 | | Review Comment: Looks it could be put in usage doc of CDC client -- 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]
