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:
setAutoCommitandisAutoCommit. A mode change commits an open transaction, then sendsSET IMPLICIT_TRANSACTIONS. The same mode does not round-trip.isAutoCommitis true only when that flag is on and no transaction is open.setTransactionIsolationLevelsendsSET TRANSACTION ISOLATION LEVEL. The session starts at read committed and changes only after the batch succeeds.beginTransaction()keeps that session level. A level onbeginTransaction(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.setLockWaitTimeoutsendsSET 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.setStatementTimeoutis a client deadline until the first response. Zero means no deadline. A miss cancels the exchange and fails withR2dbcTimeoutException. A timer that fires after the next statement has started does not cancel that later statement.createSavepointwith no transaction open turns auto-commit off, begins a transaction, then sends the savepoint. A null or empty name fails withIllegalArgumentExceptionbefore any write.releaseSavepointof any other name still completes locally. SQL Server has noRELEASE SAVEPOINT. A null or empty release name fails the same way.- A statement that never calls
bindruns as a SQL batch. Result.mapoverReadablemaps rows and out parameters. A filtered out-parameter segment still yields its value.- An unknown column name throws
NoSuchElementException. An index outside the row throwsIndexOutOfBoundsException. - Severity 15, including a syntax error, is an
R2dbcBadGrammarException. tinyintread asIntegerorShortis 0 through 255.uniqueidentifierround-trips asjava.util.UUID, using SQL Server's mixed-endian layout.- A streaming
CloborBlobwith 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:
returnGeneratedValuesandreturnGeneratedValuesFails.returnGeneratedValuesthrowsUnsupportedOperationException, including when the column-name array is null. The kit expectsIllegalArgumentExceptionfor a null array.bindFails,bindNullFails, andcreateStatementFails.bindaccepts an index or a name the statement does not use.bindNull(null, type)throwsNullPointerException.createStatement(null)does not throwIllegalArgumentException.prepareStatementWithIncompleteBatchFailsandprepareStatementWithIncompleteBindingFails. 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.
returnGeneratedValuesthrowsUnsupportedOperationExceptionwith the messageThe R2DBC-MSSQL driver does not support returnGeneratedValues.A null column-name array throws that exception. The SPI test expectsIllegalArgumentExceptionfor a null array. Return the key withOUTPUT INSERTED.bindandbindNullaccept 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)throwsNullPointerException. The SPI test expectsIllegalArgumentException.createStatement(null)does not throwIllegalArgumentException.addandexecutedo not count placeholders in the SQL. Binding@p0and leaving@p1unbound is sent. After a saved parameter set, anotheraddorexecutewith no new values still fails withIllegalStateException(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.javasrc/main/java/org/mssqllib/r2dbc/mssql/packets/PacketStatus.javasrc/main/java/org/mssqllib/r2dbc/mssql/payloads/Payload.javasrc/main/java/org/mssqllib/r2dbc/mssql/payloads/prelogin/SqlVersion.javasrc/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.