BASE Transaction

[makssent]

Hi everyone!
Previously used the project for testing distributed transactions (XA) using examples from the shardingsphere/examples repository. I noticed that there are no examples for BASE transactions, even though they are described in the documentation.

I attempted to add the dependencies via Maven:

<dependency>
    <groupId>org.apache.shardingsphere</groupId>
    <artifactId>shardingsphere-transaction-base</artifactId>
    <version>${project.version}</version>
</dependency>
<dependency>
    <groupId>org.apache.shardingsphere</groupId>
    <artifactId>sharding-transaction-base-seata-at</artifactId>
    <version>${project.version}</version>
</dependency>

However, the dependencies did not work Could not find artifact org.apache.shardingsphere:sharding-transaction-base-seata-at:jar:5.5.2-SNAPSHOT, and I couldn’t find any up-to-date examples or documentation for configuring BASE transactions.
Question at this point can we use BASE transactions?

P.S. I'm aware that BASE transactions require a SEATA server, but I wanted to make sure that such transactions are supported first to move forward.

[linghengqian]

I noticed that there are no examples for BASE transactions, even though they are described in the documentation.

• I guess you are referring to Seata's AT mode. ShardingSphere currently only focuses on Seata's AT mode. ShardingSphere has not done unit testing for Seata's TCC mode. ShardingSphere has never supported Seata's SAGA mode and XA mode.
• The CI of https://github.com/apache/shardingsphere/tree/master/examples is actually broken, see https://github.com/apache/shardingsphere/actions/runs/13703021727 . Since this module is written in FreeMarker, it's hard to say that I personally know how to fix CI.

and I couldn’t find any up-to-date examples or documentation for configuring BASE transactions.

For document

• The seata documentation for shardingsphere jdbc is at https://shardingsphere.apache.org/document/current/en/user-manual/shardingsphere-jdbc/special-api/transaction/seata/ , and the seata documentation for shardingsphere proxy is at https://shardingsphere.apache.org/document/current/en/user-manual/shardingsphere-proxy/optional-plugins/seata-at/ .

For unit test about postgresql

• There are indeed no normal integration tests for seata currently.
• However, shardingsphere did write integration tests for postgresql and seata server against the graalvm native image environment.
• The integration tests for Seata integration of ShardingSphere JDBC are located at https://github.com/apache/shardingsphere/blob/master/test/native/src/test/java/org/apache/shardingsphere/test/natived/jdbc/transactions/base/SeataTest.java .
• The integration tests for the Seata integration of ShardingSphere Proxy are at https://github.com/apache/shardingsphere/blob/master/test/native/src/test/java/org/apache/shardingsphere/test/natived/proxy/transactions/base/SeataTest.java . Note that this unit test is broken due to Could not create table after logic database created for MySQL #34816 . I can hardly say that I know how to fix Could not create table after logic database created for MySQL #34816 .
• Note that both of these unit tests target only a single microservice. Due to Seata Multi-Client Optimization incubator-seata#6614 , I intentionally did not test the transaction propagation feature across microservices in the master branch of shardingsphere.

For example git about mysql

• We introduce a premise that the shardingsphere document is built with hugo. hugo supports mermaid drawing. But for me, testing the shardingsphere document's support for mermaid is a very troublesome thing. This results in the seata document currently having no pictures.
• To explain the history of Seata integration of ShardingSphere, I wrote a Chinese article https://www.yuque.com/linghengqian/meve2v/es8d3a8a18odao7x , which demonstrated how to enable transaction propagation across microservices of Seata 2.2.0 for ShardingSphere jdbc 5.5.1 and MySQL 9.1.0 in multiple Spring Boot 3.3.5 microservices. This article does use the Yuque editor specifically to draw pictures.
• I personally don't have the energy to translate this article. But the corresponding git of this article is located at https://github.com/linghengqian/shardingsphere-seata-playground , I believe it is enough to explain a lot of things. Reading this article does require an advance understanding of spring boot, seata, shardingsphere, and mysql.
• 

P.S. I'm aware that BASE transactions require a SEATA server, but I wanted to make sure that such transactions are supported first to move forward.

• Okay, the premise we're going to introduce is that we're only going to talk about the AT mode of Seata.
• This obviously requires SQL dialect parsing to be implemented on the Seata side, and Seata implements dialect parsing through Alibaba Druid by default.
• seata also has an optional antlr4 dialect parsing module, but for more complicated reasons that module is practically unusable.
• Therefore, the seata integration of ShardingSphere actually only supports the databases mentioned in https://github.com/apache/incubator-seata/tree/v2.2.0/script/client/at/db . Currently they are dm, mysql, oracle, postgresql, and sqlserver.
• https://shardingsphere.apache.org/document/current/en/user-manual/shardingsphere-jdbc/special-api/transaction/seata/ gives some examples of related Docker Images.

When using ShardingSphere’s Seata integration module, the database instance connected to ShardingSphere should implement both ShardingSphere’s dialect parsing support and Seata AT mode’s dialect parsing support. This type of database includes but is not limited to mysql, gvenzl/oracle-free, gvenzl/oracle-xe, postgres, mcr.microsoft.com/mssql/server and other Docker Images.

• Databases with this feature include but are not limited to the following Docker Images,

1. Third-party Docker Image mysql for MySQL Community Server
2. Third-party Docker Image gvenzl/oracle-free for Oracle Database Free
3. Third-party Docker Image gvenzl/oracle-xe for Oracle Database Express Edition (XE)
4. Third-party Docker Image postgres for PostgreSQL
5. Official Docker Image mcr.microsoft.com/mssql/server for Microsoft SQL Server

• Seata also supports DM represented by DM8, but that is a commercial database. Dameng does not provide docker image to non-paying users. Refer to https://www.dameng.com/DM8.html . Seata obviously supports DM8 in a mock way, and Shardingsphere will not try to test this database that lacks docker image in the master branch.

[makssent]

For document

• The seata documentation for shardingsphere jdbc is at https://shardingsphere.apache.org/document/current/en/user-manual/shardingsphere-jdbc/special-api/transaction/seata/ , and the seata documentation for shardingsphere proxy is at https://shardingsphere.apache.org/document/current/en/user-manual/shardingsphere-proxy/optional-plugins/seata-at/ .

Thank you, this is exactly the information I was looking for. As always, you explained everything in detail and clearly. Now I can start testing BASE with JDBC. Hopefully I won't have to pester you with any more questions, but it's not certain :)

[linghengqian]

• The documentation has an outdated configuration record, I have opened Fix Proxy's Seata integration config doc #34941 .