Architecture
mssqllib is TDS on a JDK SocketChannel. io.r2dbc:r2dbc-mssql is TDS on Netty. There is no Netty pipeline in this driver, and the two implementations do not share code.
Where work runs
ConnectionFactory.create() subscribes on Reactor's bounded-elastic scheduler. PRELOGIN, TLS, and LOGIN7 run on that thread while the socket is still blocking. After login the driver calls enterAsyncMode(), which is what sets the channel non-blocking. Later query writes are queued as plaintext TDS and written on the selector thread.
Inbound bytes are parsed on that same read loop. A row with a streaming column is emitted at the first chunk, and the rest of the value is delivered as further reads complete. Because the parser and the queue share the read loop, a full row queue can pause the socket. A streaming value pauses only after a subscriber attaches. That is the watermark behavior on the features page. A Netty driver that aggregates the PLP into one buffer before the row exists cannot pause the server between chunks. The bytes are already local.
Why cancel can keep session TLS
Azure SQL and Force Encryption keep TLS for the whole session. AES-GCM advances the record sequence when SSLEngine.wrap runs. Encrypting a packet and then discarding the ciphertext desynchronizes the server. Local SQL Server usually negotiates encryption off after login, so the same discard looks fine there and fails on Azure.
Plaintext TDS stays on the write queue. The TLS wrapper is installed only when TLS remains after login, and it runs immediately before SocketChannel.write. A purged packet is never wrapped. A record already handed to the socket is written to completion. LOGIN7 is the exception: it is wrapped and written with a blocking write, before async mode.
That split is also why an unfinished client message is closed with IGNORE plus end-of-message, while a finished message is cancelled with Attention. The features page states the application-visible rule. The repository note Incomplete RPC Abort and Session TLS is the protocol checkpoint.
Performance
Initial testing shows roughly twice the performance of io.r2dbc:r2dbc-mssql. The stated reason is this NIO path: one selector thread, no Netty pipeline, and large values that are not copied into a single buffer before the application can read them. This repository does not contain the benchmark harness or the test conditions. Treat the factor as an initial result.
Login shape
LOGIN7 asks for TDS 7.4. The client PRELOGIN version is the product version in the prelogin payload. The driver does not advertise enhanced routing support. The server's encryption answer selects login-only TLS, session TLS, or no TLS. Byte REQUIRED, which Azure SQL returns, keeps TLS for the session. Byte OFF, usual for a local server, drops TLS after LOGIN7 and before the login acknowledgement is read. Dropping it late makes the driver treat the TDS header as a TLS record.
An Azure SQL gateway can answer with a routing target. The driver closes that socket and opens one new connection. The second hop builds a new SSLContext so the gateway session cannot resume. A second redirect fails.
Developer notes
Design notes live in doc/notes/ in the repository. They are not this manual. The links open the files on the nonblocking branch. The transport-control note still has an older paragraph that describes GracefulAbortException as sending Attention. Trust the incomplete-RPC note, and the code, for that path.
- LOB columns and the R2DBC row contract. Streaming max and XML columns, and how that differs from
io.r2dbc:r2dbc-mssql1.0.7. - Federated Authentication. Token login on a new physical connection.
- TDS Handshake and Security. PRELOGIN, TLS, and LOGIN7.
- Incomplete RPC Abort and Session TLS. IGNORE plus end-of-message, and Azure session TLS.
- Outbound pipeline error handling.
- Outbound pipeline and transport.
- Inbound pipeline.
- Client API and the outbound boundary.
- Result processing. Read the LOB note for column lifetime.
- Server cursors.
- Inner and outer flux.
- Inbound exception handling.
- Transport control plane. Older in places. See the warning above.