How to Connect JMeter to SQL Server for Performance Test using JDBC

In this SQL Server guide, I want to show database developers and SQL Server administrators how they can use Apache JMeter to connect SQL Server database for performance testing and for generating SQL workload.

Apache JMeter is a frequently used tool for performance testing for web applications and for database solutions.
For database performance testing, JMeter basically creates a database connection using appropriate JDBC driver to the target data platform, in our case SQL Server.
Then JMeter executes predefined SQL queries and SQL commands to generate required workload for database performance testing.

Database developers and SQL administrators can follow the below steps in order to connect JMeter to SQL Server database assuming that they have already access to the target SQL Server database.
First, appropriate SQL Server JDBC driver should be installed on JMeter.
Then JMeter Test Plan and its components including JDBC Connection Configuration, Thread Group, JDBC Request sampler and View Results listeners should be created.
Finally, we are ready to run our SQL queries and SQL commands on the connected SQL Server database for generating SQL workload and measure the performance of the target SQL Server instance.

Download JDBC Driver for SQL Server

You can download JDBC Driver for SQL Server by following the official link Download JDBC Driver for SQL Server

You will see "Download Microsoft JDBC Driver 12.6 for SQL Server (zip)" via URL
You may or may not use the latest version of JDBC driver, you can prefer to use a previous version of JDBC Driver for SQL Server.
But before you download the JDBC driver, please check the troubleshooting section below in this article which is pointing to JRE mismatch between JMeter and JDBC driver used.

After you download the compressed zip file, you can extract it anywhere and copy the JAR files.
Add these copied database specific connector JAR files (JDBC driver) to the lib folder of JMeter and restart the Jmeter application
You need to restart the JMeter to reflect the changes in its lib folder for recently added JDBC driver files

SQL Server JDBC driver jar files in JMeter lib folder

Create JMeter Test Plan and Related Components

At this stage we will create JMeter Test Plan, SQL Server related components of a JMeter test plan, and make required configurations for successfully connecting to a SQL Server database.

Create a new test plan within Apache JMeter tool.
You can rename it as you wish

create test plan in JMeter for SQL Server connection

Right click on Test Plan and following menu options "Add > Config Element > JDBC Connection Configuration", add the configuration item for your SQL Server JDBC connection.

JMeter JDBC Connection Configuration config element for SQL Server database connection

Here is the JDBC Connection Configuration test plan item where you can provide details for the database connection.

JMeter JDBC Connection Configuration element details

The most important part is below where the database connection configuration is done by providing database URL and credentials for SQL Server JDBC driver.

JMeter database connection configuration for SQL Server JDBC driver

Database URL for SQL Server installed on local server can be build by using the following generalized form


jdbc:sqlserver://[serverName[\instanceName][:portNumber]][;property=value[;property=value]]

You can refer to building JDBC connection guide for how to setup database URL for the SQL Server JDBC connection from JMeter.

In my scenario, I wanted to acces from JMeter to a locally installed named SQL Server instance.
Please note that named instances differ slightly from default instances for the database server name used within connection string.
In a default instance, it is enough to use the IP address, server name or even "localhost" if it is running on local server.
On the other hand, for a named instance you have to use the template "[servername\instancename]"

I used following string as my database URL to be used in SQL Server JDBC connection

jdbc:sqlserver://localhost\KODYAZ:1433

An other important note will be related with the default port 1433 used for SQL Server connection.
It is possible to configure a different port which is not common.
But especially for named instances, if default SQL Server instance is using 1433 port, named instances will be using different ports for communication.
In the troubleshooting section, below the article I will be sharing a code and referring to a SQL Server tutorial which is showing how to identify the port number used by that SQL Server instance.

On above database URL string for JDBC connection, you don't see database name. If you don't explicitly provide a target SQL Server database, the connection will be opened to the database which is configured as default database for the SQL login or SQL user on the target SQL Server instance.

If you know the database name you want to connect, you can add following string by replacing your database name instead of using "targetdatabasename"

;databaseName=targetdatabasename

This change will bring the database URL to:

jdbc:sqlserver://localhost\KODYAZ:1433;databaseName=psychology

On the same screen, JDBC Connection Configuration screen, find and fill the "Variable Name for created pool". We will reference this variable name later.
I named it as dbcon

Now create a Thread Group under the Test Plan
You can right click on Test Plan item and follow the menu options: "Add > Threads (Users) > Thread Group"

add JMeter Thread Group to SQL Server Test Plan

Then under this Thread Group add a new sampler of type JDBC Request
Follow the context menu on Thread Group: "Add > Sampler > JDBC Request"

JMeter JDBC Request sampler for SQL Server connection test

In the JDBC Request sampler, refer to the previously created JDBC Connection Configuration by using the variable name
Remember I used the variable name dbcon

variable name bound to pool

In SQL Query section, I keep the "Query Type" as "Select Statement" and paste the below SQL Select query to run on my sample database named psychology


        select top(10) * FROM [psychology].[dbo].[PsychologyGraduates]

        -- or you can simply execute below command to see current database name

        select db_name() as "current database"

SQL select query for JMeter SQL Server JDBC connection

Of course, you need to customize the SQL Select statement according to your database table.
I also preferred to limit the returned data set with 10 rows only at the beginning where I concentrated more on the setup and configuration instead of performance.

Now it is time to test the JDBC connection to SQL Server from Apache JMeter test plan.

On Thread Group, using right click open the context menu and Add > Listeners:
View Results Tree, and
View Results in Table

add JMeter listeners to see output

Execute the test plan by selecting View Results Tree from left view and click on the green triangle to Run the test plan.
If you get the green icons indicating that the test plan successfully executed, then congratulations.
But it is also possible to face with some errors. In such case you will see a red icon indicating an error or event worse "nothing" in view results listeners, that is preventing the JMeter SQL Server test plan to run smoothly.

Troubleshooting JMeter SQL Server Connection Errors

If you face problems with your test plan which is creating a JDBC connection to SQL Server database, start from beginning.
Save the test plan and close JMeter.

Using Windows Explorer, you can launch JMeter by double click on the jmeter.bat file
Run C:\My\apache-jmeter-5.6.3\bin\jmeter.bat

Then from recent test plans, open your test plan which connects to SQL Server database using JDBC connection. Run the plan.
Check the Command Prompt screen where jmeter.bat is executed

Do you see an output giving some error details?

Uncaught Exception java.lang.UnsupportedClassVersionError: com/microsoft/sqlserver/jdbc/SQLServerDriver has been compiled by a more recent version of the Java Runtime (class file version 55.0), this version of the Java Runtime only recognizes class file versions up to 52.0 in thread Thread[Thread Group 1-1,6,main]. See log file for details.

JDBC SQLServerDriver has been compiled by a more recent version of the Java Runtime

As described in error message, the solution is to use a previous version of SQL Server JDBC driver compiled with a previous version of JRE
The error is caused because JMeter is not supporting the JDBC driver's Java version.

I experienced this problem and instead of using the most recent JDBC driver version "Microsoft JDBC Driver 12.6 for SQL Server", I downloaded and used "Microsoft JDBC Driver 10.2.3 for SQL Server"

To understand which class file version maps to which JRE and to which SQL Server JDBC Driver, please refer to following resources:
https://stackoverflow.com/questions/9170832/list-of-java-class-file-format-major-version-numbers
Previous Releases
https://learn.microsoft.com/en-us/sql/connect/jdbc/release-notes-for-the-jdbc-driver?view=sql-server-ver16#previous-releases
Support Matrix
https://learn.microsoft.com/en-us/sql/connect/jdbc/microsoft-jdbc-driver-for-sql-server-support-matrix?view=sql-server-ver16#java-and-jdbc-specification-support

Remove previous SQL Server JDBC driver jar files, and copy new driver files to lib folder then restart the JMeter

You may be experiencing problems regarding port number. For example:

Response message:java.sql.SQLException: Cannot create PoolableConnectionFactory (The TCP/IP connection to the host [localhost, port 1433 has failed. Error: "[localhost: invalid IPv6 address literal. Verify the connection properties. Make sure that an instance of SQL Server is running on the host and accepting TCP/IP connections at the port. Make sure that TCP connections to the port are not blocked by a firewall.".)

Cannot create PoolableConnectionFactory TCP/IP connection to the host has failed

I checked SQL Server tutorial "Find the Port Number for SQL Server Instance" for how I can identify the port number SQL Server instance is using
When I execute given SQL query in the referenced SQL tutorial, I see that the port number in use is 59493 different than the default port 1433

find SQL Server port using SQL query

So my new Database URL string for the SQL Server JDBC connection has changed to:
jdbc:sqlserver://localhost\kodyaz:59493

The unlucky cases still continued with my test scenario and I still experienced errors when I run the test plan for SQL Server connection from Apache JMeter.
This time the error message changed to:

Response message:java.sql.SQLException: Cannot create PoolableConnectionFactory (The driver could not establish a secure connection to SQL Server by using Secure Sockets Layer (SSL) encryption. Error: "PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target". ClientConnectionId:79d8c80e-f634-406b-b8d2-ac33e3397832)

Cannot create PoolableConnectionFactory driver could not establish a secure connection to SQL Server

The solution for this JMeter error can be achieved by modifying the connection string to:
jdbc:sqlserver://localhost\kodyaz:59493;encrypt=true;trustServerCertificate=true;
simply by adding
;encrypt=true;trustServerCertificate=true;
at the end of the JDBC connection database URL

Only after this above modification, I could successfully execute the test plan and connect and execute my SQL Select statement on the target SQL Server instance using JDBC connection within Apache JMeter tool.

connect to SQL Server from JMeter and execute test plan via JDBC connection

I hope testers and developers who want to see how their applications and SQL Server databases behave under certain SQL workloads, this JMeter tutorial showing how to create a JMeter test plan and use JDBC Request sampler with JDBC Connection Configuration element helps. I expect notes during my test case related with troubleshooting JMeter connection to SQL Server databases will help JMeter users experiencing similar problems.

I can also suggest my other JMeter tutorial JMeter MongoDB Connection as a simple case for NoSQL database connections from JMeter tool if you are interested in different ways of connecting database platforms.