diff --git a/docs/document/content/user-manual/shardingsphere-jdbc/special-api/transaction/seata.cn.md b/docs/document/content/user-manual/shardingsphere-jdbc/special-api/transaction/seata.cn.md index 7a41e181ca9fa..53adcdf9c6248 100644 --- a/docs/document/content/user-manual/shardingsphere-jdbc/special-api/transaction/seata.cn.md +++ b/docs/document/content/user-manual/shardingsphere-jdbc/special-api/transaction/seata.cn.md @@ -5,7 +5,39 @@ weight = 7 ## 背景信息 -Apache ShardingSphere 提供 BASE 事务,集成了 Seata 的实现。 +Apache ShardingSphere 提供 BASE 事务,集成了 Seata 的实现。本文所指 Seata 集成均指向 Seata AT 模式。 + +## 前提条件 + +引入 Maven 依赖,并排除 `io.seata:seata-all` 中过时的 `org.antlr:antlr4-runtime:4.8` 的 Maven 依赖。 + +```xml + + + + org.apache.shardingsphere + shardingsphere-jdbc-core + ${shardingsphere.version} + + + org.apache.shardingsphere + shardingsphere-transaction-base-seata-at + ${shardingsphere.version} + + + io.seata + seata-all + 2.0.0 + + + org.antlr + antlr4-runtime + + + + + +``` ## 操作步骤 @@ -17,39 +49,77 @@ Apache ShardingSphere 提供 BASE 事务,集成了 Seata 的实现。 ### 启动 Seata Server -按照 [seata-work-shop](https://github.com/seata/seata-workshop) 中的步骤,下载并启动 Seata 服务器。 +按照 [seata-fescar-workshop](https://github.com/seata/fescar-workshop) 或 https://hub.docker.com/r/seataio/seata-server 中的步骤, +下载并启动 Seata 服务器。 ### 创建 undo_log 表 在每一个分片数据库实例中执创建 `undo_log` 表(以 MySQL 为例)。 +SQL 的内容以 https://github.com/apache/incubator-seata/tree/v2.0.0/script/client/at/db 内对应的数据库为准。 ```sql CREATE TABLE IF NOT EXISTS `undo_log` ( - `id` BIGINT(20) NOT NULL AUTO_INCREMENT COMMENT 'increment id', - `branch_id` BIGINT(20) NOT NULL COMMENT 'branch transaction id', - `xid` VARCHAR(100) NOT NULL COMMENT 'global transaction id', - `context` VARCHAR(128) NOT NULL COMMENT 'undo_log context,such as serialization', - `rollback_info` LONGBLOB NOT NULL COMMENT 'rollback info', - `log_status` INT(11) NOT NULL COMMENT '0:normal status,1:defense status', - `log_created` DATETIME NOT NULL COMMENT 'create datetime', - `log_modified` DATETIME NOT NULL COMMENT 'modify datetime', - PRIMARY KEY (`id`), - UNIQUE KEY `ux_undo_log` (`xid`, `branch_id`) -) ENGINE = InnoDB - AUTO_INCREMENT = 1 - DEFAULT CHARSET = utf8 COMMENT ='AT transaction mode undo table'; + `branch_id` BIGINT NOT NULL COMMENT 'branch transaction id', + `xid` VARCHAR(128) NOT NULL COMMENT 'global transaction id', + `context` VARCHAR(128) NOT NULL COMMENT 'undo_log context,such as serialization', + `rollback_info` LONGBLOB NOT NULL COMMENT 'rollback info', + `log_status` INT(11) NOT NULL COMMENT '0:normal status,1:defense status', + `log_created` DATETIME(6) NOT NULL COMMENT 'create datetime', + `log_modified` DATETIME(6) NOT NULL COMMENT 'modify datetime', + UNIQUE KEY `ux_undo_log` (`xid`, `branch_id`) + ) ENGINE = InnoDB AUTO_INCREMENT = 1 DEFAULT CHARSET = utf8mb4 COMMENT ='AT transaction mode undo table'; + +ALTER TABLE `undo_log` ADD INDEX `ix_log_created` (`log_created`); ``` ### 修改配置 -在 classpath 中增加 `seata.conf` 文件。 +在 classpath 的根目录中增加 `seata.conf` 文件, +配置文件格式参考 `io.seata.config.FileConfiguration` 的 [JavaDoc](https://github.com/apache/incubator-seata/blob/v2.0.0/config/seata-config-core/src/main/java/io/seata/config/FileConfiguration.java)。 + +`seata.conf` 存在四个属性, + +1. `sharding.transaction.seata.at.enable`,当此值为`true`时,开启 ShardingSphere 的 Seata AT 集成,存在默认值为 `true` +2. `sharding.transaction.seata.tx.timeout`,全局事务超时(秒),存在默认值为 `60` +3. `client.application.id`,应用唯一主键 +4. `client.transaction.service.group`,所属事务组,存在默认值为 `default` + +一个完全配置的 `seata.conf` 如下, ```conf +sharding.transaction.seata.at.enable = true +sharding.transaction.seata.tx.timeout = 30 + client { - application.id = example ## 应用唯一主键 - transaction.service.group = my_test_tx_group ## 所属事务组 + application.id = example + transaction.service.group = default_tx_group } ``` 根据实际场景修改 Seata 的 `file.conf` 和 `registry.conf` 文件。 + +### 使用限制 + +ShardingSphere 的 Seata 集成不支持隔离级别。 + +ShardingSphere 的 Seata 集成将获取到的 Seata 全局事务置入线程的局部变量。 +而 `org.apache.seata.spring.annotation.GlobalTransactionScanner` 则是采用 Dynamic Proxy 的方式对方法进行增强。 +这意味着用户始终不应该针对 ShardingSphere 的 DataSource 使用 `io.seata:seata-spring-boot-starter` 的注解。 +即在使用 ShardingSphere 的 Seata 集成时,用户应避免使用 `io.seata:seata-spring-boot-starter` 的 Maven 依赖。 + +针对 ShardingSphere 数据源,讨论 5 种情况, + +1. 手动获取从 ShardingSphere 数据源创建的 `java.sql.Connection` 实例, +并手动调用 `setAutoCommit()`, `commit()` 和 `rollback()` 方法,这是被允许的。 + +2. 在函数上使用 Jakarta EE 8 的 `javax.transaction.Transactional` 注解,这是被允许的。 + +3. 在函数上使用 Jakarta EE 9/10 的 `jakarta.transaction.Transactional` 注解,这是被允许的。 + +4. 在函数上使用 `io.seata.spring.annotation.GlobalTransactional` 注解,这是不被允许的。 + +5. 手动从 `io.seata.tm.api.GlobalTransactionContext ` 创建 `io.seata.tm.api.GlobalTransaction` 实例, +调用 `io.seata.tm.api.GlobalTransaction` 实例的 `begin()`, `commit()` 和 `rollback()` 方法,这是不被允许的。 + +长话短说,在使用 ShardingSphere 的 Seata 集成时,你不应该使用 Seata Java API。 diff --git a/docs/document/content/user-manual/shardingsphere-jdbc/special-api/transaction/seata.en.md b/docs/document/content/user-manual/shardingsphere-jdbc/special-api/transaction/seata.en.md index 92d72d302667f..1ba21fc838d0e 100644 --- a/docs/document/content/user-manual/shardingsphere-jdbc/special-api/transaction/seata.en.md +++ b/docs/document/content/user-manual/shardingsphere-jdbc/special-api/transaction/seata.en.md @@ -6,6 +6,39 @@ weight = 7 ## Background Apache ShardingSphere provides BASE transactions that integrate the Seata implementation. +All references to Seata integration in this article refer to Seata AT mode. + +## Prerequisites + +Introduce Maven dependencies and exclude the outdated Maven dependencies of `org.antlr:antlr4-runtime:4.8` in `io.seata:seata-all`. + +```xml + + + + org.apache.shardingsphere + shardingsphere-jdbc-core + ${shardingsphere.version} + + + org.apache.shardingsphere + shardingsphere-transaction-base-seata-at + ${shardingsphere.version} + + + io.seata + seata-all + 2.0.0 + + + org.antlr + antlr4-runtime + + + + + +``` ## Procedure @@ -17,39 +50,77 @@ Apache ShardingSphere provides BASE transactions that integrate the Seata implem ### Start Seata Server -Refer to [seata-work-shop](https://github.com/seata/seata-workshop) to download and start the Seata server. +Follow the steps in [seata-fescar-workshop](https://github.com/seata/fescar-workshop) or https://hub.docker.com/r/seataio/seata-server , +download and start the Seata server. ### Create undo_log table Create the `undo_log` table in each shard database instance (take MySQL as an example). +The content of SQL is subject to the corresponding database in https://github.com/apache/incubator-seata/tree/v2.0.0/script/client/at/db . ```sql CREATE TABLE IF NOT EXISTS `undo_log` ( - `id` BIGINT(20) NOT NULL AUTO_INCREMENT COMMENT 'increment id', - `branch_id` BIGINT(20) NOT NULL COMMENT 'branch transaction id', - `xid` VARCHAR(100) NOT NULL COMMENT 'global transaction id', - `context` VARCHAR(128) NOT NULL COMMENT 'undo_log context,such as serialization', - `rollback_info` LONGBLOB NOT NULL COMMENT 'rollback info', - `log_status` INT(11) NOT NULL COMMENT '0:normal status,1:defense status', - `log_created` DATETIME NOT NULL COMMENT 'create datetime', - `log_modified` DATETIME NOT NULL COMMENT 'modify datetime', - PRIMARY KEY (`id`), - UNIQUE KEY `ux_undo_log` (`xid`, `branch_id`) -) ENGINE = InnoDB - AUTO_INCREMENT = 1 - DEFAULT CHARSET = utf8 COMMENT ='AT transaction mode undo table'; + `branch_id` BIGINT NOT NULL COMMENT 'branch transaction id', + `xid` VARCHAR(128) NOT NULL COMMENT 'global transaction id', + `context` VARCHAR(128) NOT NULL COMMENT 'undo_log context,such as serialization', + `rollback_info` LONGBLOB NOT NULL COMMENT 'rollback info', + `log_status` INT(11) NOT NULL COMMENT '0:normal status,1:defense status', + `log_created` DATETIME(6) NOT NULL COMMENT 'create datetime', + `log_modified` DATETIME(6) NOT NULL COMMENT 'modify datetime', + UNIQUE KEY `ux_undo_log` (`xid`, `branch_id`) + ) ENGINE = InnoDB AUTO_INCREMENT = 1 DEFAULT CHARSET = utf8mb4 COMMENT ='AT transaction mode undo table'; + +ALTER TABLE `undo_log` ADD INDEX `ix_log_created` (`log_created`); ``` ### Modify configuration -Add the `seata.conf` file to the classpath. +Add the `seata.conf` file to the root directory of the classpath. +The configuration file format refers to the [JavaDoc](https://github.com/apache/incubator-seata/blob/v2.0.0/config/seata-config-core/src/main/java/io/seata/config/FileConfiguration.java) of `io.seata.config.FileConfiguration`. + +There are four properties in `seata.conf`, + +1. `sharding.transaction.seata.at.enable`, when this value is `true`, ShardingSphere's Seata AT integration is enabled, there is a default value of `true` +2. `sharding.transaction.seata.tx.timeout`, global transaction timeout in SECONDS, there is a default value of `60` +3. `client.application.id`, apply the only primary key +4. `client.transaction.service.group`, the transaction group it belongs to, there is a default value of `default` + +A fully configured `seata.conf` is as follows, ```conf +sharding.transaction.seata.at.enable = true +sharding.transaction.seata.tx.timeout = 30 + client { - application.id = example ## Apply the only primary key - transaction.service.group = my_test_tx_group ## The transaction group it belongs to. + application.id = example + transaction.service.group = default_tx_group } ``` Modify the `file.conf` and `registry.conf` files of Seata as required. + +### Usage restrictions + +ShardingSphere's Seata integration does not support isolation levels. + +ShardingSphere's Seata integration places the obtained Seata global transaction into the thread's local variables. +And `org.apache.seata.spring.annotation.GlobalTransactionScanner` uses Dynamic Proxy to enhance the method. +This means that users should never use the `io.seata:seata-spring-boot-starter` annotation for ShardingSphere's DataSource. +That is, when using ShardingSphere's Seata integration, users should avoid using the Maven dependency of `io.seata:seata-spring-boot-starter`. + +For ShardingSphere data source, discuss 5 situations, + +1. Manually obtain the `java.sql.Connection` instance created from the ShardingSphere data source, + and manually calling the `setAutoCommit()`, `commit()` and `rollback()` methods is allowed. + +2. Using the Jakarta EE 8 `javax.transaction.Transactional` annotation on the function is allowed. + +3. Using Jakarta EE 9/10’s `jakarta.transaction.Transactional` annotation on functions is allowed. + +4. Using the `io.seata.spring.annotation.GlobalTransactional` annotation on the function is not allowed. + +5. Manually create `io.seata.tm.api.GlobalTransaction` instance from `io.seata.tm.api.GlobalTransactionContext`, +calling the `begin()`, `commit()` and `rollback()` methods of an `io.seata.tm.api.GlobalTransaction` instance is not allowed. + +Long story short, you should not use the Seata Java API when using ShardingSphere's Seata integration. diff --git a/kernel/transaction/type/base/seata-at/pom.xml b/kernel/transaction/type/base/seata-at/pom.xml index e6ef1c98ee45d..d89ff39403102 100644 --- a/kernel/transaction/type/base/seata-at/pom.xml +++ b/kernel/transaction/type/base/seata-at/pom.xml @@ -26,6 +26,27 @@ shardingsphere-transaction-base-seata-at ${project.artifactId} + + + + io.seata + seata-all + ${seata.version} + + + org.antlr + antlr4-runtime + + + + + org.antlr + antlr4-runtime + ${antlr4.version} + + + + org.apache.shardingsphere diff --git a/kernel/transaction/type/base/seata-at/src/test/resources/file.conf b/kernel/transaction/type/base/seata-at/src/test/resources/file.conf index 47f45ee06becc..0a3731adf5705 100644 --- a/kernel/transaction/type/base/seata-at/src/test/resources/file.conf +++ b/kernel/transaction/type/base/seata-at/src/test/resources/file.conf @@ -39,11 +39,9 @@ transport { } service { #vgroup->rgroup - vgroupMapping.my_test_tx_group = "default" + vgroupMapping.default_tx_group = "default" #only support single node default.grouplist = "127.0.0.1:8891" - #degrade current not support - enableDegrade = false #disable disable = false } @@ -54,4 +52,7 @@ client { retry.internal = 10 retry.times = 30 } + tm { + degradeCheck = false + } } diff --git a/kernel/transaction/type/base/seata-at/src/test/resources/seata.conf b/kernel/transaction/type/base/seata-at/src/test/resources/seata.conf index 069a678a7e5df..dd4a21605412d 100644 --- a/kernel/transaction/type/base/seata-at/src/test/resources/seata.conf +++ b/kernel/transaction/type/base/seata-at/src/test/resources/seata.conf @@ -20,5 +20,5 @@ sharding.transaction.seata.tx.timeout = 30 client { application.id = jdbc-test - transaction.service.group = my_test_tx_group + transaction.service.group = default_tx_group } diff --git a/pom.xml b/pom.xml index 0efa42e3dc035..00f95da26dbd7 100644 --- a/pom.xml +++ b/pom.xml @@ -97,7 +97,7 @@ 5.12.4.Final 7.6.0.Final 3.2.1.Final - 1.6.1 + 2.0.0 4.1.106.Final 1.70