Statements
Learn how to run plain statements, prepared statements, batches, and stored procedures against your database.
Understand the kinds of statements
Use jdbc("name") to create a request, then pick the kind of statement, named after the JDBC one Gatling runs:
| Method | JDBC statement | Use it for |
|---|---|---|
statement(sql) |
java.sql.Statement |
SQL without bound parameters. |
preparedStatement(sql) |
java.sql.PreparedStatement |
SQL with ? placeholders bound with params, or run as a batch. |
callableStatement(sql) |
java.sql.CallableStatement |
Stored procedures and functions, with OUT and INOUT parameters. |
Gatling runs every statement with execute, so they accept any SQL: queries, updates, DDL, or scripts producing several results.
The name is the name of the request in the reports.
#{table} are replaced with their value in the SQL text itself, like everywhere else in Gatling.
To bind values, use a prepared statement with ? placeholders.Run a statement
statement runs SQL as is. The SQL is a Gatling Expression Language String, or a function:
/*
* 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.JDBCType;
import java.util.List;
import static io.gatling.javaapi.core.CoreDsl.*;
import static io.gatling.javaapi.jdbc.JdbcDsl.*;
class JdbcStatementsSampleJava {
{
//#statement
jdbc("Count orders").statement("SELECT COUNT(*) FROM orders");
// the SQL can be dynamic, here the name of the table
jdbc("Count rows").statement("SELECT COUNT(*) FROM #{table}");
jdbc("Count rows").statement(session -> "SELECT COUNT(*) FROM " + session.getString("table"));
//#statement
//#prepared-statement
jdbc("Find user")
.preparedStatement("SELECT * FROM users WHERE id = ? AND status = ?")
// Strings are Gatling Expression Language, other values are bound as is
.params("#{userId}", "ACTIVE");
//#prepared-statement
//#param-function
jdbc("Find next user")
.preparedStatement("SELECT * FROM users WHERE id = ?")
// computed from the Session
.params(param(session -> session.getLong("userId") + 1));
//#param-function
//#typed-params
jdbc("Insert order")
.preparedStatement("INSERT INTO orders (label, amount, placed_on, paid) VALUES (?, ?, ?, ?)")
.params(
"#{label}",
// a String converted to a BigDecimal, bound with setBigDecimal, which keeps the scale
param("#{amount}", JDBCType.DECIMAL),
// a String converted with java.sql.Date.valueOf, for example 2026-11-04
param("#{date}", JDBCType.DATE),
// a null bound with setNull and the given type
param(null, JDBCType.BOOLEAN)
);
//#typed-params
//#batch
jdbc("Insert orders")
.preparedStatement("INSERT INTO orders (label, amount) VALUES (?, ?)")
// a List of rows, each one being a List of values
.batch("#{rows}");
jdbc("Insert orders")
.preparedStatement("INSERT INTO orders (label, amount) VALUES (?, ?)")
.batch(session -> List.of(List.<Object>of("first", 10), List.<Object>of("second", 20)));
//#batch
//#generated-keys
jdbc("Insert order")
.preparedStatement("INSERT INTO orders (label) VALUES (?)")
.params("#{label}")
// the driver decides which columns to return
.returnGeneratedKeys()
.check(generatedKey().saveAs("orderId"));
jdbc("Insert order")
.preparedStatement("INSERT INTO orders (label) VALUES (?)")
.params("#{label}")
// the given columns
.returnGeneratedKeys("ID")
.check(generatedKey("ID").saveAs("orderId"));
//#generated-keys
//#callable-statement
jdbc("Transfer")
.callableStatement("{call transfer(?, ?, ?)}")
.params("#{from}", "#{to}", outParam(JDBCType.INTEGER))
// the value of the OUT parameter at index 3
.check(outValue(3).is(0));
jdbc("Increment")
.callableStatement("{call increment(?)}")
.params(inOutParam("#{counter}", JDBCType.INTEGER))
.check(outValue(1).saveAs("counter"));
//#callable-statement
}
}/*
* 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.
*/
//#statement
// Support coming soon
//#statement
//#prepared-statement
// Support coming soon
//#prepared-statement
//#param-function
// Support coming soon
//#param-function
//#typed-params
// Support coming soon
//#typed-params
//#batch
// Support coming soon
//#batch
//#generated-keys
// Support coming soon
//#generated-keys
//#callable-statement
// Support coming soon
//#callable-statement
/*
* 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.JDBCType
class JdbcStatementsSampleKotlin {
init {
//#statement
jdbc("Count orders").statement("SELECT COUNT(*) FROM orders")
// the SQL can be dynamic, here the name of the table
jdbc("Count rows").statement("SELECT COUNT(*) FROM #{table}")
jdbc("Count rows").statement { session -> "SELECT COUNT(*) FROM " + session.getString("table") }
//#statement
//#prepared-statement
jdbc("Find user")
.preparedStatement("SELECT * FROM users WHERE id = ? AND status = ?")
// Strings are Gatling Expression Language, other values are bound as is
.params("#{userId}", "ACTIVE")
//#prepared-statement
//#param-function
jdbc("Find next user")
.preparedStatement("SELECT * FROM users WHERE id = ?")
// computed from the Session
.params(param { session -> session.getLong("userId") + 1 })
//#param-function
//#typed-params
jdbc("Insert order")
.preparedStatement("INSERT INTO orders (label, amount, placed_on, paid) VALUES (?, ?, ?, ?)")
.params(
"#{label}",
// a String converted to a BigDecimal, bound with setBigDecimal, which keeps the scale
param("#{amount}", JDBCType.DECIMAL),
// a String converted with java.sql.Date.valueOf, for example 2026-11-04
param("#{date}", JDBCType.DATE),
// a null bound with setNull and the given type
param(null, JDBCType.BOOLEAN)
)
//#typed-params
//#batch
jdbc("Insert orders")
.preparedStatement("INSERT INTO orders (label, amount) VALUES (?, ?)")
// a List of rows, each one being a List of values
.batch("#{rows}")
jdbc("Insert orders")
.preparedStatement("INSERT INTO orders (label, amount) VALUES (?, ?)")
.batch { session -> listOf(listOf<Any>("first", 10), listOf<Any>("second", 20)) }
//#batch
//#generated-keys
jdbc("Insert order")
.preparedStatement("INSERT INTO orders (label) VALUES (?)")
.params("#{label}")
// the driver decides which columns to return
.returnGeneratedKeys()
.check(generatedKey().saveAs("orderId"))
jdbc("Insert order")
.preparedStatement("INSERT INTO orders (label) VALUES (?)")
.params("#{label}")
// the given columns
.returnGeneratedKeys("ID")
.check(generatedKey("ID").saveAs("orderId"))
//#generated-keys
//#callable-statement
jdbc("Transfer")
.callableStatement("{call transfer(?, ?, ?)}")
.params("#{from}", "#{to}", outParam(JDBCType.INTEGER))
// the value of the OUT parameter at index 3
.check(outValue(3).shouldBe(0))
jdbc("Increment")
.callableStatement("{call increment(?)}")
.params(inOutParam("#{counter}", JDBCType.INTEGER))
.check(outValue(1).saveAs("counter"))
//#callable-statement
}
}/*
* 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.JDBCType
import io.gatling.commons.validation._
import io.gatling.core.Predef._
import io.gatling.jdbc.Predef._
class JdbcStatementsSampleScala {
//#statement
jdbc("Count orders").statement("SELECT COUNT(*) FROM orders")
// the SQL can be dynamic, here the name of the table
jdbc("Count rows").statement("SELECT COUNT(*) FROM #{table}")
jdbc("Count rows").statement(session => s"SELECT COUNT(*) FROM ${session("table").as[String]}")
//#statement
//#prepared-statement
jdbc("Find user")
.preparedStatement("SELECT * FROM users WHERE id = ? AND status = ?")
// Strings are Gatling Expression Language, other values are bound as is
.params("#{userId}", "ACTIVE")
//#prepared-statement
//#param-function
jdbc("Find next user")
.preparedStatement("SELECT * FROM users WHERE id = ?")
// computed from the Session
.params(session => session("userId").validate[Long].map(_ + 1))
//#param-function
//#typed-params
jdbc("Insert order")
.preparedStatement("INSERT INTO orders (label, amount, placed_on, paid) VALUES (?, ?, ?, ?)")
.params(
"#{label}",
// a String converted to a BigDecimal, bound with setBigDecimal, which keeps the scale
param("#{amount}", JDBCType.DECIMAL),
// a String converted with java.sql.Date.valueOf, for example 2026-11-04
param("#{date}", JDBCType.DATE),
// a null bound with setNull and the given type
param(null, JDBCType.BOOLEAN)
)
//#typed-params
//#batch
jdbc("Insert orders")
.preparedStatement("INSERT INTO orders (label, amount) VALUES (?, ?)")
// a Seq of rows, each one being a Seq of values
.batch("#{rows}")
jdbc("Insert orders")
.preparedStatement("INSERT INTO orders (label, amount) VALUES (?, ?)")
.batch(session => Seq(Seq("first", 10), Seq("second", 20)).success)
//#batch
//#generated-keys
jdbc("Insert order")
.preparedStatement("INSERT INTO orders (label) VALUES (?)")
.params("#{label}")
// the driver decides which columns to return
.returnGeneratedKeys
.check(generatedKey.saveAs("orderId"))
jdbc("Insert order")
.preparedStatement("INSERT INTO orders (label) VALUES (?)")
.params("#{label}")
// the given columns
.returnGeneratedKeys("ID")
.check(generatedKey("ID").saveAs("orderId"))
//#generated-keys
//#callable-statement
jdbc("Transfer")
.callableStatement("{call transfer(?, ?, ?)}")
.params("#{from}", "#{to}", outParam(JDBCType.INTEGER))
// the value of the OUT parameter at index 3
.check(outValue(3).is(0))
jdbc("Increment")
.callableStatement("{call increment(?)}")
.params(inOutParam("#{counter}", JDBCType.INTEGER))
.check(outValue(1).saveAs("counter"))
//#callable-statement
}Run a prepared statement
preparedStatement binds the values of its ? placeholders, in order, with params.
Strings are Gatling Expression Language: "#{userId}" binds the value of the userId attribute, with its own type.
Other values are bound as is.
jdbc("Find user")
.preparedStatement("SELECT * FROM users WHERE id = ? AND status = ?")
// Strings are Gatling Expression Language, other values are bound as is
.params("#{userId}", "ACTIVE");// Support coming soon
jdbc("Find user")
.preparedStatement("SELECT * FROM users WHERE id = ? AND status = ?")
// Strings are Gatling Expression Language, other values are bound as is
.params("#{userId}", "ACTIVE")jdbc("Find user")
.preparedStatement("SELECT * FROM users WHERE id = ? AND status = ?")
// Strings are Gatling Expression Language, other values are bound as is
.params("#{userId}", "ACTIVE")To compute a value from the Session, pass a function: in Java and Kotlin, wrap it with param, in JavaScript, TypeScript, and Scala, pass it as is.
jdbc("Find next user")
.preparedStatement("SELECT * FROM users WHERE id = ?")
// computed from the Session
.params(param(session -> session.getLong("userId") + 1));// Support coming soon
jdbc("Find next user")
.preparedStatement("SELECT * FROM users WHERE id = ?")
// computed from the Session
.params(param { session -> session.getLong("userId") + 1 })jdbc("Find next user")
.preparedStatement("SELECT * FROM users WHERE id = ?")
// computed from the Session
.params(session => session("userId").validate[Long].map(_ + 1))Bind typed parameters
By default, Gatling binds values with setObject, and the driver infers the SQL type from the Java type.
Some databases, such as PostgreSQL, reject a String for a numeric or date column.
param(value, jdbcType) binds a value with the given java.sql.JDBCType, like JMeter’s typed parameters.
In JavaScript and TypeScript, the JDBC type is its name, such as "DECIMAL".
Gatling converts String values to the Java type matching the JDBC type, then binds them with the matching setter:
| JDBC type | String converted with | Bound with |
|---|---|---|
INTEGER, BIGINT, SMALLINT, TINYINT |
Integer.valueOf, Long.valueOf, Short.valueOf, Byte.valueOf |
setInt, setLong, setShort, setByte |
DECIMAL, NUMERIC |
new BigDecimal(...) |
setBigDecimal |
DOUBLE, FLOAT, REAL |
Double.valueOf, Float.valueOf |
setDouble, setFloat |
BOOLEAN, BIT |
true, false, 1, or 0, ignoring case |
setBoolean |
DATE, TIME, TIMESTAMP |
java.sql.Date.valueOf, Time.valueOf, Timestamp.valueOf |
setDate, setTime, setTimestamp |
CHAR, VARCHAR, LONGVARCHAR |
not converted | setString |
NCHAR, NVARCHAR, LONGNVARCHAR |
not converted | setNString |
| other types | not converted | setObject(value, type) |
A value that can’t be converted makes the request crash before anything is sent to the database. Values of other Java types aren’t converted.
jdbc("Insert order")
.preparedStatement("INSERT INTO orders (label, amount, placed_on, paid) VALUES (?, ?, ?, ?)")
.params(
"#{label}",
// a String converted to a BigDecimal, bound with setBigDecimal, which keeps the scale
param("#{amount}", JDBCType.DECIMAL),
// a String converted with java.sql.Date.valueOf, for example 2026-11-04
param("#{date}", JDBCType.DATE),
// a null bound with setNull and the given type
param(null, JDBCType.BOOLEAN)
);// Support coming soon
jdbc("Insert order")
.preparedStatement("INSERT INTO orders (label, amount, placed_on, paid) VALUES (?, ?, ?, ?)")
.params(
"#{label}",
// a String converted to a BigDecimal, bound with setBigDecimal, which keeps the scale
param("#{amount}", JDBCType.DECIMAL),
// a String converted with java.sql.Date.valueOf, for example 2026-11-04
param("#{date}", JDBCType.DATE),
// a null bound with setNull and the given type
param(null, JDBCType.BOOLEAN)
)jdbc("Insert order")
.preparedStatement("INSERT INTO orders (label, amount, placed_on, paid) VALUES (?, ?, ?, ?)")
.params(
"#{label}",
// a String converted to a BigDecimal, bound with setBigDecimal, which keeps the scale
param("#{amount}", JDBCType.DECIMAL),
// a String converted with java.sql.Date.valueOf, for example 2026-11-04
param("#{date}", JDBCType.DATE),
// a null bound with setNull and the given type
param(null, JDBCType.BOOLEAN)
)Bind NULLs
param(null, jdbcType) binds a NULL with setNull and the given type.
An untyped NULL is bound with setNull and java.sql.Types.NULL, which some drivers reject for some column types.
Use a typed NULL when your driver needs it, see database specifics.
null.Run a batch
batch runs a prepared statement once per row, with addBatch and executeBatch.
Each row is a List of values bound to the ? placeholders, in order.
A batch produces one update count per row.
jdbc("Insert orders")
.preparedStatement("INSERT INTO orders (label, amount) VALUES (?, ?)")
// a List of rows, each one being a List of values
.batch("#{rows}");
jdbc("Insert orders")
.preparedStatement("INSERT INTO orders (label, amount) VALUES (?, ?)")
.batch(session -> List.of(List.<Object>of("first", 10), List.<Object>of("second", 20)));// Support coming soon
jdbc("Insert orders")
.preparedStatement("INSERT INTO orders (label, amount) VALUES (?, ?)")
// a List of rows, each one being a List of values
.batch("#{rows}")
jdbc("Insert orders")
.preparedStatement("INSERT INTO orders (label, amount) VALUES (?, ?)")
.batch { session -> listOf(listOf<Any>("first", 10), listOf<Any>("second", 20)) }jdbc("Insert orders")
.preparedStatement("INSERT INTO orders (label, amount) VALUES (?, ?)")
// a Seq of rows, each one being a Seq of values
.batch("#{rows}")
jdbc("Insert orders")
.preparedStatement("INSERT INTO orders (label, amount) VALUES (?, ?)")
.batch(session => Seq(Seq("first", 10), Seq("second", 20)).success)batch and params can’t be combined on the same statement.
The request crashes, without sending anything, when the batch is empty.
Rows contain plain values, so they can’t contain param(...): use the Java types matching the columns, such as BigDecimal or java.sql.Timestamp.
Return generated keys
returnGeneratedKeys asks the database for the keys it generated, typically for identity columns, so you can check them with generatedKey.
It works with statements, prepared statements, and batches.
returnGeneratedKeys()lets the driver decide which columns to return, seeStatement.RETURN_GENERATED_KEYS.returnGeneratedKeys(column, columns...)returns the given columns.
jdbc("Insert order")
.preparedStatement("INSERT INTO orders (label) VALUES (?)")
.params("#{label}")
// the driver decides which columns to return
.returnGeneratedKeys()
.check(generatedKey().saveAs("orderId"));
jdbc("Insert order")
.preparedStatement("INSERT INTO orders (label) VALUES (?)")
.params("#{label}")
// the given columns
.returnGeneratedKeys("ID")
.check(generatedKey("ID").saveAs("orderId"));// Support coming soon
jdbc("Insert order")
.preparedStatement("INSERT INTO orders (label) VALUES (?)")
.params("#{label}")
// the driver decides which columns to return
.returnGeneratedKeys()
.check(generatedKey().saveAs("orderId"))
jdbc("Insert order")
.preparedStatement("INSERT INTO orders (label) VALUES (?)")
.params("#{label}")
// the given columns
.returnGeneratedKeys("ID")
.check(generatedKey("ID").saveAs("orderId"))jdbc("Insert order")
.preparedStatement("INSERT INTO orders (label) VALUES (?)")
.params("#{label}")
// the driver decides which columns to return
.returnGeneratedKeys
.check(generatedKey.saveAs("orderId"))
jdbc("Insert order")
.preparedStatement("INSERT INTO orders (label) VALUES (?)")
.params("#{label}")
// the given columns
.returnGeneratedKeys("ID")
.check(generatedKey("ID").saveAs("orderId"))Drivers don’t agree on the columns they return without names: some return the actual key under a driver-specific label, and Oracle Database returns the ROWID.
Pass the column names when you need the actual values, see database specifics.
Call a stored procedure
callableStatement calls a stored procedure or a function, with the JDBC escape syntax such as {call procedure(?, ?)} or {? = call function(?)}, or a database-specific syntax.
Its params accept, in addition to the values of a prepared statement:
outParam(jdbcType): an OUT parameter, registered withregisterOutParameter, with the JDBC type as a name in JavaScript and TypeScript, such as"INTEGER"inOutParam(value, jdbcType): an INOUT parameter, bound likeparam(value, jdbcType), then registered
jdbc("Transfer")
.callableStatement("{call transfer(?, ?, ?)}")
.params("#{from}", "#{to}", outParam(JDBCType.INTEGER))
// the value of the OUT parameter at index 3
.check(outValue(3).is(0));
jdbc("Increment")
.callableStatement("{call increment(?)}")
.params(inOutParam("#{counter}", JDBCType.INTEGER))
.check(outValue(1).saveAs("counter"));// Support coming soon
jdbc("Transfer")
.callableStatement("{call transfer(?, ?, ?)}")
.params("#{from}", "#{to}", outParam(JDBCType.INTEGER))
// the value of the OUT parameter at index 3
.check(outValue(3).shouldBe(0))
jdbc("Increment")
.callableStatement("{call increment(?)}")
.params(inOutParam("#{counter}", JDBCType.INTEGER))
.check(outValue(1).saveAs("counter"))jdbc("Transfer")
.callableStatement("{call transfer(?, ?, ?)}")
.params("#{from}", "#{to}", outParam(JDBCType.INTEGER))
// the value of the OUT parameter at index 3
.check(outValue(3).is(0))
jdbc("Increment")
.callableStatement("{call increment(?)}")
.params(inOutParam("#{counter}", JDBCType.INTEGER))
.check(outValue(1).saveAs("counter"))Check the values of OUT and INOUT parameters with outValue(index), where the index is the 1-based index of the parameter.
Gatling reads them after all the results the procedure produced.
A cursor, such as a REF_CURSOR, is read entirely, as a List of rows.
Only callable statements support OUT and INOUT parameters: preparedStatement rejects them.