Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Bump io.seata:seata-all for testing to 2.0.0 #30146

Merged
merged 1 commit into from
Feb 17, 2024
Merged

Bump io.seata:seata-all for testing to 2.0.0 #30146

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
106 changes: 88 additions & 18 deletions ...ent/content/user-manual/shardingsphere-jdbc/special-api/transaction/seata.cn.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
<project>
<dependencies>
<dependency>
<groupId>org.apache.shardingsphere</groupId>
<artifactId>shardingsphere-jdbc-core</artifactId>
<version>${shardingsphere.version}</version>
</dependency>
<dependency>
<groupId>org.apache.shardingsphere</groupId>
<artifactId>shardingsphere-transaction-base-seata-at</artifactId>
<version>${shardingsphere.version}</version>
</dependency>
<dependency>
<groupId>io.seata</groupId>
<artifactId>seata-all</artifactId>
<version>2.0.0</version>
<exclusions>
<exclusion>
<groupId>org.antlr</groupId>
<artifactId>antlr4-runtime</artifactId>
</exclusion>
</exclusions>
</dependency>
</dependencies>
</project>
```

## 操作步骤

Expand All @@ -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。
105 changes: 88 additions & 17 deletions ...ent/content/user-manual/shardingsphere-jdbc/special-api/transaction/seata.en.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
<project>
<dependencies>
<dependency>
<groupId>org.apache.shardingsphere</groupId>
<artifactId>shardingsphere-jdbc-core</artifactId>
<version>${shardingsphere.version}</version>
</dependency>
<dependency>
<groupId>org.apache.shardingsphere</groupId>
<artifactId>shardingsphere-transaction-base-seata-at</artifactId>
<version>${shardingsphere.version}</version>
</dependency>
<dependency>
<groupId>io.seata</groupId>
<artifactId>seata-all</artifactId>
<version>2.0.0</version>
<exclusions>
<exclusion>
<groupId>org.antlr</groupId>
<artifactId>antlr4-runtime</artifactId>
</exclusion>
</exclusions>
</dependency>
</dependencies>
</project>
```

## Procedure

Expand All @@ -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.
21 changes: 21 additions & 0 deletions kernel/transaction/type/base/seata-at/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,27 @@
<artifactId>shardingsphere-transaction-base-seata-at</artifactId>
<name>${project.artifactId}</name>

<dependencyManagement>
<dependencies>
<dependency>
<groupId>io.seata</groupId>
<artifactId>seata-all</artifactId>
<version>${seata.version}</version>
<exclusions>
<exclusion>
<groupId>org.antlr</groupId>
<artifactId>antlr4-runtime</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>org.antlr</groupId>
<artifactId>antlr4-runtime</artifactId>
<version>${antlr4.version}</version>
</dependency>
</dependencies>
</dependencyManagement>

<dependencies>
<dependency>
<groupId>org.apache.shardingsphere</groupId>
Expand Down
7 changes: 4 additions & 3 deletions kernel/transaction/type/base/seata-at/src/test/resources/file.conf
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
}
Expand All @@ -54,4 +52,7 @@ client {
retry.internal = 10
retry.times = 30
}
tm {
degradeCheck = false
}
}
2 changes: 1 addition & 1 deletion kernel/transaction/type/base/seata-at/src/test/resources/seata.conf
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
}
2 changes: 1 addition & 1 deletion pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,7 @@
<narayana.version>5.12.4.Final</narayana.version>
<jboss-transaction-spi.version>7.6.0.Final</jboss-transaction-spi.version>
<jboss-logging.version>3.2.1.Final</jboss-logging.version>
<seata.version>1.6.1</seata.version>
<seata.version>2.0.0</seata.version>

<netty.version>4.1.106.Final</netty.version>
<bouncycastle.version>1.70</bouncycastle.version>
Expand Down
Loading