R2DBC Proxy - R2DBC Proxying Framework

Each SPI object(Connection, Statement, Batch, Result, and Row) created by ProxyConnectionFactory is wrapped by a proxy.

When a caller invokes a method on the proxy, it triggers corresponding callback methods on the registered listeners.

Listeners are the callback implementation. Each listener implements the ProxyExecutionListener interface, which defines [before|after]Query, [before|after]Method, and eachQueryResult methods.

When triggered, these callback methods receive contextual information as a parameter. The MethodExecutionInfo is a parameter that contains the information about the invoked method, and the QueryExecutionInfo holds the information of the query execution.

Users would write a listener implementation to perform custom actions.

One of the main action performed by a listener is logging. When a listener received a callback, the passed contextual information requires a transformation to a String in order to be an entry for the logging.

Formatters are utility classes that covert MethodExecutionInfo and QueryExecutionInfo to String.

QueryExecutionInfoFormatter and MethodExecutionInfoFormatter are available out of the box to transform QueryExecutionInfo and MethodExecutionInfo, respectively.

Converters are the callbacks that could alter the original invocation.

Currently, BindParameterConverter and ResultRowConverter are available. They represent bind operations(Statement#[bind|bindNull]) and result row get operations(Row#get), respectively. The converters can change the result, call alternative methods, or even not invoke the originally called method.

Artifacts are available on Maven Central:

If you’d rather like the latest snapshots of the upcoming major version, use the Maven snapshot repository and declare the appropriate dependency version.

R2DBC Proxy supports GraalVM native-image. The proxy creation uses the JDK dynamic proxy by default. They need a configuration in the native image environment.

R2DBC proxy jar ships with the following configuration files:

The native image build automatically detects these embedded configuration files and sets up the dynamic proxy usage for R2DBC Proxy.

R2DBC specifies two types of connection factory discovery, URL-based and Programmatic. R2DBC Proxy supports both with proxy as the driver identifier.

ProxyConnectionFactory provides a builder to construct a proxy ConnectionFactory. The builder has methods to register concrete and adhoc listeners.

This is the entry point to create a ConnectionFactory proxy.

The ProxyConnectionFactory#builder static method creates a Builder instance, which provides methods to register listeners, configures the proxy, and generates a proxy ConnectionFactory.

Alternatively, the connection factory discovery can create a proxy when driver name is the proxy.

Central configuration object for creating proxies.

A ProxyConfig instance holds the proxy related configurations, such as ProxyExecutionListener, ProxyFactory, or BindParameterConverter. Any proxy objects created by a proxy ConnectionFactory share the same ProxyConfig instance.

ProxyConnectionFactory.Builder automatically creates a ProxyConfig internally. It also takes a custom ProxyConfig in case you need a customization.

Strategy interface to create each proxy.

The default proxy factory implementation(JdkProxyFactory) uses JDK dynamic proxy for creating proxy objects.

Providing a custom ProxyFactory allows different proxy mechanism for constructing proxies. For example, here is a sample code to use ByteBuddy for proxy creation.

When you have a custom ProxyFactory implementation, ProxyConfig has a method to register it.

ProxyExecutionListener is the root listener interface which defines callbacks for method invocation, query execution, and query result processing.

Anytime a caller invokes a method on a proxy, it triggers method callbacks,beforeMethod() and afterMethod(). They receive a QueryExecutionInfo parameter which contains the contextual information about the invoked method.

The query execution methods, Batch#execute() and Statement#execute(), trigger query callbacks, beforeQuery() and afterQuery(). (Specifically, it is called when returned result-publisher is subscribed.) They receive QueryExecutionInfo parameter which holds the executing query information such as the query strings, bound parameter values, duration of the query execution, etc.

While processing a Result object, eachQueryResult() receives a callback on each mapped query result at the subscription of Result#map().

When a user has a custom ProxyExecutionListener implementation, ProxyConnectionFactory.Builder has a method to register the listener. In addition, the builder provides methods to directly register adhoc listeners.

ProxyMethodExecutionListener is an extension of ProxyExecutionListener. In addition to the methods defined in ProxyExecutionListener, ProxyMethodExecutionListener has explicit before/after methods for all methods defined on ConnectionFactory, Connection, Batch, Statement, and Result.

Method names are based on the rule: "[before|after]<method-name>On<class-name>".

For example, if you want to perform an action at the creation or close of a connection:

One of the typical usages of the proxy listener is logging a contextual information. For example, when a query runs, logs the query string, parameters, success/failure result, query execution time, thread, etc.

Each callback method on ProxyExecutionListener receives contextual information - QueryExecutionInfo and MethodExecutionInfo. To perform logging, you need to transform [Method|Query]ExecutionInfo to the logging entries in a format of the String.

Formatter classes fill this gap. QueryExecutionInfoFormatter and MethodExecutionInfoFormatter are available out of the box. They provide user-friendly conversion methods, which transform selectively or all data in the [Method|Query]ExecutionInfo to a String with a default or customized format.

BindParameterConverter is a callback interface for bind parameter related operations - Statement#bind and Statement#bindNull.

The callback is performed before calling the actual bind parameter operations. This converter can change the actual behavior of the bind parameter operations. For example, a converter can transform the bind markers.

Please see more details on the "gh-26: Proxy mechanism to support converting bind marker" github issue.

ResultRowConverter is a callback interface for result row get(Row#get) operations.

The callback is performed before calling the actual Row#get operation. This converter can alter the actual behavior of the invoked Row#get method.

To use the converter, register it to the ProxyConfig.

Sample usages:

At the query executions, registered proxy listeners receive query callbacks, [before|after]Query methods with QueryExecutionInfo parameter. This parameter contains contextual information about the query execution, such as query string, execution type, bindings, execution time, etc.

With the QueryExecutionInfoFormatter, which converts QueryExecutionInfo to String, users can easily perform query logging.

There are two types of slow query detections - preemptive and non-preemptive.

The "non-preemptive" slow query detection is simple. On afterQuery callback, check the query execution time. If it took more than your threshold, perform an action such as logging, send notification, etc.

For the "preemptive" slow query detection, you may create a watcher that checks the running queries and notifies ones that have exceeded the threshold. In datasource-proxy, SlowQueryListener is implemented this way.

When a caller invokes a method on the proxy classes(ConnectionFactory, Connection, Batch, Statement, or Result), the registered listeners receive callbacks before and after the target method invocation.

By logging each contextual information of the invoked method, essentially this shows the caller’s interactions with R2DBC SPI objects.

On method or query callbacks, update the metrics with the provided contextual information.

For example:

Construct tracing spans in appropriate callbacks.

By inspecting invoked methods and/or executed queries, you can verify whether the logic you inspect has performed as expected.

For example, by keeping track of connection open/close method calls, connection leaks can be detected or verified.

Another example is to check the group of queries is executed on the same connection. This verifies the premise of the transaction - same connection needs to perform the queries in order for them to be in the same transaction.

Users can write own callback logic that performs any actions, such as audit logging, sending notifications, calling external system, etc.

To consume query results, Result#map method accepts a mapping function(BiFunction) that takes Row and RowMetadata.

The Row#get method takes a Class in the second argument to represent the returning value type(data type). R2DBC spec does not support primitive types for this data type. Only boxed(wrapper) types are supported.

ResultRowConverter can provide support for primitive types by modifying the Row#get behavior.

The following converter transforms a primitive to a corresponding wrapper data type. (e.g. row.get(0, int.class) to row.get(0, Integer.class))
Also, this converter handles null return value.

By modifying the Row#get behavior with ResultRowConverter, the following converters support column names that do not exist.

In the callbacks, ValueSource contains a reactor’s ContextView object under ContextView.class key. This provides a readonly access to the reactor context.

R2DBC Proxy has an optional dependency on Micrometer to provide Micrometer Observation support. The ObservationProxyExecutionListener creates observations for query executions.

All Micrometer Observation implementation classes are located under the io.r2dbc.proxy.observation package. Since the dependency is optional, users need to explicit add the micrometer-observation dependency.

For Spring Boot 3, a separate project, TBD, provides auto-configuration for this.