mssqllibR2DBC for SQL Server

Project

Source, issues, and merge requests: gitlab.com/tdslib/R2dbcMssql.

Status

Version 1.0.1 is the current release. Version 1.0.0 shipped on 20 October 2026. It passes the R2DBC SPI TCK: 34 tests, 0 failures, 0 errors, 7 skipped. See R2DBC TCK and changes since 1.0.0. Coordinates and the module name are on the installation page.

SQL username and password login and Entra federated authentication are implemented. Managed identity, Kerberos, and browser login are not. The default read path streams max and XML columns. materializeLobs=true is the compatibility setting for code written against io.r2dbc:r2dbc-mssql.

This site is the static files in docs/. GitLab Pages, on the main branch, copies those files to public/. There is no site generator. docs/CNAME is mssqllib.org.

Unit tests in src/test are loopback and codec tests. They do not open a SQL Server. Live SQL Server and Azure SQL cases are the sibling MsSqlTesting project. A Spring Boot WebFlux sample that uses this driver is AzureTdsClient. Developer notes stay in doc/notes/ and are linked from Architecture.

Changes since 1.0.0

1.0.1 keeps the same URL, driver id, SQL password login, and Entra login. These calls match the driver as of this release:

  • setAutoCommit and isAutoCommit. A mode change commits an open transaction, then sends SET IMPLICIT_TRANSACTIONS. The same mode does not round-trip. isAutoCommit is true only when that flag is on and no transaction is open.
  • setTransactionIsolationLevel sends SET TRANSACTION ISOLATION LEVEL. The session starts at read committed and changes only after the batch succeeds. beginTransaction() keeps that session level. A level on beginTransaction(TransactionDefinition) lasts for that transaction. Commit and rollback put the session level back, because a non-zero isolation byte stays for the rest of the SQL Server session.
  • setLockWaitTimeout sends SET LOCK_TIMEOUT. A negative duration is wait-forever (-1). A lock-wait on a transaction definition lasts for that transaction, then the previous session value is restored.
  • setStatementTimeout is a client deadline until the first response. Zero means no deadline. A miss cancels the exchange and fails with R2dbcTimeoutException. A timer that fires after the next statement has started does not cancel that later statement.
  • createSavepoint with no transaction open turns auto-commit off, begins a transaction, then sends the savepoint. A null or empty name fails with IllegalArgumentException before any write. releaseSavepoint of any other name still completes locally. SQL Server has no RELEASE SAVEPOINT. A null or empty release name fails the same way.
  • A statement that never calls bind runs as a SQL batch.
  • Result.map over Readable maps rows and out parameters. A filtered out-parameter segment still yields its value.
  • An unknown column name throws NoSuchElementException. An index outside the row throws IndexOutOfBoundsException.
  • Severity 15, including a syntax error, is an R2dbcBadGrammarException.
  • tinyint read as Integer or Short is 0 through 255. uniqueidentifier round-trips as java.util.UUID, using SQL Server's mixed-endian layout.
  • A streaming Clob or Blob with no subscriber leaves the shared socket readable. The high watermark pauses that value after a subscriber attaches.
  • The transport debug snapshot counts an in-flight cancel once, including a cancel that happens before the request is written.

The statements, the type rules, and the exception table are on the configuration page. Streaming reads are on the features page.

R2DBC TCK

Version 1.0.1 passes io.r2dbc.spi.test.TestKit from io.r2dbc:r2dbc-spi-test:1.0.0.RELEASE. The class is MssqlTestKit. mvn verify -Ptck runs it against a Testcontainers SQL Server. The latest run is 34 tests, 0 failures, 0 errors, and 7 skipped.

Those seven tests stay disabled in the kit. Two are unsupported generated values. The other five are argument checks where this driver still throws a different exception, or does not reject an incomplete parameter set:

  • returnGeneratedValues and returnGeneratedValuesFails. returnGeneratedValues throws UnsupportedOperationException, including when the column-name array is null. The kit expects IllegalArgumentException for a null array.
  • bindFails, bindNullFails, and createStatementFails. bind accepts an index or a name the statement does not use. bindNull(null, type) throws NullPointerException. createStatement(null) does not throw IllegalArgumentException.
  • prepareStatementWithIncompleteBatchFails and prepareStatementWithIncompleteBindingFails. The driver does not detect a parameter set that skips a later placeholder.

Known limits

These are the calls behind the seven skipped TCK tests.

  • returnGeneratedValues throws UnsupportedOperationException with the message The R2DBC-MSSQL driver does not support returnGeneratedValues. A null column-name array throws that exception. The SPI test expects IllegalArgumentException for a null array. Return the key with OUTPUT INSERTED.
  • bind and bindNull accept any index and any name. The SPI test expects a failure for an index or a name the statement does not use.
  • bindNull(null, type) throws NullPointerException. The SPI test expects IllegalArgumentException.
  • createStatement(null) does not throw IllegalArgumentException.
  • add and execute do not count placeholders in the SQL. Binding @p0 and leaving @p1 unbound is sent. After a saved parameter set, another add or execute with no new values still fails with IllegalStateException (The statement is parametrized and not all parameter values are provided).

License

The project license is The Unlicense. The text is the LICENSE file in the repository. Anyone may copy, modify, publish, use, compile, sell, or distribute the software, for any purpose.

That dedication does not cover files that already carry a Microsoft MIT copyright header:

  • src/main/java/org/mssqllib/r2dbc/mssql/packets/PacketType.java
  • src/main/java/org/mssqllib/r2dbc/mssql/packets/PacketStatus.java
  • src/main/java/org/mssqllib/r2dbc/mssql/payloads/Payload.java
  • src/main/java/org/mssqllib/r2dbc/mssql/payloads/prelogin/SqlVersion.java
  • src/main/java/org/mssqllib/r2dbc/mssql/tokens/Token.java

Code copied from the Apache-2.0 io.r2dbc driver is not public domain. This tree has no Apache-2.0 file header to name. The software is provided as is, without warranty.

Contributing

Open an issue or a merge request on tdslib/R2dbcMssql. The code is Java 17. Production sources are under src/main/java/org/mssqllib/r2dbc/mssql/.

Do not commit a password, a client secret, a certificate, a JWT, or a key log. The driver must not gain a read of AZURE_* or any other environment variable for those values. Do not add MSAL, Azure Identity, Key Vault, managed identity, or Netty.

Do not put this jar and io.r2dbc:r2dbc-mssql on one classpath in a reproducer. Both register the same service interface. The JPMS module name stays org.tdslib.r2dbc.mssql.

A change that needs a real server belongs in the sibling MsSqlTesting project, as a case, rather than as a new main in this repository. This repository's tests do not point at Azure.