Extra features
The default is streaming mode: materializeLobs is false. The integration suite calls that unrestricted mode (compat=false). The comparison below is with io.r2dbc:r2dbc-mssql 1.0.7, which buffers each PLP value before it emits the row.
Set materializeLobs=true when existing code needs the buffered shape. That flag is the compatibility setting. It changes the read path only. Streaming parameters, cancel of an unfinished RPC, and row lifetime stay as described here. With the flag on, a max or XML value is buffered before the row is emitted, so the per-value socket pause does not apply to that column.
Streaming reads
varchar(max), nvarchar(max), varbinary(max), xml, and the other (max) types SQL Server sends with TDS max length 65535 are each a Clob or a Blob. The row is emitted when the first chunk of the first of those columns arrives. Later chunks are onNext. io.r2dbc:r2dbc-mssql 1.0.7 keeps the row until the PLP terminator is in memory, then Clob.stream() replays that buffer.
text, ntext, and image arrive already buffered in both modes. A SQL NULL is null. There is no publisher to subscribe to.
Read columns from left to right. Columns before the first large value are already present. Take the Clob or Blob inside Result.map, and drain it before reading a column that follows it. Those later columns are not in the row yet. Result.map does not subscribe to a publisher the mapper returns, so flatten it yourself.
Flux.from(statement.execute())
.flatMap(result -> result.map((row, meta) -> {
Integer id = row.get("id", Integer.class);
Clob body = row.get("body", Clob.class);
Mono<String> text = body == null
? Mono.just("")
: Flux.from(body.stream())
.map(CharSequence::toString)
.reduce("", String::concat);
return text.map(value -> {
String tail = row.get("tail", String.class);
return new Item(id, value, tail);
});
}))
.flatMap(mono -> mono);
row.get(String.class) or row.get(byte[].class) on a live large value throws IllegalArgumentException and names Clob, Blob, or materializeLobs. ColumnMetadata.getJavaType() still reports String or ByteBuffer for those columns. Code that uses the metadata class as the class to request needs materializeLobs=true.
Clob.discard() drops the rest of a value without reading it. A short value often hides the ordering rule, because the next column is already parsed by the time application code asks for it. A large value does not.
Chunk size is not an API. On an 8000-byte TDS packet, a single-byte varchar(max) is cut at about 7924 characters on the first slice and 7988 after that. Compatibility mode returns one string for the whole value. Code that counts chunks is coupled to the mode.
Backpressure on the socket
useWatermarks defaults to true. Each Clob or Blob queues at most 128 chunks and resumes the socket at 32. At a typical 8 KB packet that high watermark is about 1 MB. The queue that carries rows uses 256 and 64. When the row queue hits its high watermark the driver pauses the socket read. The parser runs on that same read loop, so it stops. Draining the publisher down to the low watermark resumes the read.
A Clob or Blob with no subscriber keeps its chunks and leaves the socket readable, so the rest of the response can still arrive. The high watermark pauses that value only after something subscribes, including when the queue is already full and the subscriber has not requested a chunk. Draining down to 32 resumes the read.
A slow subscriber therefore bounds heap. In io.r2dbc:r2dbc-mssql 1.0.7 the server has already finished sending before the first chunk is delivered, so delayElements or request(0) only paces an in-memory replay.
Subscribing to a large column and not draining it stalls the statement. Later columns may still be absent, and row.get past the last parsed column throws Cannot read column N before it has been fully received from the network. Holding a subscribed Clob after the row mapper returns holds the connection. collectList() on rows whose large values are read later stalls, because the next row cannot start until the current value is drained inside the mapping.
Set useWatermarks=false only when that pause is unwanted. The queue is then unbounded.
Cancel stops the server
Cancelling the result while SQL Server is still sending a streamed value is a protocol cancel. The query message is already complete, so the driver sends an Attention packet and keeps the session busy until the matching completion. detectOrphanedExecutions defaults to true: if the subscriber is already gone and another row arrives, the driver sends Attention. Set it to false and the driver drops those rows locally while the server finishes the result.
Cancelling Clob.stream() or calling discard() only marks that value discarded. It does not by itself send Attention. Cancel the result subscription when the server should stop.
In 1.0.7, cancelling a Clob skips the rest of a replay after the bytes have already crossed the network. This driver can also deliver many chunks and then fail. Bytes already forwarded stay forwarded.
If the client message is still open, cancel does not send Attention. An unfinished RPC, including a Blob or Clob parameter that has not been finished, is closed with IGNORE plus end-of-message on the same packet type. Attention on an unfinished RPC has hung Azure SQL. After the server completes that close, the same session can run another statement.
Streaming parameters
A bound Blob is written as varbinary(max). A bound Clob is written as a max character value. The driver sends an unknown-length PLP header and then the publisher's chunks. It does not buffer the whole value first.
Blob payload = Blob.from(Flux.just(ByteBuffer.wrap(bytes)));
Publisher<? extends Result> insert = connection.createStatement(
"INSERT INTO dbo.document (payload) VALUES (@payload)")
.bind("payload", payload)
.execute();
If that publisher fails, the driver does not write a zero-length PLP terminator. A terminator would commit the value. It closes the unfinished RPC with IGNORE plus end-of-message, and the application receives the original failure. The session stays usable after the server's completion.
On Azure SQL the session stays encrypted. Plaintext packets sit on the write queue, and TLS wrapping happens immediately before the socket write, so a packet that is discarded is never encrypted. Wrapping and then dropping ciphertext desynchronizes that session. Local SQL Server with encryption off has no session TLS, so the same bug does not show up there.
Row lifetime
The R2DBC SPI says a Row is valid only inside the Result.map callback. This driver does not invalidate TdsRow when the callback returns. io.r2dbc:r2dbc-mssql 1.0.7 releases the row in a finally and a later get throws Value cannot be retrieved after row has been released. Code that reads the row after map returns runs here and fails on that driver. Portable code reads the row inside the callback. This difference is independent of materializeLobs.