• Stars
    star
    114
  • Rank 308,031 (Top 7 %)
  • Language
    Java
  • License
    Apache License 2.0
  • Created almost 5 years ago
  • Updated 5 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Connector for Java R2DBC

MariaDB R2DBC connector

Maven Central Test Build License codecov

Non-blocking MariaDB and MySQL client.

MariaDB and MySQL client, 100% Java, compatible with Java8+, apache 2.0 licensed.

  • Driver permits ed25519, PAM authentication that comes with MariaDB.
  • use MariaDB 10.5 returning fonction to permit Statement.returnGeneratedValues

Driver follow R2DBC 1.0.0 specifications

Documentation

See documentation for native or with Spring Data R2DBC use.

Quick Start

The MariaDB Connector is available through maven using :

    <dependency>
        <groupId>org.mariadb</groupId>
        <artifactId>r2dbc-mariadb</artifactId>
        <version>1.1.4</version>
    </dependency>

Factory can be created using ConnectionFactory or using connection URL.

Using builder

MariadbConnectionConfiguration conf = MariadbConnectionConfiguration.builder()
            .host("localhost")
            .port(3306)
            .username("myUser")
            .password("MySuperPassword")
            .database("db")
            .build();
MariadbConnectionFactory factory = new MariadbConnectionFactory(conf);

//OR

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

Basic example:

    MariadbConnectionConfiguration conf = MariadbConnectionConfiguration.builder()
            .host("localhost")
            .port(3306)
            .username("myUser")
            .password("MySuperPassword")
            .database("db")
            .build();
    MariadbConnectionFactory factory = new MariadbConnectionFactory(conf);

    MariadbConnection connection = factory.create().block();
    connection.createStatement("SELECT * FROM myTable WHERE val = ?")
            .bind(0, "myVal") // setting parameter
            .execute()
            .flatMap(r -> r.map((row, metadata) -> {
              return "value=" + row.get(0, String.class);
            }));
    connection.close().subscribe();

Connection options

option description type default
username User to access database. string
password User password. string
host IP address or DNS of the database server. Multiple host can be set, separate by comma. If first host is not reachable (timeout is connectTimeout), driver use next hosts.Not used when using option socketPath. string "localhost"
port Database server port number. Not used when using option socketPath integer 3306
database Default database to use when establishing the connection. string
connectTimeout Sets the connection timeout Duration 10s
socketTimeout Sets the socket timeout Duration
tcpKeepAlive Sets socket keep alive Boolean false
tcpAbortiveClose This option can be used in environments where connections are created and closed in rapid succession. Often, it is not possible to create a socket in such an environment after a while, since all local “ephemeral” ports are used up by TCP connections in TCP_WAIT state. Using tcpAbortiveClose works around this problem by resetting TCP connections (abortive or hard close) rather than doing an orderly close. boolean false
socket Permits connections to the database through the Unix domain socket for faster connection whe server is local. string
allowMultiQueries Allows you to issue several SQL statements in a single call. (That is, INSERT INTO a VALUES('b'); INSERT INTO c VALUES('d');).

This may be a security risk as it allows for SQL Injection attacks.
boolean false
connectionAttributes When performance_schema is active, permit to send server some client information.
Those information can be retrieved on server within tables performance_schema.session_connect_attrs and performance_schema.session_account_connect_attrs. This can permit from server an identification of client/application per connection
Map<String,String>
sessionVariables Permits to set session variables upon successful connection Map<String,String>
tlsProtocol Force TLS/SSL protocol to a specific set of TLS versions (example "TLSv1.2", "TLSv1.3"). List java default
serverSslCert Permits providing server's certificate in DER form, or server's CA certificate.
This permits a self-signed certificate to be trusted. Can be used in one of 3 forms :
  • serverSslCert=/path/to/cert.pem (full path to certificate)
  • serverSslCert=classpath:relative/cert.pem (relative to current classpath)
  • as verbatim DER-encoded certificate string "------BEGIN CERTIFICATE-----"
String
clientSslCert Permits providing client's certificate in DER form (use only for mutual authentication). Can be used in one of 3 forms :
  • clientSslCert=/path/to/cert.pem (full path to certificate)
  • clientSslCert=classpath:relative/cert.pem (relative to current classpath)
  • as verbatim DER-encoded certificate string "------BEGIN CERTIFICATE-----"
String
clientSslKey client private key path(for mutual authentication) String
clientSslPassword client private key password charsequence
sslMode ssl requirement. Possible value are
  • DISABLE, // NO SSL
  • TRUST, // Encryption, but no certificate and hostname validation (DEVELOPMENT ONLY)
  • VERIFY_CA, // Encryption, certificates validation, BUT no hostname validation
  • VERIFY_FULL, // Standard SSL use: Encryption, certificate validation and hostname validation
  • TUNNEL, // Connect over a pre-created SSL tunnel. See sslContextBuilderCustomizer options and sslTunnelDisableHostVerification
SslMode DISABLE
rsaPublicKey only for MySQL server
Server RSA public key, for SHA256 authentication
String
cachingRsaPublicKey only for MySQL server
Server caching RSA public key, for cachingSHA256 authentication
String
allowPublicKeyRetrieval only for MySQL server
Permit retrieved Server RSA public key from server. This can create a security issue
boolean true
allowPipelining Permit to send queries to server without waiting for previous query to finish boolean true
useServerPrepStmts Permit to indicate to use text or binary protocol for query with parameter boolean false
prepareCacheSize if useServerPrepStmts = true, cache the prepared informations in a LRU cache to avoid re-preparation of command. Next use of that command, only prepared identifier and parameters (if any) will be sent to server. This mainly permit for server to avoid reparsing query. int 256
pamOtherPwd Permit to provide additional password for PAM authentication with multiple authentication step. If multiple passwords, value must be URL encoded. string
autocommit Set default autocommit value on connection initialization" boolean true
tinyInt1isBit Convert Bit(1)/TINYINT(1) default to boolean type boolean true
restrictedAuth if set, restrict authentication plugin to secure list. Default provided plugins are mysql_native_password, mysql_clear_password, client_ed25519, dialog, sha256_password and caching_sha2_password string
loopResources permits to share netty EventLoopGroup among multiple async libraries/framework LoopResources
sslContextBuilderCustomizer Permits to customized SSL context builder. UnaryOperator
sslTunnelDisableHostVerification Disable hostname verification during SSLHandshake when SslMode.TUNNEL is set boolean

Failover

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 (server crash, network down …) the connection will switch to another 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. Thereafter, all statements will run on that database server until the connection will be closed (or fails). 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.

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

Failover behaviour

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

There can be multiple fail causes. When a failure occurs many things will be done:

  • connection recovery (re-establishing connection transparently)
  • re-execute command/transaction if possible

During failover, the fail host address will be put on a blacklist (shared by JVM) for 60 seconds. Connector will always try to connect non blacklisted host first, but can retry to connect blacklisted host before 60s if all hosts are blacklisted.

re-execution

The driver will try to reconnect to any valid host (not blasklisted, or if all primary host are blacklisted trying blacklisted hosts). If reconnection fail, an Exception with be thrown with SQLState "08XXX". If using a pool, this connection will be discarded.

on successful reconnection, there will be different cases.

If driver identify that command can be replayed without issue (for example connection.isValid(), a PREPARE/ROLLBACK command), driver will execute command without throwing any error.

Driver cannot transparently handle all cases : imagine that the failover occurs when executing an INSERT command without a transaction: driver cannot know that command has been received and executed on server. In those case, an SQLException with be thrown with SQLState "25S03".

Option transactionReplay :

Most of the time, queries occurs in transaction (ORM for example doesn't permit using auto-commit), so redo transaction implementation will solve most of failover cases transparently for user point of view.

Redo transaction approach is to save commands in transaction. When a failover occurs during a transaction, the connector can automatically reconnect and replay transaction, making failover completely transparent.

There is some limitations :

driver will buffer up commands in a transaction until some inner limit. huge command will temporarily disable transaction buffering for current transaction. Commands must be idempotent only (queries can be "replayable")

Tracker

To file an issue or follow the development, see JIRA.

More Repositories

1

MaxScale

An intelligent database proxy.
C++
1,374
star
2

mariadb-connector-nodejs

MariaDB Connector/Node.js is used to connect applications developed on Node.js to MariaDB and MySQL databases. MariaDB Connector/Node.js is LGPL licensed.
JavaScript
366
star
3

mariadb-connector-j

MariaDB Connector/J is used to connect applications developed in Java to MariaDB and MySQL databases. MariaDB Connector/J is LGPL licensed.
Java
330
star
4

mariadb-connector-c

MariaDB Connector/C is used to connect applications developed in C/C++ to MariaDB and MySQL databases.The client library is LGPL licensed.
C
277
star
5

mariadb-connector-python

MariaDB Connector/Python
Python
131
star
6

mariadb-columnstore-engine

Core storage engine - UM and PM Process code
C++
106
star
7

mariadb-connector-cpp

MariaDB Connector for C++
C++
78
star
8

mariadb-columnstore-server

Modified version of MariaDB for ColumnStore
C++
62
star
9

mariadb-connector-odbc

MariaDB Connector ODBC. A driver which enables ODBC applications to communicate with MariaDB and MySQL servers
C
47
star
10

maxscale-docker

Shell
39
star
11

Developer-Examples

This repository contains samples applications demonstrating the power of MariaDB!
36
star
12

dev-example-todo

JavaScript
20
star
13

mariadb-columnstore-sample-data

Example queries and dataset for use with MariaDB ColumnStore
Shell
19
star
14

mariadb-community-columnstore-docker

Official MariaDB ColumnStore Community Docker Image
Shell
19
star
15

mariadb-qa

MariaDB QA (mariadb-qa)
PLpgSQL
14
star
16

mariadb-columnstore-docker

Shell
11
star
17

mariadb-columnstore-api

C++
11
star
18

libmarias3

A lightweight, LGPL-2.1 licensed C API to read from / write to S3 buckets
C
11
star
19

dev-example-places

A web application (with multiple API project options) that uses MariaDB!
JavaScript
10
star
20

dev-example-bookings

A web application (with multiple API project options) that uses MariaDB HTAP!
JavaScript
9
star
21

dev-example-modern-sql

9
star
22

dev-example-flights

A simple web application demonstrating the power and simplicity of MariaDB ColumnStore.
JavaScript
8
star
23

dev-example-connector-python

A repository that provides samples that use MariaDB Connector/Python
8
star
24

columnstore-ansible-aws

HCL
7
star
25

skysql-api-go

MariaDB SkySQL API Golang SDK
Dockerfile
6
star
26

mdbci

MariaDBCI
Ruby
6
star
27

mariadb-columnstore-data-adapters

Java
5
star
28

mariadb-training

PHP
5
star
29

skysql-api-cli

MariaDB SkySQL API CLI Client
Go
5
star
30

dev-example-orders

A web application (with multiple API project options) that uses MariaDB!
JavaScript
5
star
31

mariadb-enterprise-columnstore-docker

Enterprise MariaDB Columnstore Cluster Project
Shell
5
star
32

dev-example-nosql-listener

This repository contains information on how to create and use a MariaDB MaxScale NoSQL Listener with MariaDB Community Server.
JavaScript
5
star
33

dev-example-columnstore-quickstart

Shell
4
star
34

dev-example-pl-sql

4
star
35

terraform-provider-skysql

MariaDB SkySQL terraform provider
Go
4
star
36

mariadb-columnstore-tools

Shell
4
star
37

xbench-community

Python
3
star
38

dev-example-blog-samples

Python
3
star
39

dev-example-orms

Object-Relational Mapping and MariaDB samples
JavaScript
3
star
40

mariadb-powerbi

Power BI DirectQuery Connector
3
star
41

galera-qa

MariaDB Galera Testing Tool
Yacc
2
star
42

MaxScale-Documentation

MaxScale end-user documentation.
CSS
2
star
43

build-scripts

Shell
2
star
44

xpand-locust

Python
1
star
45

dev-example-r2dbc-sample

Java
1
star
46

dev-example-skysql-htap-quickstart

Shell
1
star
47

dev-example-htap-community

Shell
1
star
48

dev-example-microservices-dotnet

C#
1
star
49

maxscale-cdc-connector

C++
1
star
50

MaxGui

The gui for MaxScale's admin tool
Vue
1
star
51

build-scripts-vagrant

Modified build scripts to work with Vagrant-controlled VMs
Shell
1
star
52

connector-test-machine

Connector test scripts
Shell
1
star