Database Requests

A database request in Apache JMeter 6.0.0 is never one element. The connection lives in a config element and the SQL lives in a sampler, and both have to be in place before a single row moves. ## The two elements **JDBC Connection Configuration** is a Configuration Element. It carries every connection detail — `Database URL`, `JDBC Driver class`, `Username`, `Password`, `Connection Properties` — plus the pool tuning fields (`Max Number of Connections`, `Max Wait (ms)`, `Time Between Eviction Runs (ms)`, `Auto Commit`, `Transaction Isolation`, `Pool Prepared Statements`, `Preinit Pool`, `Init SQL statements separated by new line`, `Test While Idle`, `Soft Min Evictable Idle Time(ms)`, `Validation Query`). At test start it stores a pool handle under the name typed into **Variable Name for created pool**; the Apache Commons DBCP `BasicDataSource` behind it is built there and then when `Max Number of Connections` is positive, and lazily, per thread, at the shipped `0`. **JDBC Request** is a Sampler. It carries `Query Type`, `SQL Query`, `Parameter values`, `Parameter types`, `Variable Names`, `Result Variable Name`, `Query timeout (s)`, `Limit ResultSet` and `Handle ResultSet` — and one pool reference, labelled *Variable Name of Pool declared in JDBC Connection Configuration*. It has no URL, no driver and no credentials of its own. The join between them is the pool name, matched as plain text. Several samplers may name the same pool; one plan may hold several configuration elements, but each needs its own unique name — if two share one, JMeter logs `JDBC data source already defined for: <name>` and only one of them binds. ## Where the driver jar goes JMeter finds jars in two directories automatically: - `lib/` — utility jars, which is where JDBC drivers belong; - `lib/ext/` — JMeter's own components and plugins, which is *not* where a driver belongs. If you would rather not copy the jar into the installation, the `user.classpath` and `plugin_dependency_paths` properties in `jmeter.properties` add further search paths, and the Test Plan element itself has a panel that appends jars or directories to the JMeter loader's search path. Two traps sit here. JMeter only picks up `.jar` files, never `.zip`. And exporting `CLASSPATH` does nothing at all, because `bin/jmeter` starts the JVM with `java -jar`, and the `java` command silently ignores both `CLASSPATH` and `-cp` when `-jar` is used. ## What the failures look like | Symptom | Cause | |---|---| | Sample fails, response data `No pool found named: 'reportingDb', ensure Variable Name matches...` | The sampler's pool field and the configuration's Variable Name differ | | Sample fails with a `ClassNotFoundException` for the driver class | The vendor jar is missing from `lib/` (or is a `.zip`, or was added only to `CLASSPATH`) | | Only one of two configuration elements works | Both were given the same Variable Name; JMeter logged `JDBC data source already defined for:` | | Sample fails carrying an SQLState and a vendor error code | The connection was obtained but the database rejected the statement or the credentials | The last row is worth internalising: when the driver throws, the JDBC Request sampler puts the driver's SQLState plus its vendor error code into the sample's response code and the exception text into the response message, so a JTL row from a failed database sample carries the database's own diagnosis rather than an HTTP-style code. ## A first-run checklist 1. Copy the vendor driver jar into `lib/` and restart JMeter — the classpath is read at startup. 2. Add a JDBC Connection Configuration and give **Variable Name for created pool** a name you will not reuse. 3. Fill `Database URL` and `JDBC Driver class`; JMeter offers a preconfigured list of driver class names, populated from the `jdbc.config.jdbc.driver.class` property. 4. Add a JDBC Request under the same thread group and paste the *same* pool name into its pool field. 5. Type the SQL with **no trailing semi-colon** — the manual is explicit about that. 6. Run one thread once and read the response data before you scale anything up. One ordering detail catches people later: the configuration element resolves its fields once, at test start, rather than per iteration. Whether it also *builds* a pool then depends on `Max Number of Connections` — a positive value builds the shared pool at test start; the shipped `0` stores a placeholder and each thread's own single-connection pool is built lazily, on that thread's first JDBC Request. And the config element's `Password` field is stored unencrypted in the `.jmx`, which the manual says outright — worth knowing before a plan with real credentials lands in a repository.