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.

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.

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, see Statement.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 with registerOutParameter, with the JDBC type as a name in JavaScript and TypeScript, such as "INTEGER"
  • inOutParam(value, jdbcType): an INOUT parameter, bound like param(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.

Edit this page on GitHub