Release Notes for MariaDB Connector/R2DBC 1.1.2

Overview

MariaDB Connector/R2DBC is a non-blocking interface between Java applications and MariaDB Server. MariaDB Connector/R2DBC enables the development of Java 8+ applications for MariaDB database products.

MariaDB Connector/R2DBC 1.1.2 was released on 2022-06-27. MariaDB Connector/R2DBC 1.1 is the first generally available (GA) release of MariaDB Connector/R2DBC. This release is compatible with R2DBC 0.9.1.M2 specification.

Support of the R2DBC 0.9.1 Specification

To support the new R2DBC 0.9.1 specification, the following implementations have been added or changed:

  • Support for improved bind parameter declarations

  • New Connection.beginTransaction(TransactionDefinition)

  • New NoSuchOptionException

  • Changed RowMetadata

  • New statement timeout

  • Implement SPI test kit to validate the driver with the specification (R2DBC-45)

  • Exception behavior conformed per spec (R2DBC-47)

  • Adding SQL property to R2DBC Exceptions (R2DBC-46)

  • After spec batch clarification, trailing batch should fail (R2DBC-48)

Full Implementation of JPMS Modularity

MariaDB Connector/R2DBC implements JPMS modularity when using Java 9 and later. This change improves security by hiding and protecting internal packages from reflection. This change improves performance by enabling faster detection of missing modules on startup and lighter packaging for standalone applications.

Failover and Load Balancing

Failover occurs when a connection to a primary database server fails and the connector opens up a connection to another database server. For example, server A has the current connection. After a failure (for example, server crash or network down) the connection will switch to another server, server B.

Load balancing allows load to be distributed over multiple servers. When initializing a connection or after a failed connection, the connector will attempt to connect to a host. The connection is selected randomly among the valid hosts. After a connection is made, all statements will run on that database server until the connection is closed (or fails).

For example, when creating a pool of 60 connections, each one will use a random host. With 3 master hosts, the pool will have about 20 connections to each host.

The R2DBC specification follows RFC 3986, permitting multiple hosts in connection string with format:

authority = [ userinfo "@" ] host [ ":" port ] [ "," host [ ":" port ] ]

For example:

ConnectionFactory factory = ConnectionFactories.get("r2dbc:mariadb:sequential://user:password@host:3306,host2:3302/myDB?option1=value");

Failover Behavior

Failover parameter is set (i.e., prefixing connection string with r2dbc:mariadb:[sequential|loadbalancing]://... or using HA Mode builder).

In the event of a failure, the following actions occur:

  • Connection recovery (re-establishing connection transparently)

  • Re-execute command/transaction if possible

  • During failover, the fail host address will be put on a block list (shared by JVM) for 60 seconds. MariaDB Connector/R2DBC will always avoid connecting blocked hosts first, but can retry to connect blocked hosts before 60s if all hosts are in the block list.

Re-execution

The driver will try to reconnect to any non-blocked host. If reconnection fails, an exception will be thrown with SQLState 08XXX. If using a pool, this connection will be discarded.

On successful reconnection, there will be different cases.

If the driver identifies that a command can be replayed without issue (for example, connection.validate(ValidationDepth.REMOTE) ), the driver will transparently execute the command without throwing any error.

The driver cannot transparently handle all cases. For example if the failover occurs when executing an INSERT command without a transaction, the driver cannot know that command has been received and executed on server. In those types of instances, an R2dbcTransientException will be thrown with SQLState 25S03.

transactionReplay Option

Most queries occur in transactions (ORM, for example, doesn't permit using auto-commit).

MariaDB Connector/R2DBC saves commands in transactions. When a failover occurs during a transaction, the connector can automatically reconnect and replay transactions, making failover completely transparent.

There are some limitations. The driver will buffer up commands in a transaction until an inner limit is reached. A huge command may temporarily disable transaction buffering for current transactions. Commands must be idempotent only (queries can be "re-playable").

Optimized Back Pressure Handling

MariaDB Connector/R2DBC 1.1.2 ensures back-pressure internally, and does not rely on TCP back pressure. (R2DBC-63)

Restrict Authentication Plugins Option

The new option restrictedAuth enables restricting the authentication plugins that can be used when authenticating a user.

For example, to allow using only the mysql_native_password or ed25519 plugins:

r2dbc:mariadb://root:password@localhost:3306/db?restrictedAuth=mysql_native_password,ed25519

By default, the provided plugins are: mysql_native_password, client_ed25519, auth_gssapi_client, caching_sha2_password, dialog, and mysql_clear_password.

Support for skip metadata Feature

MariaDB 10.6 Server enables skipping sending metadata when they haven't changed. This concerns SQL commands that return a result set, when using option useServerPrepStmts. Now, the server will send metadata only if they have changed (DDL change for example).

This prevents unnecessary information transiting on the network and requiring parsing.

Other Changes

  • Supports Batch cancellation (R2DBC-64)

  • Permits sharing channels through loopResources connection option.