mssqllibR2DBC for SQL Server

Compatibility mode

materializeLobs=true is the drop-in setting for code written against io.r2dbc:r2dbc-mssql. There is no option named compat, compatibility, or unrestricted. The integration suite's compat=true profile sets TdsLibOptions.MATERIALIZE_LOBS. That profile fails at startup if the driver under test is io.r2dbc:r2dbc-mssql, because that driver has no such option.

What the flag changes

With the flag off, a PLP column is a live Clob or Blob and String or byte[] reads throw. With the flag on, the driver buffers every chunk and emits the row only when the last column is in. row.get as String or byte[] then matches 1.0.7. Clob and Blob still work. They wrap the finished buffer and complete in one emission.

The URL value must be the string true. The factory uses Boolean.parseBoolean. Any other text, including yes, is false.

io.r2dbc:r2dbc-mssql
implementation "io.r2dbc:r2dbc-mssql:1.0.7.RELEASE"

// r2dbc:sqlserver or r2dbc:mssql
row.get("body", String.class);
row.get("payload", byte[].class);
mssqllib, materialized
implementation "org.mssqllib.r2dbc.mssql:r2dbc-mssql:1.0.1"

// r2dbc:mssql://host:1433/db?materializeLobs=true
row.get("body", String.class);
row.get("payload", byte[].class);
Same flag on the builder
.option(TdsLibOptions.MATERIALIZE_LOBS, true)

Default, for comparison

materializeLobs=false (default)
Clob body = row.get("body", Clob.class);
Flux.from(body.stream())
    .map(CharSequence::toString)
    .reduce("", String::concat);
materializeLobs=true
String body = row.get("body", String.class);
byte[] payload = row.get("payload", byte[].class);

Read either form inside Result.map. Ordinary varchar, nvarchar, and varbinary columns are strings or bytes in both modes. Only the max and XML path changes.

What the flag does not copy

The flag makes large-value reads line up with io.r2dbc:r2dbc-mssql. It is not a claim that every SPI call behaves the same. Auto-commit, session isolation, and lock wait are sent to the server. Statement timeout is a client deadline until the first response. Those calls are on the configuration page. These stay as they are when materializeLobs is true:

  • The driver id is mssql only. sqlserver is rejected. The port is required.
  • Both jars must not be on the classpath together.
  • Statement.returnGeneratedValues throws UnsupportedOperationException, including when the column names are null. Return keys with an OUTPUT clause in the SQL.
  • releaseSavepoint completes without a server call. A null or empty name throws IllegalArgumentException. Creating a savepoint and rolling back to one are sent. With no transaction open, createSavepoint turns auto-commit off and begins a transaction first.
  • bind accepts any index or name. bindNull(null, type) throws NullPointerException. createStatement(null) does not throw IllegalArgumentException. A parameter set that skips a later placeholder is still sent. See known limits.
  • The row is not invalidated when Result.map returns. 1.0.7 throws on a later get. Portable code does not keep the row.
  • A positive fetchSize on a single execution opens a server cursor. Zero, the default, sends the statement directly.

The substitution checklist is on the migration page. Option defaults are on the reference page.