R2DBC - Reactive Relational Database Connectivity

R2DBC is an endeavor to bring a reactive programming API to relational data stores. The Introduction contains more details about its origins and will explain its goals.

This document describes the first and initial generation of R2DBC.

This document is organized in x parts:

R2DBC stands for Reactive Relational Database Connectivity. R2DBC started as experiment and proof of concept to enable integration of relational databases into systems using reactive programming models – Reactive in the sense of an event-driven, non-blocking and functional programming model that does not make assumptions over concurrency or asynchronicity. Instead, it assumes scheduling and parallelization to happen as part of the runtime scheduling.

The R2DBC SPI provides reactive programmatic access to relational databases from the Java and other JVM-based programming languages.

R2DBC specifies a service-provider interface (SPI) intended to be implemented by driver vendors and used by client libraries. Using the R2DBC SPI, applications written in a JVM programming language can execute SQL statements, and retrieve results using an underlying data source. The R2DBC SPI can also be used to interact with multiple data sources in a distributed, heterogeneous environment. R2DBC targets primarily, but is not limited to, relational databases. It aims for a range of data sources whose query and statement interface is based on SQL (or a SQL-like dialect) and represent their data in a tabular form.

A key difference between R2DBC and imperative data access SPIs is the deferred nature of execution. R2DBC is therefore based on Reactive Streams to use the concept of Publisher and Subscriber to allow non-blocking backpressure-aware data access.

This specification is targeted primarily towards:

This specification is also intended to serve the following purposes:

The R2DBC specification work is being conducted as an effort of individuals that recognized the demand for a reactive, standardized API for relational database access. We want to thank all contributing members for their countless hours of work and discussion.

Thanks also go to Ollie without whom this initiative would not even exist.

For information on R2DBC source code repositories, nightly builds, and snapshot artifacts, see the R2DBC homepage. You can help make R2DBC best serve the needs of the community by interacting with developers through the community. To follow developer activity, look for the mailing list information on the R2DBC homepage. If you encounter a bug or want to suggest an improvement, please create a ticket on the R2DBC issue tracker. R2DBC forms an open-source organization on GitHub bundling various projects (SPI, drivers) under R2DBC.

To stay up to date with the latest news and announcements in the R2DBC eco system, subscribe to the mailing list. You can also follow the project team on Twitter (@R2DBC).

The R2DBC specification aims for establishing an interface with a minimal API surface to integrate with relational databases using a reactive programming model. The most significant goals are honoring and embracing the properties of reactive programming:

R2DBC aims for seamless integration of reactive JVM platforms targeting Java as its primary platform. R2DBC should also be usable from other platforms such as Kotlin or Scala without scarifying its SPI for the sake of idiomatic use in a different platform.

R2DBC SPI strives to provide access to features that are commonly found across different vendor implementations. The goal here is providing a balance between features that are implemented in a driver and these that are better implemented in a client library.

Each database comes with its very own feature set and how these are implemented. R2DBC’s goal here is to define a minimal standard over commonly used functionality and allow for vendor-specific deviation. Drivers can implement additional functionality or make these transparent through R2DBC SPI.

The focus of R2DBC is on accessing relational data from the Java programming language using databases that provide a SQL interface to interact with.

The goal here is not to limit implementations to relational-only databases. Instead, providing guidance for uniform reactive data access using tabular data consumption patterns.

R2DBC does not aim for being a general purpose data access API.

R2DBC specializes in reactive data access and common usage patterns that result from relational data interaction. R2DBC does not aim for abstracting common functionality that needs to be re-implemented by driver vendors in a similar manner. It aims for leaving this functionality to client libraries of which there are typically fewer implementations than drivers.

R2DBC SPI aims for being primarily consumed though client library implementations.

It does not aim for being an end-user or application developer programming interface.

Having a uniform reactive relational data access SPI makes R2DBC a valuable target platform for tool vendors and application developers who want to create portable tools and applications.

The requirements for R2DBC compliance should be unambiguous and easy to identify. The R2DBC specification and the API documentation (Javadoc) clarify which features are required and which are optional.

To avoid ambiguity, we will use the following terms in the compliance section and across this specification:

The following guidelines apply to R2DBC compliance:

A driver that is compliant with the R2DBC specification must do the following:

A driver can implement optional Extensions if it is able to provide extension functionality specified by R2DBC.

R2DBC uses the Connection interface to define a logical connection API to the underlying data source. A structure of a connection depends on the actual requirements of a data source and how the driver implements these.

In a typical scenario, an application using R2DBC connects to a target data source using one of two mechanisms:

R2DBC drivers must implement the ConnectionFactory interface as a mandatory part of the SPI. Drivers can provide multiple ConnectionFactory implementations depending on the used protocol or aspects that require the use of a different ConnectionFactory implementation.

The following rules apply:

ConnectionFactory Metadata

ConnectionFactories are required to expose metadata to identify the driver (ConnectionFactory) and its capabilities. Metadata must not require a connection to a data source.

See the R2DBC SPI Specification for more details.

As part of its usage, the ConnectionFactories class attempts to load any R2DBC driver classes referenced by the ConnectionFactoryProvider interface listed in the Java Service Provider manifests available on the CLASSPATH.

Drivers must include the file META-INF/services/io.r2dbc.spi.ConnectionFactoryProvider. This file contains the name of the R2DBC driver’s implementation (or implementations) of io.r2dbc.spi.ConnectionFactoryProvider. To ensure that drivers can be loaded using this mechanism, io.r2dbc.spi.ConnectionFactoryProvider implementations are required to provide a no-argument constructor.

ConnectionFactories uses a ConnectionFactoryOptions object to lookup a matching driver using a two-step model:

ConnectionFactoryProvider implementations are required to return a boolean indicator whether they support a specific configuration represented by ConnectionFactoryOptions. Drivers must expect any plurality of Options to be configured. Drivers must report that they support a configuration only if the ConnectionFactoryProvider can provide a ConnectionFactory based on the given ConnectionFactoryOptions. Drivers should gracefully fail if a ConnectionFactory creation through ConnectionFactoryProvider.create(…) is not possible.

See the R2DBC SPI Specification for more details.

The ConnectionFactoryOptions class represents a configuration to request a ConnectionFactory from a ConnectionFactoryProvider. It represents the programmatic connection creation approach without using driver-specific classes. ConnectionFactoryOptions instances are created using the builder pattern and properties are configured through Option<T> identifiers. A ConnectionFactoryOptions is immutable once created. Option objects are reused as part of the built-in constant pool. Options are identified by a literal.

ConnectionFactoryOptions defines a set of well-known options:

The following rules apply:

See the R2DBC SPI Specification for more details.

Once a ConnectionFactory is bootstrapped, connections are obtained from the create() method.

The connection is active once it was emitted by the Publisher and must be released ("closed") once it is no longer in use.

Calling Connection.close() prepares a close handle to release the connection and its associated resources. Connections must be closed to ensure proper resource management.

See the R2DBC SPI Specification for more details.

The Statement interface defines methods for executing SQL statements. SQL statements may contain parameter bind markers for input parameters.

SQL used to create a statement can be parameterized using vendor-specific bind markers. Portability of SQL statements across R2DBC implementation is a non-goal.

Parameterized Statement objects are created by Connection objects in the same manner as non-parameterized Statements. See the the following example:

Parameter bind markers are identified by the Statement object. Parameterized statements may be cached by R2DBC implementations for resuse (e.g. for prepared statement execution).

Many database systems provide a mechanism that automatically generates a value when inserting a row. The value that is generated may or may not be unique or represent a key value depending on the executed SQL, and table definition. The method returnGeneratedValues, which can be called to retrieve the generated value, indicates to the Statement object to retrieve generated values. The method accepts a var-arg parameter to specify the column name(s) for which to return generated keys. The emitted Result exposes a column for each automatically generated value taking the column name hint into account.

When not specifying column name(s), the R2DBC driver implementation will determine the columns or value to return.

See the R2DBC SPI Specification for more details.

The Batch interface defines methods for executing SQL statements. SQL statements may not contain parameter bind markers for input parameters. A batch is created to execute multiple SQL statements for performance reasons.

Result objects are forward-only and read-only objects that allow consumption of two result types:

Results move forward from the first Row to the last one. After emitting the last row, a Result object gets invalidated and rows from the same Result object cannot be longer consumed. Rows contained in the result depend on how the underlying database materializes the results. That is, it contains the rows that satisfy the query at either the time the query is executed or as the rows are retrieved. An R2DBC driver can obtain a Result either directly or by using cursors.

Result reports the number of rows affected for SQL statements such as update for SQL Data Manipulation Language (DML) statements. The update count may be empty for statements that do not modify rows. After emitting the update count, a Result object gets invalidated and rows from the same Result object cannot be longer consumed.

The streaming nature of a result allows either consumption of tabular results or update count. Depending on how the underlying database materializes results, an R2DBC driver can lift this limitation.

A Result object is emitted for each statement result in a forward-only direction.

A Result object is most often created as the result of executing a Statement object. The Statement method execute() returns a Publisher that emits Result objects as result of statement execution.

The Result object will emit a Row for each row in the table books, containing the two columns title and author. The following sections detail how these rows and columns can be consumed.

A Row object represents a single row of tabular results.

The following methods are available on the Row interface:

Both get methods accept a column identifier that can be either the column name or the column index. Column names used as input to the get methods are case insensitive. Column names do not necessarily reflect the column names how they are in the underlying tables but rather how columns are represented (e.g. aliased) in the result.

Calling get without specifying a target type returns a suitable value representation according to Mapping of Data Types. Specifying a target type, the R2DBC driver attempts to convert the value to the target type.

When the column value in the database is SQL NULL, it may be returned to the Java application as null.

A RowMetadata object is created during tabular results consumption through Result.map(…). It is created for each row. The following example illustrates retrieval and usage using an anonymous inner class:

RowMetadata methods are used to retrieve metadata for a single or all columns.

ColumnMetadata declares methods to access column metadata on a best-effort basis. Column metadata that is available as a by-product of statement execution must be made available through ColumnMetadata. Metadata exposure requiring interaction with the database (e.g. issuing queries to information schema entities to resolve type properties) should not be exposed as methods on ColumnMetadata are expected to be non-blocking.

The following example illustrates how to consume ColumnMetadata using lambdas:

See the API specification for more details.

Categorized exceptions provide a standard mapping to common error states. An R2DBC driver should provide specific subclasses to indicate affinity with the driver. Categorized exceptions provide a standardized approach for R2DBC clients and R2DBC users to translate common exceptions into an application-specific state without the need to implement an SQLState-based exception translation resulting in more portable error-handling code.

R2DBC categorizes exceptions into two top-level categories:

This section explains how SQL-specific types are mapped to Java types. The list is nonexhaustive and should be received as a guideline for drivers. R2DBC drivers should use modern types and type descriptors to exchange data for consumption by applications and consumption by the driver. Driver implementations should implement the following type mapping and can support additional type mappings.

Vendor-specific types (such as spatial data types, structured JSON/XML data, user-defined types) are subject to vendor-specific mapping.

The R2DBC API declares default mappings for advanced data types. The following list describes data types and the interfaces to which they map:

The Wrapped interface provides a mechanism for users to access an instance of a resource which has been wrapped and for implementors to expose wrapped resources. This mechanism helps to eliminate the need to use non-standard means to access vendor-specific resources.