Transactions
Learn how to run several statements in a transaction, and how Gatling keeps its connection in between.
Understand how transactions work
Outside of a transaction, each statement borrows a connection in auto-commit mode, and gives it back once over.
A transaction keeps a connection for the virtual user:
begin()borrows a connection and turns auto-commit off- every statement of the virtual user then runs on this connection, without waiting for another one
commit()orrollback()ends the transaction, and gives the connection back, even when they fail
begin, commit, and rollback are requests: Gatling reports them with their own name and response time.
The response time of begin includes waiting for a free connection.
Run a transaction
Put the statements of the transaction between begin and commit:
/*
* Copyright 2011-2026 GatlingCorp (https://gatling.io)
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import io.gatling.javaapi.core.*;
import java.sql.Connection;
import static io.gatling.javaapi.core.CoreDsl.*;
import static io.gatling.javaapi.jdbc.JdbcDsl.*;
class JdbcTransactionsSampleJava {
{
//#transaction
ChainBuilder transfer =
exec(
jdbc("Begin").begin(),
jdbc("Debit")
.preparedStatement("UPDATE accounts SET balance = balance - ? WHERE id = ?")
.params("#{amount}", "#{from}"),
jdbc("Credit")
.preparedStatement("UPDATE accounts SET balance = balance + ? WHERE id = ?")
.params("#{amount}", "#{to}"),
jdbc("Commit").commit()
);
//#transaction
//#rollback
jdbc("Rollback").rollback();
//#rollback
//#options
jdbc("Begin")
.begin()
// see Connection.setTransactionIsolation
.transactionIsolation(Connection.TRANSACTION_SERIALIZABLE)
// see Connection.setReadOnly
.readOnly();
//#options
//#group
ChainBuilder timedTransfer = group("Transfer").on(transfer);
//#group
}
}/*
* Copyright 2011-2026 GatlingCorp (https://gatling.io)
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
//#transaction
// Support coming soon
//#transaction
//#rollback
// Support coming soon
//#rollback
//#options
// Support coming soon
//#options
//#group
// Support coming soon
//#group
/*
* Copyright 2011-2026 GatlingCorp (https://gatling.io)
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import io.gatling.javaapi.core.CoreDsl.*
import io.gatling.javaapi.jdbc.JdbcDsl.*
import java.sql.Connection
class JdbcTransactionsSampleKotlin {
init {
//#transaction
val transfer =
exec(
jdbc("Begin").begin(),
jdbc("Debit")
.preparedStatement("UPDATE accounts SET balance = balance - ? WHERE id = ?")
.params("#{amount}", "#{from}"),
jdbc("Credit")
.preparedStatement("UPDATE accounts SET balance = balance + ? WHERE id = ?")
.params("#{amount}", "#{to}"),
jdbc("Commit").commit()
)
//#transaction
//#rollback
jdbc("Rollback").rollback()
//#rollback
//#options
jdbc("Begin")
.begin()
// see Connection.setTransactionIsolation
.transactionIsolation(Connection.TRANSACTION_SERIALIZABLE)
// see Connection.setReadOnly
.readOnly()
//#options
//#group
val timedTransfer = group("Transfer").on(transfer)
//#group
}
}/*
* Copyright 2011-2026 GatlingCorp (https://gatling.io)
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import java.sql.Connection
import io.gatling.core.Predef._
import io.gatling.jdbc.Predef._
class JdbcTransactionsSampleScala {
//#transaction
val transfer =
exec(
jdbc("Begin").begin(),
jdbc("Debit")
.preparedStatement("UPDATE accounts SET balance = balance - ? WHERE id = ?")
.params("#{amount}", "#{from}"),
jdbc("Credit")
.preparedStatement("UPDATE accounts SET balance = balance + ? WHERE id = ?")
.params("#{amount}", "#{to}"),
jdbc("Commit").commit()
)
//#transaction
//#rollback
jdbc("Rollback").rollback()
//#rollback
//#options
jdbc("Begin")
.begin()
// see Connection.setTransactionIsolation
.transactionIsolation(Connection.TRANSACTION_SERIALIZABLE)
// see Connection.setReadOnly
.readOnly
//#options
//#group
val timedTransfer = group("Transfer")(transfer)
//#group
}Use rollback to discard what the transaction did instead:
jdbc("Rollback").rollback();// Support coming soon
jdbc("Rollback").rollback()jdbc("Rollback").rollback()Gatling fails these requests, without sending anything to the database:
beginwhen a transaction is already opencommitorrollbackwhen no transaction is open
A statement failing inside a transaction leaves it open: it’s up to the scenario to roll it back, for example with tryMax or exitBlockOnFail.
To measure the whole transaction, put it in a group:
ChainBuilder timedTransfer = group("Transfer").on(transfer);// Support coming soon
val timedTransfer = group("Transfer").on(transfer)val timedTransfer = group("Transfer")(transfer)Configure the transaction
begin accepts the following options, that Gatling sets on the connection before turning auto-commit off:
| Option | JDBC equivalent | Description |
|---|---|---|
transactionIsolation(level) |
Connection.setTransactionIsolation |
One of the java.sql.Connection.TRANSACTION_* constants, or in JavaScript and TypeScript, the name of the level, such as "SERIALIZABLE". |
readOnly |
Connection.setReadOnly |
A hint that the transaction doesn’t write. Some drivers enforce it, others ignore it. |
jdbc("Begin")
.begin()
// see Connection.setTransactionIsolation
.transactionIsolation(Connection.TRANSACTION_SERIALIZABLE)
// see Connection.setReadOnly
.readOnly();// Support coming soon
jdbc("Begin")
.begin()
// see Connection.setTransactionIsolation
.transactionIsolation(Connection.TRANSACTION_SERIALIZABLE)
// see Connection.setReadOnly
.readOnly()jdbc("Begin")
.begin()
// see Connection.setTransactionIsolation
.transactionIsolation(Connection.TRANSACTION_SERIALIZABLE)
// see Connection.setReadOnly
.readOnlyGatling restores the previous isolation level and read-only mode of the connection when the transaction is over. Databases don’t support every isolation level, and some drivers ignore the read-only mode, see database specifics.
Understand what happens when a virtual user exits
When a virtual user exits with a transaction still open, for example on exitHere or at the end of its scenario, Gatling rolls the transaction back and gives the connection back.
When the simulation ends, Gatling aborts the connections still borrowed, so the database rolls their transactions back.
Gatling never commits a transaction you didn’t commit.