<title>Transactions | Ebean</title>

<meta name="layout" content="_layout2/base-docs.html"/>

<meta name="bread1" content="Transactions" href="/docs/transactions"/>

<#assign n0_docs="active">

<#assign n1_transactions="active">

<#assign n2_transactions="active">

<h2 id="transactional">@Transactional</h2>

Annotate methods with <code>@Transactional</code> and all database queries and changes

will occur in a single transaction.

The transaction will use the <a href="/docs/intro/database/#default">default database</a>,

be put into the "thread local scope" and will commit if the methods completes successfully.

<pre content="java">

@Transactional

public void process(OffsetDateTime startOffset) {

...

customer.save();

contact.save();

}

<h2 id="current">Transaction.current()</h2>

Use <code>Transaction.current()</code> to return the current transaction from "thread local scope"

of the <a href="/docs/intro/database/#default">default database</a>.

<pre content="java">

@Transactional

public void process(OffsetDateTime startOffset) {

...

Transaction txn = Transaction.current();

...

}

use <code>database.currentTransaction()</code> to return the current transaction for a given database

that is typically not the default database.

<pre content="java">

Database otherDb = DB.byName("other");

Transaction txn = otherDb.currentTransaction();

<h2 id="beginTransaction">beginTransaction()</h2>

As an alternative to <em>@Transactional</em> we can use <code>beginTransaction()</code> to

start an explicit transaction. The transaction is put into the "thread local scope" and used

by any subsequent queries, save, delete etc.

We should use a <em>try with resources</em> block to ensure that the transaction is closed

if any error occurs in the block.

<pre content="java">

try (Transaction transaction = DB.beginTransaction()) {

// do stuff...

Customer customer = ...

customer.save();

Order order = ...

order.save();

transaction.commit();

}

<h4 id="kotlinUse">Kotlin transaction.use { }</h4>

Kotlin <code>use</code> is used similarly to <em>try with resources</em> to ensure

the transaction is closed.

<pre content="kotlin">

DB.beginTransaction().use { transaction ->

// do stuff...

val customer = ...

customer.save();

val order = ...

order.save();

transaction.commit()

}

<h2 id="end">commit(), rollback(), end()</h2>

Often with a <em>try with resources</em> block we don't need explicit calls to

<code>transaction.rollback()</code> or <code>transaction.end()</code> like the

example for <a href="#beginTransaction">beginTransaction()</a> above.

<code>rollback()</code> will rollback the transaction and commonly we use that

in a catch block.

<code>end()</code> will rollback the transaction if it has not already been committed.

We primarily use <code>end()</code> in a finally block.

<pre content="java">

Transaction transaction = DB.beginTransaction()

try {

// do stuff...

Customer customer = ...

customer.save();

Order order = ...

order.save();

transaction.commit();

} catch (SomeException e) {

transaction.rollback();

} finally {

transaction.end(); // rollback if not committed

}

<h2 id="commitAndContinue">commitAndContinue()</h2>

Occasionally in larger transactions we get to a point where we would like

to commit the changes to this point but then carry on processing with

subsequent changes potentially failing.

We use <code>transaction.commitAndContinue()</code> for this.

<h2 id="setRollbackOnly">setRollbackOnly()</h2>

We use <code>transaction.setRollbackOnly()</code> such that a transaction

will not commit but only rollback.

We can make use of this when some processing has a sort of "preview" mode where

we process changes but then do not commit. This can also be useful in some

testing scenarios.

<h2 id="createTransaction">createTransaction()</h2>

<code>database.createTransaction()</code> will create a transaction but it will

<em>NOT</em> be put in "thread local scope". We generally use this when we have

a transaction that we want to pass between threads.

For example: start a transaction, obtain a row lock, if that is successful pass the

transaction to a task to execute via a background thread.

When we use <code>createTransaction()</code> we must explicitly use the transaction

in queries and saving etc. We explicitly specify the transaction with query beans

via ... and <em>model.save(transaction)</em> etc.

<pre content="java">

try (Transaction transaction = DB.getDefault().createTransaction()) {

...

var customer = new QCustomer(transaction) // explicit transaction

.name.eq("Rob")

.findOne();

...

customer.update(transaction); // explicit transaction

}

<h2 id="implicit">Implicit transactions</h2>

When no transactions are specified explicitly Ebean will create a transaction to perform the action.

<h4>Query - read only transaction</h4>

For queries Ebean will look to use a read only transaction. If a <code>Read Only DataSource</code> has

be configured Ebean will look to use that by default.

<h4>Insert, Update, Delete</h4>

For all persist requests like save, insert, update, delete Ebean will create a transaction and perform

a <code>COMMIT</code> at the end of the operation.

<@next_edit "Batch" "/docs/transactions/batch" "/docs/transactions/index.html"/>