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.
<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.
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.
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:
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.
spring:
r2dbc:
url: "r2dbc:mssql://host:1433/database?trustServerCertificate=true&authentication=ActiveDirectoryServicePrincipal"
pool:
initial-size: 0
max-size: 4
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.
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-graphql</artifactId>
</dependency>
type Query {
items: [Item!]!
}
type Item {
id: Int
name: String
note: String
}
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.
query {
items { id name note }
}