CINXE.COM

<!doctype html> <html lang="en"> <head> <title>Transactions | Ebean</title> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"> <link rel="shortcut icon" href="/images/favicon.ico"> <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto|Source+Sans+Pro|Ubuntu&display=swap"> <link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.1.0/css/all.css" integrity="sha384-lKuwvrZot6UHsBSfcMvOkWwlCMgc0TaWr+30HWe3a4ltaBwTZhyTEggF5tJv8tbt" crossorigin="anonymous"> <link rel="stylesheet" href="/css/reset3.css"> <link rel="stylesheet" href="/css/site3.css"> <link rel="stylesheet" href="/css/pygments3.css"> </head> <body> <div id="main"> <div id="banner"> <header> <nav id="top"> <h1 id="breadcrumb"> <a class="nav-logo" href="/"><img src="/images/logo-200.png" height="35"></a>  <a href="/docs">Documentation</a> / Transactions </h1> <ul> <li><a onclick="toggleTheme();" title="switch dark light theme"></a></li> </ul> </nav> </header> </div> <div class="grid grid-docs"> <aside> <nav class="side"> <ul> <li class="nav0 "> <a href="/docs/getting-started">Getting started</a> </li> <li class="nav0 "> <a href="/docs/intro">Introduction</a> </li> <li class="nav0 active"> <a class="active" href="/docs">Documentation</a> <ul> <li class="nav1 "> <a href="/docs/best-practice">Best practice</a> </li> <li class="nav1 "> <a href="/docs/query">Query</a> </li> <li class="nav1 "> <a href="/docs/persist">Persist</a> </li> <li class="nav1 active"> <a class="active" href="/docs/transactions">Transactions</a> <ul class="nav"> <li class="nav1 active"> <a class="active" href="/docs/transactions/">Introduction</a> <ul class="nav nav-scroll"> <li><a href="#transactional">@Transactional</a></li> <li><a href="#current">Transaction.current()</a></li> <li><a href="#beginTransaction">beginTransaction()</a></li> <li><a href="#end">commit(), rollback(), end()</a></li> <li><a href="#commitAndContinue">commitAndContinue()</a></li> <li><a href="#setRollbackOnly">setRollbackOnly()</a></li> <li><a href="#createTransaction">createTransaction()</a></li> <li><a href="#implicit">Implicit transactions</a></li> </ul> </li> <li class="nav1 "> <a href="/docs/transactions/batch">Batch</a> </li> <li class="nav1 "> <a href="/docs/transactions/scopes">Scopes</a> </li> <li class="nav1 "> <a href="/docs/transactions/savepoints">Savepoints</a> </li> <li class="nav1 "> <a href="/docs/transactions/spring">Spring</a> </li> <li class="nav1 "> <a href="/docs/transactions/jta">JTA</a> </li> </ul> </li> <li class="nav1 "> <a href="/docs/mapping">Mapping</a> </li> <li class="nav1 "> <a href="/docs/ddl-generation">DDL & Migrations</a> </li> <li class="nav1 "> <a href="/docs/logging">Logging</a> </li> <li class="nav1 "> <a href="/docs/testing">Testing</a> </li> <li class="nav1 "> <a href="/docs/read-replicas">Read Replicas</a> </li> <li class="nav1 "> <a href="/docs/database">Database platforms</a> </li> <li class="nav1 "> <a href="/docs/multi-database">Multiple databases</a> </li> <li class="nav1 "> <a href="/docs/kotlin">Kotlin</a> </li> <li><a href="/docs/tuning">Tuning</a></li> <li class="nav1 "> <a href="/docs/features">Features</a> </li> </ul> </li> <li class="nav0 "> <a href="/support">Getting help</a> </li> <li class="nav0 "> <a target="_blank" href="/apidoc/13">API Javadoc</a> </li> <li class="nav0 "> <a href="/videos">Videos</a> </li> <li class="nav0 "> <a href="/docs/upgrading">Upgrading</a> </li> <li class="nav0 "> <a href="/releases">Releases</a> </li> </ul> </nav> </aside> <article> <form action="https://www.google.com/search" method="get" class="inline-form"> <input type="hidden" name="as_sitesearch" value="ebean.io"> <div id="page-search"> <div class="input-group"> <input class="frm" name="q" id="searchinput" type="text" placeholder="Search... (press 's' to focus)" data-placeholder-focus="Search... (use '↑', '↓' and '⏎' to select results)" data-placeholder-blur="Search... (press 's' to focus)" autocomplete="off"> <div class="input-group-btn"> <button class="frm" type="submit"></button> </div> </div> <div id="page-search-results" style="display: none;"> <ul id="search-results-container" class="search-results"><li class=" active"><a href="/docs" title="Docs">Docs Documentation </a></li><li class="">And 101 more...</li></ul> </div> </div> </form> <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. <div class="syntax java"><div class="highlight"><pre>@Transactional public void process(OffsetDateTime startOffset) { ... customer.save(); contact.save(); } </pre></div> </div> <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>. <div class="syntax java"><div class="highlight"><pre>@Transactional public void process(OffsetDateTime startOffset) { ... Transaction txn = Transaction.current(); ... } </pre></div> </div> use <code>database.currentTransaction()</code> to return the current transaction for a given database that is typically not the default database. <div class="syntax java"><div class="highlight"><pre>Database otherDb = DB.byName("other"); Transaction txn = otherDb.currentTransaction(); </pre></div> </div> <h2 id="beginTransaction">beginTransaction()</h2> As an alternative to @Transactional 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 try with resources block to ensure that the transaction is closed if any error occurs in the block. <div class="syntax java"><div class="highlight"><pre>try (Transaction transaction = DB.beginTransaction()) { // do stuff... Customer customer = ... customer.save(); Order order = ... order.save(); transaction.commit(); } </pre></div> </div> <h4 id="kotlinUse">Kotlin transaction.use { }</h4> Kotlin <code>use</code> is used similarly to try with resources to ensure the transaction is closed. <div class="syntax kotlin"><div class="highlight"><pre>DB.beginTransaction().use { transaction -> // do stuff... val customer = ... customer.save(); val order = ... order.save(); transaction.commit() } </pre></div> </div> <h2 id="end">commit(), rollback(), end()</h2> Often with a try with resources 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. <div class="syntax java"><div class="highlight"><pre>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 } </pre></div> </div> <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 NOT 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 model.save(transaction) etc. <div class="syntax java"><div class="highlight"><pre>try (Transaction transaction = DB.getDefault().createTransaction()) { ... var customer = new QCustomer(transaction) // explicit transaction .name.eq("Rob") .findOne(); ... customer.update(transaction); // explicit transaction } </pre></div> </div> <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. <nav class="next"> <a href="https://github.com/ebean-orm/website-source/blob/master/docs/transactions/index.html"> Edit Page</a> <a href="/docs/transactions/batch" class="btn btn-info">Next: Batch</a> </nav> </article> </div> </div> <script src="https://code.jquery.com/jquery-3.4.1.slim.min.js" integrity="sha384-J6qa4849blE2+poT4WnyKhv5vZF5SrPo0iEjwBvKU7imGFAV0wwj1yYfoRSJoZ+n" crossorigin="anonymous"></script> <script src="/js/site3.js"></script> <script src="/js/search3.js"></script> <script async src="https://www.googletagmanager.com/gtag/js?id=UA-75181644-1"></script> <script> window.dataLayer = window.dataLayer || []; function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); gtag('config', 'UA-75181644-1'); </script> </body> </html>