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.
implementation "io.r2dbc:r2dbc-mssql:1.0.7.RELEASE"
// r2dbc:sqlserver or r2dbc:mssql
row.get("body", String.class);
row.get("payload", byte[].class);
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);
.option(TdsLibOptions.MATERIALIZE_LOBS, true)
Default, for comparison
Clob body = row.get("body", Clob.class);
Flux.from(body.stream())
.map(CharSequence::toString)
.reduce("", String::concat);
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
mssqlonly.sqlserveris rejected. The port is required. - Both jars must not be on the classpath together.
Statement.returnGeneratedValuesthrowsUnsupportedOperationException, including when the column names are null. Return keys with anOUTPUTclause in the SQL.releaseSavepointcompletes without a server call. A null or empty name throwsIllegalArgumentException. Creating a savepoint and rolling back to one are sent. With no transaction open,createSavepointturns auto-commit off and begins a transaction first.bindaccepts any index or name.bindNull(null, type)throwsNullPointerException.createStatement(null)does not throwIllegalArgumentException. A parameter set that skips a later placeholder is still sent. See known limits.- The row is not invalidated when
Result.mapreturns. 1.0.7 throws on a laterget. Portable code does not keep the row. - A positive
fetchSizeon 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.