Reactive Relational Database Connectivity MySQL Implementation

This project contains the MySQL implementation of the R2DBC SPI. This implementation is not intended to be used directly, but rather to be used as the backing implementation for a humane client library to delegate to. See R2DBC Homepage.

See R2DBC MySQL wiki for more information.

Spring-framework and R2DBC-SPI Compatibility

Refer to the table below to determine the appropriate version of r2dbc-mysql for your project.

spring-boot-starter-data-r2dbc	spring-data-r2dbc	r2dbc-spi	r2dbc-mysql(recommended)
3.0.* and above	3.0.* and above	1.0.0.RELEASE	io.asyncer:r2dbc-mysql:1.2.0
2.7.*	1.5.*	0.9.1.RELEASE	io.asyncer:r2dbc-mysql:0.9.7
2.6.* and below	1.4.* and below	0.8.6.RELEASE	dev.miku:r2dbc-mysql:0.8.2

Supported Features

This driver provides the following features:

• Unix domain socket.
• Compression protocols, including zstd and zlib.
• Execution of simple or batch statements without bindings.
• Execution of prepared statements with bindings.
• Reactive LOB types (e.g. BLOB, CLOB)
• All charsets from MySQL, like utf8mb4_0900_ai_ci, latin1_general_ci, utf32_unicode_520_ci, etc.
• All authentication types for MySQL, like caching_sha2_password, mysql_native_password, etc.
• General exceptions with error code and standard SQL state mappings.
• Secure connection with verification (SSL/TLS), auto-select TLS version for community and enterprise editions.
• SSL tunnel for proxy protocol of MySQL.
• Transactions with savepoint.
• Native ping can be sent via Connection.validate(ValidationDepth.REMOTE) and the lightweight ping syntax /* ping */ ....
• Extensible, e.g. extend built-in Codec(s).
• MariaDB RETURNING clause.

Version compatibility / Integration tests states

In fact, it supports lower versions, in the theory, such as 4.1, 4.0, etc.

However, Docker-certified images do not have these versions lower than 5.5.0, so tests are not integrated on these versions.

Maven

<dependency>
  <groupId>io.asyncer</groupId>
  <artifactId>r2dbc-mysql</artifactId>
  <version>1.2.0</version>
</dependency>

Gradle

Groovy DSL

dependencies {
    implementation 'io.asyncer:r2dbc-mysql:1.2.0'
}

Kotlin DSL

dependencies {
    // Maybe should to use `compile` instead of `implementation` on the lower version of Gradle.
    implementation("io.asyncer:r2dbc-mysql:1.2.0")
}

Getting Started

Here is a quick teaser of how to use R2DBC MySQL in Java:

// Notice: the query string must be URL encoded
ConnectionFactory connectionFactory = ConnectionFactories.get("r2dbcs:mysql://root:database-password-in-here@127.0.0.1:3306/r2dbc");

// Creating a Mono using Project Reactor
Mono<Connection> connectionMono = Mono.from(connectionFactory.create());

See Getting Started and Configuration Options wiki for more information.

Pooling

See r2dbc-pool.

Usage

connection.createStatement("INSERT INTO `person` (`first_name`, `last_name`) VALUES ('who', 'how')")
    .execute(); // return a Publisher include one Result

See Usage wiki for more information.

Reporting Issues

The R2DBC MySQL Implementation uses GitHub as issue tracking system to record bugs and feature requests. If you want to raise an issue, please follow the recommendations below:

• Before log a bug, please search the issue tracker to see if someone has already reported the problem.
• If the issue doesn't already exist, create a new issue.
• Please provide as much information as possible with the issue report, we like to know the version of R2DBC MySQL that you are using and JVM version.
• If you need to paste code, or include a stack trace use Markdown ``` escapes before and after your text.
• If possible try to create a test-case or project that replicates the issue. Attach a link to your code or a compressed file containing your code.

Before use

• The MySQL data fields encoded by index-based natively, get fields by an index will have better performance than get by column name.
• Each Result should be used (call getRowsUpdated or map/flatMap, even table definition), can NOT just ignore any Result, otherwise inbound stream is unable to align. (like ResultSet.close in jdbc, Result auto-close after used by once)
• The MySQL server does not actively return time zone when query DATETIME or TIMESTAMP, this driver does not attempt time zone conversion. That means should always use LocalDateTime for SQL type DATETIME or TIMESTAMP. Execute SHOW VARIABLES LIKE '%time_zone%' to get more information.
• Should not turn-on the trace log level unless debugging. Otherwise, the security information may be exposed through ByteBuf dump.
• If Statement bound returnGeneratedValues, the Result of the Statement can be called both of getRowsUpdated and map/flatMap.
  • If server is MariaDB 10.5.1 and above: the statement will attempt to use RETURNING clause, zero arguments will make the statement like ... RETURNING *.
  • Otherwise: returnGeneratedValues can only be called with one or zero arguments, and map/flatMap will emit the last inserted id.
• The MySQL may be not support well for searching rows by a binary field, like BIT and JSON
  • BIT: cannot select 'BIT(64)' with value greater than 'Long.MAX_VALUE' (or equivalent in binary)
  • JSON: different MySQL may have different serialization formats, e.g. MariaDB and MySQL
• MySQL 8.0+ disables @@global.local_infile by default, make sure @@local_infile is ON before enable allowLoadLocalInfileInPath of the driver. e.g. run SET GLOBAL local_infile=ON, or set it in mysql.cnf.

License

This project is released under version 2.0 of the Apache License.

Acknowledgements

Contributors

Thanks a lot for your support!

Supports

• R2DBC Team - Thanks for their support by sharing all relevant resources around R2DBC projects.