mssql-jdbc

Microsoft JDBC Driver for SQL Server

Welcome to the Microsoft JDBC Driver for SQL Server project!

The Microsoft JDBC Driver for SQL Server is a Type 4 JDBC driver that provides database connectivity through the standard JDBC application program interfaces (APIs) available in the Java Platform, Enterprise Editions. The Driver provides access to Microsoft SQL Server and Azure SQL Database from any Java application, application server, or Java-enabled applet.

Releases can be found on the GitHub Releases page, in the Microsoft JDBC Documentation, or via Maven. Starting from preview release 12.1.0, each release contains two versions of the driver. One for use with Java 8 (jre8), and one for use with version Java 11 and above (jre11).

We hope you enjoy using the Microsoft JDBC Driver for SQL Server.

Microsoft JDBC driver for SQL Server Team

Take our survey

Let us know how you think we're doing.

Status of Most Recent Builds

Azure Pipelines (Windows)	Azure Pipelines (Linux)	Azure Pipelines (MacOS)

Announcements

What's coming next? We will look into adding a more comprehensive set of tests, improving our javadocs, and start developing the next set of features.

Get Started

Getting started with SQL Server and Java

Build

Prerequisites

• Java 11+
• Maven 3.5.0+
• An instance of SQL Server or Azure SQL Database that you can connect to.

Build the JAR files

Maven builds automatically trigger a set of verification tests to run. For these tests to pass, you will first need to add an environment variable in your system called mssql_jdbc_test_connection_properties to provide the correct connection properties for your SQL Server or Azure SQL Database instance.

To build the jar files, you must use minimum version of Java 11 with Maven. You may choose to build a jar against the JDBC 4.3 API with partial support (for use with JRE 11 or newer JRE versions) and/or a JDBC 4.2 compliant jar file (for use with JRE 8). See the support matrix for the JDBC 4.3 features that are implemented.

• Maven:

  1. If you have not already done so, add the environment variable mssql_jdbc_test_connection_properties in your system with the connection properties for your SQL Server or SQL DB instance.
  2. Run one of the commands below to build a JRE 11 and newer versions compatible jar or JRE 8 compatible jar in the \target directory.
     • Run mvn install -Pjre26. This creates JRE 26 compatible jar in \target directory built against the JDBC 4.3 API with partial support (see the support matrix). Build with JDK 26.
     • Run mvn install -Pjre25. This creates JRE 25 compatible jar in \target directory built against the JDBC 4.3 API with partial support (see the support matrix). Build with JDK 25.
     • Run mvn install -Pjre21. This creates JRE 21 compatible jar in \target directory built against the JDBC 4.3 API with partial support (see the support matrix). Build with JDK 21+.
     • Run mvn install -Pjre17. This creates JRE 17 compatible jar in \target directory built against the JDBC 4.3 API with partial support (see the support matrix). Build with JDK 17+.
     • Run mvn install -Pjre11. This creates JRE 11 compatible jar in \target directory built against the JDBC 4.3 API with partial support (see the support matrix). Build with JDK 11+.
     • Run mvn install -Pjre8. This creates JRE 8 compatible jar in \target directory which is JDBC 4.2 compliant (Build with JDK 11+).

• Gradle:

  1. If you have not already done so, add the environment variable mssql_jdbc_test_connection_properties in your system with the connection properties for your SQL Server or SQL DB instance.
  2. Run one of the commands below to build a JRE 11 and newer versions compatible jar or JRE 8 compatible jar in the \build\libs directory.
     • Run gradle build -PbuildProfile=jre26. This creates JRE 26 compatible jar in \build\libs directory built against the JDBC 4.3 API with partial support (see the support matrix). Build with JDK 26.
     • Run gradle build -PbuildProfile=jre25. This creates JRE 25 compatible jar in \build\libs directory built against the JDBC 4.3 API with partial support (see the support matrix). Build with JDK 25.
     • Run gradle build -PbuildProfile=jre21. This creates JRE 21 compatible jar in \build\libs directory built against the JDBC 4.3 API with partial support (see the support matrix). Build with JDK 21+.
     • Run gradle build -PbuildProfile=jre17. This creates JRE 17 compatible jar in \build\libs directory built against the JDBC 4.3 API with partial support (see the support matrix). Build with JDK 17+.
     • Run gradle build -PbuildProfile=jre11. This creates JRE 11 compatible jar in \build\libs directory built against the JDBC 4.3 API with partial support (see the support matrix). Build with JDK 11+.
     • Run gradle build -PbuildProfile=jre8. This creates JRE 8 compatible jar in \build\libs directory which is JDBC 4.2 compliant (Build with JDK 11+).

Resources

Documentation

API reference documentation is available in Javadocs.

This driver is documented on Microsoft Docs.

Sample Code

For samples, please see the src\sample directory.

Download the DLLs

For some features (e.g. Integrated Authentication), you may need to use the mssql-jdbc_auth-. DLL. It can be found in the package that can be downloaded from Microsoft. mssql-jdbc_auth-. can also be downloaded from Maven. For Distributed Transactions (XA), the required extended stored procedures are built into SQL Server 2017 CU16 and later and can be enabled by running EXEC sp_sqljdbc_xa_install on the server. The standalone sqljdbc_xa.dll (previously required only for SQL Server 2016 and earlier) is no longer shipped.

Download the driver

Don't want to compile anything?

We're now on the Maven Central Repository. Add the following to your POM file to get the most stable release:

	com.microsoft.sqlserver
	mssql-jdbc
	13.6.0.jre11

The driver can be downloaded from Microsoft. For driver version 12.1.0 and greater, please use the jre11 version when using Java 11 or greater, and the jre8 version when using Java 8.

To get the latest version of the driver, add the following to your POM file:

	com.microsoft.sqlserver
	mssql-jdbc
	13.6.0.jre11

Using driver as Java Module

Starting from version 7.0.0, the driver Jars (jre10 and above) will expose 'Automatic-Module' as 'com.microsoft.sqlserver.jdbc'. The supporting Jar can now be added to ModulePath to access this module.

Dependencies

This project has following dependencies:

Compile Time:

• com.azure:azure-security-keyvault-keys : Microsoft Azure Client Library For KeyVault Keys (optional)
• com.azure:azure-identity : Microsoft Azure Client Library For Identity (optional)
• org.bouncycastle:bcprov-jdk18on : Bouncy Castle Provider for Always Encrypted with secure enclaves feature with JAVA 8 only (optional)
• com.google.code.gson:gson : Gson for Always Encrypted with secure enclaves feature (optional)

Test Time:

• junit:jar : For Unit Test cases.

Dependency Tree

One can see all dependencies including Transitive Dependency by executing following command.

mvn dependency:tree

Azure Key Vault and Azure Active Directory Authentication Dependencies

Projects that require either of the two features need to explicitly declare the dependency in their pom file.

For Example: If you are using Azure Active Directory Authentication feature then you need to declare the azure-identity dependency in your project's POM file. Please see the following snippet:

	com.microsoft.sqlserver
	mssql-jdbc
	13.6.0.jre11
	compile

	com.azure
	azure-identity
	1.12.2

For Example: If you are using Azure Key Vault feature then you need to declare the azure-identity and azure-security-keyvault-keys dependencies in your project's POM file. Please see the following snippet:

	com.microsoft.sqlserver
	mssql-jdbc
	13.6.0.jre11
	compile

	com.azure
	azure-identity
	1.12.2

	com.azure
	azure-security-keyvault-keys
	4.7.3

Please note as of the v6.2.2, the way to construct a SQLServerColumnEncryptionAzureKeyVaultProvider object has changed. Please refer to this Wiki page for more information.

'useFmtOnly' connection property Dependencies

When setting 'useFmtOnly' property to 'true' for establishing a connection or creating a prepared statement, antlr-runtime dependency is required to be added in your project's POM file. Please see the following snippet:

	com.microsoft.sqlserver
	mssql-jdbc
	13.6.0.jre11

	org.antlr
	antlr4-runtime
	4.9.3

Helpful Links

Topic	Link to File
Coding Guidelines	coding-guidelines.md
Best Practices	coding-best-practices.md
Review Process	review-process.md
Security Guidelines	security.md
Changelog	CHANGELOG.md
Code of Conduct	CODE_OF_CONDUCT.md

Guidelines for Creating Pull Requests

We love contributions from the community. To help improve the quality of our code, we encourage you