sandynz commented on code in PR #28889: URL: https://github.com/apache/shardingsphere/pull/28889#discussion_r1381190686
########## docs/document/content/user-manual/shardingsphere-proxy/cdc/build.cn.md: ########## @@ -0,0 +1,160 @@ ++++ +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 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://repo1.maven.org/maven2/org/apache/shardingsphere/shardingsphere-global-clock-tso-provider-redis)，下载和 ShardingSphere-Proxy 同名版本 +2. [jedis-4.3.1](https://repo1.maven.org/maven2/redis/clients/jedis/4.3.1/jedis-4.3.1.jar) + +### 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-8.0.11.jar]( https://repo1.maven.org/maven2/mysql/mysql-connector-java/5.1.49/mysql-connector-java-5.1.49.jar ) | [Connector/J Versions]( https://repo1.maven.org/maven2/mysql/mysql-connector-java/8.0.11/mysql-connector-java-8.0.11.jar ) | +| openGauss | [opengauss-jdbc-3.1.1-og.jar]( https://repo1.maven.org/maven2/org/opengauss/opengauss-jdbc/3.1.1-og/opengauss-jdbc-3.1.1-og.jar ) | | + +4. 启动 ShardingSphere-Proxy： + +``` +sh bin/start.sh +``` + +5. 查看 proxy 日志 `logs/stdout.log`，看到日志中出现： + +``` +[INFO ] [main] o.a.s.p.frontend.ShardingSphereProxy - ShardingSphere-Proxy Cluster mode started successfully +``` + +确认启动成功。 + +## CDC Client 使用手册 + +用户可以通过 CDC Client 和服务端进行交互，CDC Client 的依赖很轻，只包含 netty 以及 CDC 协议相关的依赖。 + +有两种方式可以引入 CDC Client + +1. 源码编译，CDC Client 在编译 Proxy 的时候会一同编译，在 kernel/data-pipeline/scenario/cdc/client/target 目录下可以找到编译后的 jar 文件 +2. 从 maven 仓库获取，[Shardingsphere Data Pipeline CDC Client](https://mvnrepository.com/artifact/io.github.greycode/shardingsphere-data-pipeline-cdc-client) + +### CDC Client 介绍 + +`org.apache.shardingsphere.data.pipeline.cdc.client.CDCClient` 是 CDC Client 的入口类，用户可以通过该类和 CDC Server 进行交互。主要的和新方法如下。 + +| 方法名 | 返回值 | 说明 | +|----------------------------------------------------| --- | --- | +| await() | void | 阻塞 CDC 线程，await channel 关闭 | +| close() | void | 关闭 channel | +| connect() | void | 和服务端进行连接 | +| login (CDCLoginParameter parameter) | void | 登陆验证 | +| startStreaming (StartStreamingParameter parameter) | java.lang.String （CDC 任务唯一标识） | 开启 CDC 订阅 | +| restartStreaming (java.lang.String streamingId) | void | 重启订阅 | +| stopStreaming (java.lang.String streamingId) | void | 停止订阅 | + + +### CDC Client 使用示例 + +目前 CDC Client 只提供了 Java API，用户需要自行实现数据的消费逻辑。 + +1. 引入 CDC Client + +```xml +<dependency> + <groupId>io.github.greycode</groupId> + <artifactId>shardingsphere-data-pipeline-cdc-client</artifactId> Review Comment: groupId and artifactId is not correct ########## docs/document/content/user-manual/shardingsphere-proxy/cdc/usage.cn.md: ########## @@ -0,0 +1,322 @@ ++++ +title = "使用手册" +weight = 2 ++++ + +## CDC 功能介绍 + +### CDC 协议介绍 + +CDC 协议使用 Protobuf，对应的 Protobuf 类型是根据 Java 中的类型来映射的。 + +这里以 openGauss 为例，CDC 协议的数据类型和数据库类型的映射关系如下 + +| 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、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 返回的数据都是时区无关的 + +## 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. 准备好 CDC 源端的库、表、数据。 + +```sql +DROP DATABASE IF EXISTS ds_0; +CREATE DATABASE ds_0; + +DROP DATABASE IF EXISTS ds_1; +CREATE DATABASE ds_1; +``` + +#### 操作步骤 + +1. 在 `server.yaml` 中开启 CDC 功能。 + +```yaml +mode: + type: Cluster + repository: + type: ZooKeeper + props: + namespace: cdc + server-lists: localhost:2181 + retryIntervalMilliseconds: 500 + timeToLiveSeconds: 60 + maxRetries: 3 + operationTimeoutMilliseconds: 500 + +authority: + users: + - user: root@% + password: root + privilege: + type: ALL_PERMITTED + +#开启 GLT 功能参考 CDC 部署手册 +#transaction: +# defaultType: XA +# providerType: Atomikos +# +#globalClock: +# enabled: true +# type: TSO +# provider: redis +# props: +# host: 127.0.0.1 +# port: 6379 + +props: + system-log-level: INFO + check-table-metadata-enabled: false + proxy-default-port: 3307 # Proxy default port. + cdc-server-port: 33071 # CDC server port + proxy-frontend-database-protocol-type: openGauss +``` + +2. 在 proxy 新建逻辑数据库并配置好存储单元和规则。 + +2.1. 创建逻辑库。 + +```sql +CREATE DATABASE sharding_db; + +\c sharding_db +``` +2.2. 注册存储单元。 + +```sql +REGISTER STORAGE UNIT ds_0 ( + URL="jdbc:opengauss://127.0.0.1:5432/ds_0", + USER="gaussdb", + PASSWORD="Root@123", + PROPERTIES("minPoolSize"="1","maxPoolSize"="20","idleTimeout"="60000") +), ds_1 ( + URL="jdbc:opengauss://127.0.0.1:5432/ds_1", + USER="gaussdb", + PASSWORD="Root@123", + PROPERTIES("minPoolSize"="1","maxPoolSize"="20","idleTimeout"="60000") +); +``` + +2.3. 创建分片规则。 + +```sql +CREATE SHARDING TABLE RULE t_order( +STORAGE_UNITS(ds_0,ds_1), +SHARDING_COLUMN=order_id, +TYPE(NAME="hash_mod",PROPERTIES("sharding-count"="2")), +KEY_GENERATE_STRATEGY(COLUMN=order_id,TYPE(NAME="snowflake")) +); +``` + +2.4. 创建表和初始化数据 + +在 proxy 执行建表语句。 + +```sql +CREATE TABLE t_order (id INT NOT NULL, user_id INT NOT NULL, status VARCHAR(45) NULL, PRIMARY KEY (id)); + +INSERT INTO t_order (id, user_id, status) VALUES (1,1,'ok1'),(2,2,'ok2'),(3,3,'ok3'); +``` + +3. 启动 CDC Client + +先引入 CDC Client 依赖，在代码 + +这里先介绍下 `CDCClientConfiguration` 参数，构造 CDCClient 的时候需要传入该参数，该参数包含了 CDC Server 的地址，端口，以及 CDC 数据的消费逻辑。 + +```java +@RequiredArgsConstructor +@Getter +public final class CDCClientConfiguration { Review Comment: Could we move these blocks to end of steps ########## docs/document/content/user-manual/shardingsphere-proxy/cdc/build.cn.md: ########## @@ -0,0 +1,160 @@ ++++ +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 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://repo1.maven.org/maven2/org/apache/shardingsphere/shardingsphere-global-clock-tso-provider-redis)，下载和 ShardingSphere-Proxy 同名版本 +2. [jedis-4.3.1](https://repo1.maven.org/maven2/redis/clients/jedis/4.3.1/jedis-4.3.1.jar) + +### 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-8.0.11.jar]( https://repo1.maven.org/maven2/mysql/mysql-connector-java/5.1.49/mysql-connector-java-5.1.49.jar ) | [Connector/J Versions]( https://repo1.maven.org/maven2/mysql/mysql-connector-java/8.0.11/mysql-connector-java-8.0.11.jar ) | +| openGauss | [opengauss-jdbc-3.1.1-og.jar]( https://repo1.maven.org/maven2/org/opengauss/opengauss-jdbc/3.1.1-og/opengauss-jdbc-3.1.1-og.jar ) | | + +4. 启动 ShardingSphere-Proxy： + +``` +sh bin/start.sh +``` + +5. 查看 proxy 日志 `logs/stdout.log`，看到日志中出现： + +``` +[INFO ] [main] o.a.s.p.frontend.ShardingSphereProxy - ShardingSphere-Proxy Cluster mode started successfully +``` + +确认启动成功。 + +## CDC Client 使用手册 + +用户可以通过 CDC Client 和服务端进行交互，CDC Client 的依赖很轻，只包含 netty 以及 CDC 协议相关的依赖。 + +有两种方式可以引入 CDC Client + +1. 源码编译，CDC Client 在编译 Proxy 的时候会一同编译，在 kernel/data-pipeline/scenario/cdc/client/target 目录下可以找到编译后的 jar 文件 +2. 从 maven 仓库获取，[Shardingsphere Data Pipeline CDC Client](https://mvnrepository.com/artifact/io.github.greycode/shardingsphere-data-pipeline-cdc-client) + +### CDC Client 介绍 + +`org.apache.shardingsphere.data.pipeline.cdc.client.CDCClient` 是 CDC Client 的入口类，用户可以通过该类和 CDC Server 进行交互。主要的和新方法如下。 + +| 方法名 | 返回值 | 说明 | +|----------------------------------------------------| --- | --- | +| await() | void | 阻塞 CDC 线程，await channel 关闭 | +| close() | void | 关闭 channel | +| connect() | void | 和服务端进行连接 | +| login (CDCLoginParameter parameter) | void | 登陆验证 | +| startStreaming (StartStreamingParameter parameter) | java.lang.String （CDC 任务唯一标识） | 开启 CDC 订阅 | +| restartStreaming (java.lang.String streamingId) | void | 重启订阅 | +| stopStreaming (java.lang.String streamingId) | void | 停止订阅 | + + +### CDC Client 使用示例 + +目前 CDC Client 只提供了 Java API，用户需要自行实现数据的消费逻辑。 + +1. 引入 CDC Client + +```xml +<dependency> + <groupId>io.github.greycode</groupId> + <artifactId>shardingsphere-data-pipeline-cdc-client</artifactId> + <version>${version}</version> +</dependency> +``` + +2. 启动 CDC Client + +参考 [Example](https://github.com/apache/shardingsphere/blob/master/kernel/data-pipeline/scenario/cdc/client/src/test/java/org/apache/shardingsphere/data/pipeline/cdc/client/example/Bootstrap.java) 启动 CDC Client。 Review Comment: Could we move CDC Client steps to usage document? Since if proxy server in usage document does not start, users could not start CDC Client. ########## docs/document/content/user-manual/shardingsphere-proxy/cdc/usage.en.md: ########## @@ -0,0 +1,6 @@ ++++ +title = "Manual" +weight = 2 ++++ + +TODO Review Comment: Fix TODOs ########## docs/document/content/user-manual/shardingsphere-proxy/cdc/build.cn.md: ########## @@ -0,0 +1,160 @@ ++++ +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 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://repo1.maven.org/maven2/org/apache/shardingsphere/shardingsphere-global-clock-tso-provider-redis)，下载和 ShardingSphere-Proxy 同名版本 +2. [jedis-4.3.1](https://repo1.maven.org/maven2/redis/clients/jedis/4.3.1/jedis-4.3.1.jar) + +### 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-8.0.11.jar]( https://repo1.maven.org/maven2/mysql/mysql-connector-java/5.1.49/mysql-connector-java-5.1.49.jar ) | [Connector/J Versions]( https://repo1.maven.org/maven2/mysql/mysql-connector-java/8.0.11/mysql-connector-java-8.0.11.jar ) | +| openGauss | [opengauss-jdbc-3.1.1-og.jar]( https://repo1.maven.org/maven2/org/opengauss/opengauss-jdbc/3.1.1-og/opengauss-jdbc-3.1.1-og.jar ) | | + +4. 启动 ShardingSphere-Proxy： + +``` +sh bin/start.sh +``` + +5. 查看 proxy 日志 `logs/stdout.log`，看到日志中出现： + +``` +[INFO ] [main] o.a.s.p.frontend.ShardingSphereProxy - ShardingSphere-Proxy Cluster mode started successfully +``` + +确认启动成功。 + +## CDC Client 使用手册 + +用户可以通过 CDC Client 和服务端进行交互，CDC Client 的依赖很轻，只包含 netty 以及 CDC 协议相关的依赖。 + +有两种方式可以引入 CDC Client + +1. 源码编译，CDC Client 在编译 Proxy 的时候会一同编译，在 kernel/data-pipeline/scenario/cdc/client/target 目录下可以找到编译后的 jar 文件 +2. 从 maven 仓库获取，[Shardingsphere Data Pipeline CDC Client](https://mvnrepository.com/artifact/io.github.greycode/shardingsphere-data-pipeline-cdc-client) Review Comment: CDC Client url should be updated to official Maven repository. ########## docs/document/content/user-manual/shardingsphere-proxy/cdc/build.cn.md: ########## @@ -0,0 +1,160 @@ ++++ +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 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://repo1.maven.org/maven2/org/apache/shardingsphere/shardingsphere-global-clock-tso-provider-redis)，下载和 ShardingSphere-Proxy 同名版本 +2. [jedis-4.3.1](https://repo1.maven.org/maven2/redis/clients/jedis/4.3.1/jedis-4.3.1.jar) + +### 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-8.0.11.jar]( https://repo1.maven.org/maven2/mysql/mysql-connector-java/5.1.49/mysql-connector-java-5.1.49.jar ) | [Connector/J Versions]( https://repo1.maven.org/maven2/mysql/mysql-connector-java/8.0.11/mysql-connector-java-8.0.11.jar ) | +| openGauss | [opengauss-jdbc-3.1.1-og.jar]( https://repo1.maven.org/maven2/org/opengauss/opengauss-jdbc/3.1.1-og/opengauss-jdbc-3.1.1-og.jar ) | | + +4. 启动 ShardingSphere-Proxy： + +``` +sh bin/start.sh +``` + +5. 查看 proxy 日志 `logs/stdout.log`，看到日志中出现： + +``` +[INFO ] [main] o.a.s.p.frontend.ShardingSphereProxy - ShardingSphere-Proxy Cluster mode started successfully +``` + +确认启动成功。 + +## CDC Client 使用手册 + +用户可以通过 CDC Client 和服务端进行交互，CDC Client 的依赖很轻，只包含 netty 以及 CDC 协议相关的依赖。 + +有两种方式可以引入 CDC Client + +1. 源码编译，CDC Client 在编译 Proxy 的时候会一同编译，在 kernel/data-pipeline/scenario/cdc/client/target 目录下可以找到编译后的 jar 文件 +2. 从 maven 仓库获取，[Shardingsphere Data Pipeline CDC Client](https://mvnrepository.com/artifact/io.github.greycode/shardingsphere-data-pipeline-cdc-client) Review Comment: It's better to use Maven dependency, but not download jar manually. ########## docs/document/content/user-manual/shardingsphere-proxy/cdc/usage.cn.md: ########## @@ -0,0 +1,322 @@ ++++ +title = "使用手册" +weight = 2 ++++ + +## CDC 功能介绍 + +### CDC 协议介绍 + +CDC 协议使用 Protobuf，对应的 Protobuf 类型是根据 Java 中的类型来映射的。 + +这里以 openGauss 为例，CDC 协议的数据类型和数据库类型的映射关系如下 + +| 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、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 返回的数据都是时区无关的 + +## 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. 准备好 CDC 源端的库、表、数据。 + +```sql +DROP DATABASE IF EXISTS ds_0; +CREATE DATABASE ds_0; + +DROP DATABASE IF EXISTS ds_1; +CREATE DATABASE ds_1; +``` + +#### 操作步骤 + +1. 在 `server.yaml` 中开启 CDC 功能。 + +```yaml +mode: + type: Cluster Review Comment: It's better to put server.yaml to build document ########## docs/document/content/user-manual/shardingsphere-proxy/cdc/build.cn.md: ########## @@ -0,0 +1,160 @@ ++++ +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 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://repo1.maven.org/maven2/org/apache/shardingsphere/shardingsphere-global-clock-tso-provider-redis)，下载和 ShardingSphere-Proxy 同名版本 +2. [jedis-4.3.1](https://repo1.maven.org/maven2/redis/clients/jedis/4.3.1/jedis-4.3.1.jar) + +### 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-8.0.11.jar]( https://repo1.maven.org/maven2/mysql/mysql-connector-java/5.1.49/mysql-connector-java-5.1.49.jar ) | [Connector/J Versions]( https://repo1.maven.org/maven2/mysql/mysql-connector-java/8.0.11/mysql-connector-java-8.0.11.jar ) | Review Comment: 1, Reference column could be removed 2, mysql-connector-java url could be updated 3, mysql-connector-java version should be the same as proxy -- 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]
