Checks
Learn how to check what your statements produced, and save values for the next requests.
Understand JDBC checks
JDBC checks are regular Gatling checks: they support find, findAll, count, saveAs, transform, and the usual validators such as is and gt.
They run once the statement succeeded. A failing check makes the request fail.
A statement can produce several results, such as a script or a stored procedure. Each check reads the first result of its kind:
| Check | Type | Extracts |
|---|---|---|
updateCount |
multiple | The update counts, the first one with find. A batch produces one per row. |
rowCount |
single | The number of rows of the first result set. |
column(name), column(index) |
multiple | The values of a column of the first result set, one per row. |
rows |
single | All the rows of the first result set, each one as a Map of the column labels to the values. |
generatedKey, generatedKey(name), generatedKey(index) |
multiple | The values of a column of the generated keys, one per inserted row. |
outValue(index) |
single | The value of an OUT or INOUT parameter. |
Gatling only keeps the values of the rows in memory when a column or rows check needs them.
Values are the ones the driver returns with getObject, whose Java types depend on the driver, see database specifics.
Check update counts
updateCount extracts the number of rows the statement affected, for example with INSERT, UPDATE, and DELETE:
jdbc("Close orders")
.statement("UPDATE orders SET status = 'CLOSED' WHERE placed_on < CURRENT_DATE")
.check(updateCount().gt(0));
jdbc("Insert orders")
.preparedStatement("INSERT INTO orders (label) VALUES (?)")
.batch("#{rows}")
// one update count per row
.check(updateCount().findAll().saveAs("counts"));// Support coming soon
jdbc("Close orders")
.statement("UPDATE orders SET status = 'CLOSED' WHERE placed_on < CURRENT_DATE")
.check(updateCount().gt(0))
jdbc("Insert orders")
.preparedStatement("INSERT INTO orders (label) VALUES (?)")
.batch("#{rows}")
// one update count per row
.check(updateCount().findAll().saveAs("counts"))jdbc("Close orders")
.statement("UPDATE orders SET status = 'CLOSED' WHERE placed_on < CURRENT_DATE")
.check(updateCount.gt(0))
jdbc("Insert orders")
.preparedStatement("INSERT INTO orders (label) VALUES (?)")
.batch("#{rows}")
// one update count per row
.check(updateCount.findAll.saveAs("counts"))Some drivers report that a batch entry succeeded without telling how many rows it affected, with Statement.SUCCESS_NO_INFO.
updateCount.count counts them, but find and findAll fail on them, as they have no count.
Check the number of rows
rowCount extracts the number of rows of the first result set:
jdbc("Find users")
.statement("SELECT * FROM users")
.check(rowCount().gt(0));// Support coming soon
jdbc("Find users")
.statement("SELECT * FROM users")
.check(rowCount().gt(0))jdbc("Find users")
.statement("SELECT * FROM users")
.check(rowCount.gt(0))Check column values
column extracts the values of a column of the first result set, one per row, by name or by 1-based index.
The name is a Gatling Expression Language String.
Like JDBC’s findColumn, Gatling matches names exactly first, then ignoring case, as databases don’t agree on the case of unquoted names.
A wrong name fails with the list of the available columns.
jdbc("Find users")
.statement("SELECT id, email FROM users")
.check(
// the value in the first row
column("email").find().saveAs("email"),
// the values of all the rows
column("id").findAll().saveAs("userIds"),
// by index, starting at 1 like JDBC
column(1).count().gt(0),
// SQL NULLs are extracted as null
column("email").find(1).notNull()
);// Support coming soon
jdbc("Find users")
.statement("SELECT id, email FROM users")
.check(
// the value in the first row
column("email").find().saveAs("email"),
// the values of all the rows
column("id").findAll().saveAs("userIds"),
// by index, starting at 1 like JDBC
column(1).count().gt(0),
// SQL NULLs are extracted as null
column("email").find(1).notNull()
)jdbc("Find users")
.statement("SELECT id, email FROM users")
.check(
// the value in the first row
column("email").find.saveAs("email"),
// the values of all the rows
column("id").findAll.saveAs("userIds"),
// by index, starting at 1 like JDBC
column(1).count.gt(0),
// SQL NULLs are extracted as null
column("email").find(1).notNull
)Check whole rows
rows extracts all the rows of the first result set, each one as a Map of the column labels to the values, in the column order.
Save them to iterate over them with foreach:
ChainBuilder chain =
exec(
jdbc("Find users")
.statement("SELECT id, email FROM users")
.check(rows().saveAs("users"))
).foreach("#{users}", "user").on(
exec(
jdbc("Find orders")
.preparedStatement("SELECT * FROM orders WHERE user_id = ?")
.params("#{user.id}")
)
);// Support coming soon
val chain =
exec(
jdbc("Find users")
.statement("SELECT id, email FROM users")
.check(rows().saveAs("users"))
).foreach("#{users}", "user").on(
exec(
jdbc("Find orders")
.preparedStatement("SELECT * FROM orders WHERE user_id = ?")
.params("#{user.id}")
)
)val chain =
exec(
jdbc("Find users")
.statement("SELECT id, email FROM users")
.check(rows.saveAs("users"))
).foreach("#{users}", "user")(
exec(
jdbc("Find orders")
.preparedStatement("SELECT * FROM orders WHERE user_id = ?")
.params("#{user.id}")
)
)Check generated keys
generatedKey extracts the values of a column of the keys the database generated, one per inserted row.
Without argument, it extracts the first column.
It requires the statement to run with returnGeneratedKeys.
jdbc("Insert order")
.preparedStatement("INSERT INTO orders (label) VALUES (?)")
.params("#{label}")
.returnGeneratedKeys("id")
.check(generatedKey("id").saveAs("orderId"));// Support coming soon
jdbc("Insert order")
.preparedStatement("INSERT INTO orders (label) VALUES (?)")
.params("#{label}")
.returnGeneratedKeys("id")
.check(generatedKey("id").saveAs("orderId"))jdbc("Insert order")
.preparedStatement("INSERT INTO orders (label) VALUES (?)")
.params("#{label}")
.returnGeneratedKeys("id")
.check(generatedKey("id").saveAs("orderId"))Check OUT parameters
outValue extracts the value of the OUT or INOUT parameter at the given 1-based index of a callable statement:
jdbc("Count orders")
.callableStatement("{call count_orders(?, ?)}")
.params("#{userId}", outParam(java.sql.JDBCType.INTEGER))
.check(outValue(2).saveAs("orderCount"));// Support coming soon
jdbc("Count orders")
.callableStatement("{call count_orders(?, ?)}")
.params("#{userId}", outParam(java.sql.JDBCType.INTEGER))
.check(outValue(2).saveAs("orderCount"))jdbc("Count orders")
.callableStatement("{call count_orders(?, ?)}")
.params("#{userId}", outParam(java.sql.JDBCType.INTEGER))
.check(outValue(2).saveAs("orderCount"))Apply checks conditionally
checkIf only applies checks when a condition holds:
jdbc("Find user")
.preparedStatement("SELECT * FROM users WHERE id = ?")
.params("#{userId}")
.checkIf("#{mustExist}").then(rowCount().is(1));// Support coming soon
jdbc("Find user")
.preparedStatement("SELECT * FROM users WHERE id = ?")
.params("#{userId}")
.checkIf("#{mustExist}").then(rowCount().shouldBe(1))jdbc("Find user")
.preparedStatement("SELECT * FROM users WHERE id = ?")
.params("#{userId}")
.checkIf("#{mustExist}")(rowCount.is(1))