mssqllibR2DBC for SQL Server

Spring Boot

Use spring-boot-starter-data-r2dbc and this driver. Do not also depend on io.r2dbc:r2dbc-mssql. The sibling sample AzureTdsClient is Spring Boot 4.1.1 with WebFlux, this driver, and an Entra service principal. The GraphQL section uses that same R2DBC wiring under spring-boot-starter-graphql.

Dependencies

Versions other than this driver come from the Spring Boot parent. The exclusion lets Boot choose reactor-core. The driver itself is built against Reactor 3.8.7.

pom.xml
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-webflux</artifactId>
</dependency>
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-data-r2dbc</artifactId>
</dependency>
<dependency>
  <groupId>org.mssqllib.r2dbc.mssql</groupId>
  <artifactId>r2dbc-mssql</artifactId>
  <version>1.0.1</version>
  <exclusions>
    <exclusion>
      <groupId>io.projectreactor</groupId>
      <artifactId>reactor-core</artifactId>
    </exclusion>
  </exclusions>
</dependency>

SQL password

Host, port, and database are required in the URL. trustServerCertificate=true skips certificate checks. Omit it when the JVM already trusts the server.

application.yml
spring:
  r2dbc:
    url: "r2dbc:mssql://user:password@localhost:1433/database?trustServerCertificate=true"
    pool:
      initial-size: 0
      max-size: 4

The pool keys are Spring Boot's, not driver options. The sample starts the pool empty and caps it at 4.

DatabaseClient
record Item(Integer id, String name, String note) {}

@Service
public class ItemService {
  private final DatabaseClient databaseClient;

  public ItemService(DatabaseClient databaseClient) {
    this.databaseClient = databaseClient;
  }

  public Flux<Item> list() {
    return databaseClient.sql(
            "SELECT id, name, note FROM dbo.item ORDER BY id")
        .map(row -> new Item(
            row.get("id", Integer.class),
            row.get("name", String.class),
            row.get("note", String.class)))
        .all();
  }
}

DatabaseClient is org.springframework.r2dbc.core.DatabaseClient. dbo.item is the caller's table. Statement.returnGeneratedValues throws, so an insert that needs the new key uses OUTPUT INSERTED.id in the SQL.

With the default materializeLobs=false, do not map varchar(max), nvarchar(max), varbinary(max), or xml with String.class or byte[].class. Add the option when the mapper should keep doing that:

Materialize large values
import org.springframework.boot.r2dbc.autoconfigure.ConnectionFactoryOptionsBuilderCustomizer;

@Bean
ConnectionFactoryOptionsBuilderCustomizer materializeLobs() {
  return builder -> builder.option(TdsLibOptions.MATERIALIZE_LOBS, true);
}

Entra service principal

Put the mode on the URL. Put the client id and secret on the options builder, from the environment. The driver does not read AZURE_CLIENT_ID or AZURE_CLIENT_SECRET itself, and it has no tenant option. The STS URL arrives in FEDAUTHINFO. Do not put a JWT in spring.r2dbc.url.

application.yml
spring:
  r2dbc:
    url: "r2dbc:mssql://host:1433/database?trustServerCertificate=true&authentication=ActiveDirectoryServicePrincipal"
    pool:
      initial-size: 0
      max-size: 4
Spring Boot 4 customizer
import org.springframework.boot.r2dbc.autoconfigure.ConnectionFactoryOptionsBuilderCustomizer;

@Configuration
class R2dbcDriverConfiguration {
  @Bean
  ConnectionFactoryOptionsBuilderCustomizer fedAuth(Environment environment) {
    String clientId = environment.getRequiredProperty("AZURE_CLIENT_ID").trim();
    String clientSecret = environment.getRequiredProperty("AZURE_CLIENT_SECRET").trim();
    return builder -> {
      builder.option(TdsLibOptions.AUTHENTICATION, "ActiveDirectoryServicePrincipal");
      builder.option(TdsLibOptions.ENTRA_CLIENT_ID, clientId);
      builder.option(TdsLibOptions.ENTRA_CLIENT_SECRET, clientSecret);
    };
  }
}

On Spring Boot 3 the same interface is org.springframework.boot.autoconfigure.r2dbc.ConnectionFactoryOptionsBuilderCustomizer. A callback or tokenProvider is the same customizer, with TdsLibOptions.ACCESS_TOKEN_CALLBACK or TOKEN_PROVIDER. Those objects cannot be written into the URL.

GraphQL on WebFlux

Add spring-boot-starter-graphql next to WebFlux and the R2DBC starter. Do not add spring-boot-starter-web. With WebFlux on the classpath, Spring GraphQL serves the endpoint on the reactive stack. The default path is /graphql.

One more dependency
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-graphql</artifactId>
</dependency>
src/main/resources/graphql/schema.graphqls
type Query {
  items: [Item!]!
}

type Item {
  id: Int
  name: String
  note: String
}
Query mapping
import org.springframework.graphql.data.method.annotation.QueryMapping;

@Controller
class ItemController {
  private final DatabaseClient databaseClient;

  ItemController(DatabaseClient databaseClient) {
    this.databaseClient = databaseClient;
  }

  @QueryMapping
  Flux<Item> items() {
    return databaseClient.sql(
            "SELECT id, name, note FROM dbo.item ORDER BY id")
        .map(row -> new Item(
            row.get("id", Integer.class),
            row.get("name", String.class),
            row.get("note", String.class)))
        .all();
  }
}

@QueryMapping binds the method name items to the schema field. The SQL login URL and the Entra customizer above are unchanged. Large columns follow the same materializeLobs rule as any other DatabaseClient read.

Request
query {
  items { id name note }
}