Using transactions in Quarkus

`quarkus-narayana-jta`扩展提供了一个事务管理器，它可以协调和将事务曝光给你的应用，如链接中所述： Jakarta Transactions规范（以前称为 Java Transaction API (JTA)）。

The quarkus-narayana-jta extension provides a Transaction Manager that coordinates and expose transactions to your applications as described in the link: Jakarta Transactions specification, formerly known as Java Transaction API (JTA).

在讨论 Quarkus 事务时，本指南引用 Jakarta Transactions 事务样式，并且只使用术语 _transaction_来解决它们。

When discussing Quarkus transactions, this guide refers to Jakarta Transactions transaction style and uses only the term transaction to address them.

此外，Quarkus 不支持分布式事务。这意味着 Java Transaction Service (JTS)、REST-AT、WS-Atomic Transaction 等传播事务上下文的模型不受 narayana-jta 扩展支持。

Also, Quarkus does not support distributed transactions. This means that models that propagate transaction context, such as Java Transaction Service (JTS), REST-AT, WS-Atomic Transaction, and others, are not supported by the narayana-jta extension.

Setting it up

无需担心在大多数情况下进行设置，而需要此扩展的扩展会将其简单地作为一个依赖项。例如，Hibernate ORM 将包括事务管理器，并将其正确设置。

You don’t need to worry about setting it up most of the time as extensions needing it will simply add it as a dependency. Hibernate ORM for example will include the transaction manager and set it up properly.

例如，如果您未直接使用 Hibernate ORM，则可能需要显式将其作为一个依赖项添加。将以下内容添加到您的构建文件：

You might need to add it as a dependency explicitly if you are using transactions directly without Hibernate ORM for example. Add the following to your build file:

pom.xml
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-narayana-jta</artifactId>
</dependency>
build.gradle
implementation("io.quarkus:quarkus-narayana-jta")

Starting and stopping transactions: defining your boundaries

您可以用 @Transactional 声明式定义您的事务边界，也可以用 QuarkusTransaction 以编程方式定义。此外，还可以直接使用 JTA UserTransaction API，不过这不如 QuarkusTransaction 用户友好。

You can define your transaction boundaries either declaratively with @Transactional or programmatically with QuarkusTransaction. You can also use the JTA UserTransaction API directly, however this is less user-friendly than QuarkusTransaction.

Declarative approach

定义事务边界的简便方法是在入口方法上使用 @Transactional 注解 (jakarta.transaction.Transactional)。

The easiest way to define your transaction boundaries is to use the @Transactional annotation on your entry method (jakarta.transaction.Transactional).

@ApplicationScoped
public class SantaClausService {

    @Inject ChildDAO childDAO;
    @Inject SantaClausDAO santaDAO;

    @Transactional (1)
    public void getAGiftFromSanta(Child child, String giftDescription) {
        // some transaction work
        Gift gift = childDAO.addToGiftList(child, giftDescription);
        if (gift == null) {
            throw new OMGGiftNotRecognizedException(); (2)
        }
        else {
            santaDAO.addToSantaTodoList(gift);
        }
    }
}
1 This annotation defines your transaction boundaries and will wrap this call within a transaction.
2 A RuntimeException crossing the transaction boundaries will roll back the transaction.

@Transactional 可用于控制方法级或类级的任何 CDI Bean 上的事务边界，确保事务化每个方法。其中包括 REST 端点。

@Transactional can be used to control transaction boundaries on any CDI bean at the method level or at the class level to ensure every method is transactional. That includes REST endpoints.

您可以使用 @Transactional 的参数控制是否以及如何启动事务：

You can control whether and how the transaction is started with parameters on @Transactional:

  • @Transactional(REQUIRED) (default): starts a transaction if none was started, stays with the existing one otherwise.

  • @Transactional(REQUIRES_NEW): starts a transaction if none was started ; if an existing one was started, suspends it and starts a new one for the boundary of that method.

  • @Transactional(MANDATORY): fails if no transaction was started ; works within the existing transaction otherwise.

  • @Transactional(SUPPORTS): if a transaction was started, joins it ; otherwise works with no transaction.

  • @Transactional(NOT_SUPPORTED): if a transaction was started, suspends it and works with no transaction for the boundary of the method ; otherwise works with no transaction.

  • @Transactional(NEVER): if a transaction was started, raises an exception ; otherwise works with no transaction.

REQUIRED 或 NOT_SUPPORTED 可能用处最大。通过此方法您可以确定某个方法在事务内还是在事务外运行。务必查看 JavaDoc，了解确切语义。

REQUIRED or NOT_SUPPORTED are probably the most useful ones. This is how you decide whether a method is to be running within or outside a transaction. Make sure to check the JavaDoc for the precise semantic.

正如预期的那样，事务上下文将传播到 @Transactional 方法中嵌套的所有调用（在此示例中为 childDAO.addToGiftList()`和 `santaDAO.addToSantaTodoList()）。将提交事务，除非运行时异常跨越方法边界。您可以使用 @Transactional(dontRollbackOn=SomeException.class) （或 rollbackOn）覆盖是否由异常强制回滚。

The transaction context is propagated to all calls nested in the @Transactional method as you would expect (in this example childDAO.addToGiftList() and santaDAO.addToSantaTodoList()). The transaction will commit unless a runtime exception crosses the method boundary. You can override whether an exception forces the rollback or not by using @Transactional(dontRollbackOn=SomeException.class) (or rollbackOn).

此外，还可以通过编程方式要求将事务标记为需回滚。为此注入一个 TransactionManager。

You can also programmatically ask for a transaction to be marked for rollback. Inject a TransactionManager for this.

@ApplicationScoped
public class SantaClausService {

    @Inject TransactionManager tm; (1)
    @Inject ChildDAO childDAO;
    @Inject SantaClausDAO santaDAO;

    @Transactional
    public void getAGiftFromSanta(Child child, String giftDescription) {
        // some transaction work
        Gift gift = childDAO.addToGiftList(child, giftDescription);
        if (gift == null) {
            tm.setRollbackOnly(); (2)
        }
        else {
            santaDAO.addToSantaTodoList(gift);
        }
    }
}
1 Inject the TransactionManager to be able to activate setRollbackOnly semantic.
2 Programmatically decide to set the transaction for rollback.

Transaction configuration

可以使用 @TransactionConfiguration 注释配合在条目方法或类级别设置的标准 @Transactional 注释高级配置事务。

Advanced configuration of the transaction is possible with the use of the @TransactionConfiguration annotation that is set in addition to the standard @Transactional annotation on your entry method or at the class level.

@TransactionConfiguration 注释允许设置超时属性（以秒为单位），适用于在带注释的方法中创建的事务。

The @TransactionConfiguration annotation allows to set a timeout property, in seconds, that applies to transactions created within the annotated method.

此注释只能放在描述事务的顶级方法上。在事务已开始后注释的嵌套方法将引发异常。

This annotation may only be placed on the top level method delineating the transaction. Annotated nested methods once a transaction has started will throw an exception.

如果在类上定义，则等同于在所有使用 @Transactional 标记的类方法上进行定义。方法上定义的配置优先于类上定义的配置。

If defined on a class, it is equivalent to defining it on all the methods of the class marked with @Transactional. The configuration defined on a method takes precedence over the configuration defined on a class.

Reactive extensions

如果用 @Transactional 注释的方法返回响应值，例如：

If your @Transactional-annotated method returns a reactive value, such as:

  • CompletionStage (from the JDK)

  • Publisher (from Reactive-Streams)

  • Any type that can be converted to one of the two previous types using Reactive Type Converters

那么其行为略有不同，因为只有当返回的响应值结束时，事务才会结束。事实上，返回的响应值将被侦听，如果它以异常结束，则将标记事务以回滚，并只在响应值结束时提交或回滚。

then the behaviour is a bit different, because the transaction will not be terminated until the returned reactive value is terminated. In effect, the returned reactive value will be listened to and if it terminates exceptionally the transaction will be marked for rollback, and will be committed or rolled-back only at termination of the reactive value.

这允许你的响应方法异步地继续对事务执行操作直到工作真正完成，而不仅仅是等到响应方法返回时。

This allows your reactive methods to keep on working on the transaction asynchronously until their work is really done, and not just until the reactive method returns.

如果你需要在响应管道中传播事务上下文，请参见 Context Propagation guide。

If you need to propagate your transaction context across your reactive pipeline, please see the Context Propagation guide.

Programmatic approach

你可以使用 QuarkusTransaction 上的静态方法来定义事务边界。这提供了两种不同的选项，一种是函数式方法，允许你在事务作用域内运行 lambda 表达式，另一种是使用明确的 begin 、 commit 和 rollback 方法。

You can use static methods on QuarkusTransaction to define transaction boundaries. This provides two different options, a functional approach that allows you to run a lambda within the scope of a transaction, or by using explicit begin, commit and rollback methods.

import io.quarkus.narayana.jta.QuarkusTransaction;
import io.quarkus.narayana.jta.RunOptions;

public class TransactionExample {

    public void beginExample() {
        QuarkusTransaction.begin();
        //do work
        QuarkusTransaction.commit();

        QuarkusTransaction.begin(QuarkusTransaction.beginOptions()
                .timeout(10));
        //do work
        QuarkusTransaction.rollback();
    }

    public void runnerExample() {
        QuarkusTransaction.requiringNew().run(() -> {
            //do work
        });
        QuarkusTransaction.joiningExisting().run(() -> {
            //do work
        });

        int result = QuarkusTransaction.requiringNew()
                .timeout(10)
                .exceptionHandler((throwable) -> {
                    if (throwable instanceof SomeException) {
                        return RunOptions.ExceptionResult.COMMIT;
                    }
                    return TransactionExceptionResult.ROLLBACK;
                })
                .call(() -> {
                    //do work
                    return 0;
                });
    }
}

上面的示例展示了此 API 的几种不同使用方法。

The above example shows a few different ways the API can be used.

第一个方法只是调用 begin，执行一些操作并提交它。创建的事务绑定到 CDI 请求作用域，因此如果在请求作用域销毁时事务仍然处于活动状态，那么它将自动回滚。这避免了显式捕获异常和调用 rollback 的需要，并且充当防止无意事务泄漏的安全措施，然而它确实意味着这只能在请求作用域活动时使用。方法中的第二个示例调用带有超时选项的 begin，然后回滚事务。

The first method simply calls begin, does some work and commits it. This created transaction is tied to the CDI request scope, so if it is still active when the request scope is destroyed then it will be automatically rolled back. This removes the need to explicitly catch exceptions and call rollback, and acts as a safety net against inadvertent transaction leaks, however it does mean that this can only be used when the request scope is active. The second example in the method calls begin with a timeout option, and then rolls back the transaction.

第二个方法展示了使用带有 QuarkusTransaction.runner(…​) 的 lambda 作用域事务；第一个示例只是在新的事务中运行 Runnable，第二个示例也这样做不过加入现有的事务（如果有），第三个示例使用一些特定选项调用 Callable。尤其是 exceptionHandler 方法可以用来控制是否在发生异常时回滚事务。

The second method shows the use of lambda scoped transactions with QuarkusTransaction.runner(…​); the first example just runs a Runnable within a new transaction, the second does the same but joining the existing transaction (if any), and the third calls a Callable with some specific options. In particular the exceptionHandler method can be used to control if the transaction is rolled back or not on exception.

支持以下语义：

The following semantics are supported:

QuarkusTransaction.disallowingExisting()/DISALLOW_EXISTING

If a transaction is already associated with the current thread a QuarkusTransactionException will be thrown, otherwise a new transaction is started, and follows all the normal lifecycle rules.

QuarkusTransaction.joiningExisting()/JOIN_EXISTING

If no transaction is active then a new transaction will be started, and committed when the method ends. If an exception is thrown the exception handler registered by #exceptionHandler(Function) will be called to decide if the TX should be committed or rolled back. If an existing transaction is active then the method is run in the context of the existing transaction. If an exception is thrown the exception handler will be called, however a result of ExceptionResult#ROLLBACK will result in the TX marked as rollback only, while a result of ExceptionResult#COMMIT will result in no action being taken.

QuarkusTransaction.requiringNew()/REQUIRE_NEW

If an existing transaction is already associated with the current thread then the transaction is suspended, then a new transaction is started which follows all the normal lifecycle rules, and when it’s complete the original transaction is resumed. Otherwise, a new transaction is started, and follows all the normal lifecycle rules.

QuarkusTransaction.suspendingExisting()/SUSPEND_EXISTING

If no transaction is active then these semantics are basically a no-op. If a transaction is active then it is suspended, and resumed after the task is run. The exception handler will never be consulted when these semantics are in use, specifying both an exception handler and these semantics are considered an error. These semantics allows for code to easily be run outside the scope of a transaction.

Legacy API approach

一种不太容易的方法是注入 UserTransaction 并使用各种事务分隔方法。

The less easy way is to inject a UserTransaction and use the various transaction demarcation methods.

@ApplicationScoped
public class SantaClausService {

    @Inject ChildDAO childDAO;
    @Inject SantaClausDAO santaDAO;
    @Inject UserTransaction transaction;

    public void getAGiftFromSanta(Child child, String giftDescription) {
        // some transaction work
        try {
            transaction.begin();
            Gift gift = childDAO.addToGiftList(child, giftDescription);
            santaDAO.addToSantaTodoList(gift);
            transaction.commit();
        }
        catch(SomeException e) {
            // do something on Tx failure
            transaction.rollback();
        }
    }
}

你不能在已经由 @Transactional 调用启动了事务的方法中使用 UserTransaction。

You cannot use UserTransaction in a method having a transaction started by a @Transactional call.

Configuring the transaction timeout

你可以通过 quarkus.transaction-manager.default-transaction-timeout 属性（指定为持续时间）配置默认事务超时，该超时将适用于事务管理器管理的所有事务。

You can configure the default transaction timeout, the timeout that applies to all transactions managed by the transaction manager, via the property quarkus.transaction-manager.default-transaction-timeout, specified as a duration.

Unresolved directive in transaction.adoc - include::{includes}/duration-format-note.adoc[]

默认值为 60 秒。

The default value is 60 seconds.

Configuring transaction node name identifier

作为底层事务管理器，Narayana 有一个唯一节点标识符的概念。如果您考虑使用涉及多个资源的 XA 事务，这一点非常重要。

Narayana, as the underlying transaction manager, has a concept of a unique node identifier. This is important if you consider using XA transactions that involve multiple resources.

节点名称标识符在事务标识中发挥至关重要的作用。创建事务时，节点名称标识符将转换为事务 ID。基于节点名称标识符，事务管理器能够识别在数据库或 JMS 代理中创建的 XA 事务对等项。事务管理器可以利用该标识符在恢复期间回滚事务对等项。

The node name identifier plays a crucial part in the identification of a transaction. The node name identifier is forged into the transaction id when the transaction is created. Based on the node name identifier, the transaction manager is capable of recognizing the XA transaction counterparts created in database or JMS broker. The identifier makes possible for the transaction manager to roll back the transaction counterparts during recovery.

节点名称标识符必须在每个事务管理器部署中保持唯一。此外，在事务管理器重新启动期间，节点标识符必须保持稳定。

The node name identifier needs to be unique per transaction manager deployment. And the node identifier needs to be stable over the transaction manager restarts.

节点名称标识符可以通过属性 quarkus.transaction-manager.node-name 进行配置。

The node name identifier may be configured via the property quarkus.transaction-manager.node-name.

Using @TransactionScoped to bind CDI beans to the transaction lifecycle

您可以定义与事务生存期一样长的 Bean，并通过 CDI 生命周期事件在事务开始和结束时执行操作。

You can define beans that live for as long as a transaction, and through CDI lifecycle events perform actions when a transaction starts and ends.

只需使用 @TransactionScoped 标注将事务 scope 分配给此类 Bean：

Just assign the transaction scope to such beans using the @TransactionScoped annotation:

@TransactionScoped
public class MyTransactionScopedBean {

    // The bean's state is bound to a specific transaction,
    // and restored even after suspending then resuming the transaction.
    int myData;

    @PostConstruct
    void onBeginTransaction() {
        // This gets invoked after a transaction begins.
    }

    @PreDestroy
    void onBeforeEndTransaction() {
        // This gets invoked before a transaction ends (commit or rollback).
    }
}

或者，如果您不一定需要在事务期间保留状态，而只是想对事务开始/结束事件作出反应，则可以简单地在范围不同的 Bean 中声明事件侦听器：

Alternatively, if you don’t necessarily need to hold state during the transaction, and just want to react to transaction start/end events, you can simply declare event listeners in a differently scoped bean:

@ApplicationScoped
public class MyTransactionEventListeningBean {

    void onBeginTransaction(@Observes @Initialized(TransactionScoped.class) Object event) {
        // This gets invoked when a transaction begins.
    }

    void onBeforeEndTransaction(@Observes @BeforeDestroyed(TransactionScoped.class) Object event) {
        // This gets invoked before a transaction ends (commit or rollback).
    }

    void onAfterEndTransaction(@Observes @Destroyed(TransactionScoped.class) Object event) {
        // This gets invoked after a transaction ends (commit or rollback).
    }
}

event 对象表示事务 ID，并相应地定义 toString()/equals()/hashCode()。

The event object represents the transaction ID, and defines toString()/equals()/hashCode() accordingly.

在侦听器方法中，您可以通过访问 TransactionManager 来访问正在进行的事务的详细信息，这是一个 CDI Bean，可以 @Inject。

In listener methods, you can access more information about the transaction in progress by accessing the TransactionManager, which is a CDI bean and can be `@Inject`ed.

Configure storing of Quarkus transaction logs in a database

在持久存储不可用的云环境中（例如，当应用程序容器无法使用持久卷时），您可以通过使用 Java 数据库连接 (JDBC) 数据源将事务管理配置为将事务日志存储在数据库中。

In cloud environments where persistent storage is not available, such as when application containers are unable to use persistent volumes, you can configure the transaction management to store transaction logs in a database by using a Java Database Connectivity (JDBC) datasource.

然而，在云原生应用程序中，使用数据库存储事务日志还有其他要求。管理这些事务的 narayana-jta 扩展需要稳定的存储、一个唯一的可重复使用的节点标识符和一个稳定的 IP 地址才能正确工作。虽然 JDBC 对象存储提供稳定的存储，但用户仍然必须计划如何满足其他两个要求。

However, in cloud-native apps, using a database to store transaction logs has additional requirements. The narayana-jta extension, which manages these transactions, requires stable storage, a unique reusable node identifier, and a steady IP address to work correctly. While the JDBC object store provides a stable storage, users must still plan how to meet the other two requirements.

在您评估是否将数据库用于存储事务日志后，Quarkus 允许对 quarkus.transaction-manager.object-store.<property> 属性中包含的对象存储进行以下 JDBC 特定配置，其中 <property> 可以是：

Quarkus, after you evaluate whether using a database to store transaction logs is right for you, allows the following JDBC-specific configuration of the object store included in quarkus.transaction-manager.object-store.<property> properties, where <property> can be:

  • type (string): Configure this property to jdbc to enable usage of a Quarkus JDBC datasource for storing transaction logs. The default value is file-system.

  • datasource (string): Specify the name of the datasource for the transaction log storage. If no value is provided for the datasource property, Quarkus uses the default datasource.

  • create-table (boolean): When set to true, the transaction log table gets automatically created if it does not already exist. The default value is false.

  • drop-table (boolean): When set to true, the tables are dropped on startup if they already exist. The default value is false.

  • table-prefix (string): Specify the prefix for a related table name. The default value is quarkus_.

有关更多配置信息，请参阅 Quarkus All configuration options 参考的 Narayana JTA - Transaction manager 部分。

For more configuration information, see the Narayana JTA - Transaction manager section of the Quarkus All configuration options reference.

Additional information:

  • Create the transaction log table during the initial setup by setting the create-table property to true.

  • JDBC datasources and ActiveMQ Artemis allow the enlistment and automatically register the XAResourceRecovery.

    • JDBC datasources is part of quarkus-agroal, and it needs to use quarkus.datasource.jdbc.transactions=XA.

    • ActiveMQ Artemis is part of quarkus-pooled-jms, and it needs to use quarkus.pooled-jms.transaction=XA.

  • To ensure data integrity in case of application crashes or failures, enable the transaction crash recovery with the quarkus.transaction-manager.enable-recovery=true configuration.

为了解决 Agroal having a different view on running transaction checks 的当前已知问题，请将负责写入事务日志的数据源的事务类型设置为 disabled：

To work around the current known issue of Agroal having a different view on running transaction checks, set the datasource transaction type for the datasource responsible for writing the transaction logs to disabled:

quarkus.datasource.TX_LOG.jdbc.transactions=disabled

本示例使用 TX_LOG 作为数据源名称。

This example uses TX_LOG as the datasource name.

Why always having a transaction manager?

Does it work everywhere I want to?

Yep, it works in your Quarkus application, in your IDE, in your tests, because all of these are Quarkus applications. JTA has some bad press for some people. I don’t know why. Let’s just say that this is not your grandpa’s JTA implementation. What we have is perfectly embeddable and lean.

Does it do 2 Phase Commit and slow down my app?

No, this is an old folk tale. Let’s assume it essentially comes for free and let you scale to more complex cases involving several datasources as needed.

I don’t need transaction when I do read only operations, it’s faster.

Wrong. First off, just disable the transaction by marking your transaction boundary with @Transactional(NOT_SUPPORTED) (or NEVER or SUPPORTS depending on the semantic you want). Second, it’s again fairy tale that not using transaction is faster. The answer is, it depends on your DB and how many SQL SELECTs you are making. No transaction means the DB does have a single operation transaction context anyway. Third, when you do several SELECTs, it’s better to wrap them in a single transaction because they will all be consistent with one another. Say your DB represents your car dashboard, you can see the number of kilometers remaining and the fuel gauge level. By reading it in one transaction, they will be consistent. If you read one and the other from two different transactions, then they can be inconsistent. It can be more dramatic if you read data related to rights and access management for example.

Why do you prefer JTA vs Hibernate’s transaction management API

Managing the transactions manually via entityManager.getTransaction().begin() and friends lead to a butt ugly code with tons of try catch finally that people get wrong. Transactions are also about JMS and other database access, so one API makes more sense.

It’s a mess because I don’t know if my Jakarta Persistence persistence unit is using JTA or Resource-level Transaction

It’s not a mess in Quarkus :) Resource-level was introduced to support Jakarta Persistence in a non-managed environment. But Quarkus is both lean and a managed environment, so we can safely always assume we are in JTA mode. The end result is that the difficulties of running Hibernate ORM + CDI + a transaction manager in Java SE mode are solved by Quarkus.