Connect with MariaDB Connector/R2DBC

Overview

Java developers can use MariaDB Connector/R2DBC to establish client connections with MariaDB database products.

Connection Parameters

MariaDB Connector/R2DBC supports several connection parameters:

Parameter Name

Description

Type

Default Value

allowMultiQueries

Allows you to execute several SQL statements in a single call. The statements should be separated by the ; delimiter. For example, the following string would execute two INSERT statements: INSERT INTO a VALUES('b'); INSERT INTO c VALUES('d'); Enabling multi-query functionality might be a security risk, because malicious users could use it for SQL injection attacks.

boolean

false

allowPipelining

Allows queries to be executed in a pipeline, so that the next query is sent to the server before the previous query has finished execution.

boolean

true

allowPublicKeyRetrieval

Allows the RSA public key to be retrieved from the server, rather than from the cachingRsaPublicKey or rsaPublicKey parameters. It is generally more secure to configure the RSA public key using the cachingRsaPublicKey or rsaPublicKey parameters. The RSA public key only applies when connecting to MySQL with the sha256_password or caching_sha2_password authentication plugins.

boolean

true

autocommit

Sets default autocommit autocommit value on connection initialization.

boolean

true

cachingRsaPublicKey

Configures the RSA public key. The RSA public key only applies when connecting to MySQL with the sha256_password or caching_sha2_password authentication plugins.

String

clientSslCert

Configures the TLS client certificate. The TLS client certificate is only required when TLS client authentication is required. The parameter can be specified in 3 different formats:

  • Specify the absolute path to a PEM or DER certificate file: .clientSslCert("/path/to/cert.pem")

  • Specify the path to a PEM or DER certificate file relative to the Java CLASSPATH: .clientSslCert("classpath:relative/cert.pem")

  • Specify a PEM or DER certificate string: .clientSslCert("CERTIFICATE_STRING")

String

clientSslKey

Configures the TLS client private key. The TLS client private key is only required when TLS client authentication is required.

String

clientSslPassword

Configures the password for the TLS client private key. This is only required when the clientSslKey parameter refers to an encrypted private key file.

charsequence

connectionAttributes

Sets client attributes that are sent to the server. When performance_schema is enabled on the server, the client attributes can be queried from the performance_schema.session_connect_attrs and performance_schema.session_account_connect_attrs tables. Client attributes can be used to identify which client or application is using each connection.

Map<String,String>

connectTimeout

Sets the connection timeout.

duration

10s

database

Default database to use when establishing the connection.

string

host

IP address or DNS of the database server. Multiple hosts can be set by using comma separated list. If the first host is not reachable (timeout is connectTimeout), the driver uses the next host. Not used when using option socketPath.

localhost

isolationLevel

Allows setting the default isolation level on connection creation. Possible values are: READ-COMMITTED, READ-UNCOMMITTED, REPEATABLE-READ, or SERIALIZABLE. For example:

r2dbc:mariadb://USER@PASSWORD@HOST:PORT/DATABASE?isolationLevel=REPEATABLE-READ

String

null

loopResources

Permits sharing netty EventLoopGroup among multiple async libraries/framework.

LoopResources

pamOtherPwd

Configures the secondary password. The secondary password is only required when the pam authentication plugin is used to implement multi-factor authentication (MFA). If multiple passwords are specified, the value must be URL encoded.

string

password

User password.

string

permitRedirect

Permit server redirection

boolean

true

port

Database server port number. Not used when using option socketPath.

integer

3306

prepareCacheSize

If useServerPrepStmts = true, caches the prepared information in a LRU cache to avoid re-preparation of command. On the next use of that command, only the prepared identifier and parameters (if any) will be sent to server. This enables the server to avoid reparsing query.

int

256

restrictedAuth

Can restrict authentication to the specified list of authentication plugins. The authentication plugins should be separated by commas. When set to an empty string, any authentication plugin can be used. By default, the following authentication plugins can be specified: mysql_native_password, mysql_clear_password, client_ed25519, dialog, sha256_password, or caching_sha2_password.

string

rsaPublicKey

Configures the RSA public key. The RSA public key only applies when connecting to MySQL with the sha256_password or caching_sha2_password authentication plugins.

String

serverSslCert

Configures the TLS server certificate or the server's TLS CA certificate. This parameter enables a self-signed certificate to be trusted. The parameter can be specified in 3 different formats:

  • Specify the absolute path to a PEM or DER certificate file: serverSslCert("/path/to/cert.pem")

  • Specify the path to a PEM or DER certificate file relative to the Java CLASSPATH: .serverSslCert("classpath:relative/cert.pem")

  • Specify a PEM or DER certificate string: .serverSslCert("CERTIFICATE_STRING")

String

sessionVariables

Sets session values of system variables upon successful connection. The value should be set to a mapping of variables to values. For example, map.put("sql_mode", "ORACLE") or map.put("log_warnings", "5") The values of session variables can be retrieved using SHOW SESSION VARIABLESSHOW SESSION VARIABLES.

Map<String,String>

socket

Configures the path to the Unix domain socket. Connecting to a Unix domain socket can be faster than connecting via TCP/IP. Connecting to a Unix domain socket also allows authentication to occur using the unix_socket authentication plugin. Unix domain socket connections are only supported when the server is on the same system as the client.

string

sslContextBuilderCustomizer

Used with sslMode=TUNNEL, enables use of a customized SSL Context Builder. By default, SSL tunnel mode does not validate tunnel certificates and hostnames. This option permits the use of certificates, and setting the required protocol and ciphers to create a tunnel socket.

UnaryOperator<SslContextBuilder>

sslMode

Sets the TLS mode. Possible values are:

  • DISABLE - TLS is disabled.

  • TRUST - TLS is only used for data-in-transit encryption. The TLS server certificate is not verified, and the server's hostname is not validated against the certificate. MariaDB recommends only using this TLS mode for development.

  • TUNNEL - Enables use of a use pre-existing SSL tunnel.

  • VERIFY_CA - TLS is used for data-in-transit encryption, and the TLS server certificate is verified. The server's hostname is not validated against the certificate.

  • VERIFY_FULL - TLS is used for data-in-transit encryption, and the TLS server certificate is verified, and the server's hostname is validated against the certificate.

SslMode

DISABLE

sslTunnelDisableHostVerification

When the sslMode connection parameter is set to SslMode.TUNNEL, host verification can be disabled by setting this connection parameter to true.

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

tcpKeepAlive

Sets socket to keep alive.

boolean

false

timezone

This option permits forcing a session timezone in case of a client having a different timezone compared to the server. Possible values are:

  • disabled (default) : connector doesn't change time_zone

  • auto : client will use client default timezone

  • <a java timezone>: connector will set connection variable to the value

Since 1.2.0

string

disabled

tinyInt1isBit

Configures how the connector handles BIT(1)BIT(1) and TINYINT(1)TINYINT(1) values in result sets. When set to true, the values are handled as boolean objects. When set to false, the values are handled as int objects.

boolean

true

tlsProtocol

Configures the supported set of TLS protocol versions. The value can be set to a comma-separated list of TLS protocol versions. For example: .tlsProtocol(("TLSv1.2",TLSv1.3"))

List

java default

transactionReplay

Saves commands in transactions. If a failover occurs during a transaction, the connector can automatically reconnect and replay transactions, making failover completely transparent. 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").

boolean

false

username

User of access database.

string

useServerPrepStmts

Configures whether queries with parameters are evaluated using server-side prepared statements or client-side prepared statements. When server-side prepared statements are used, queries are transmitted using the binary protocol by default, but the text protocol can be used by prefixing the query string with /*text*/. When client-side prepared statements are used, queries are always transmitted using the text protocol.

boolean

false