Skip to content

Configuration Options

Jump to bottom
jchrys edited this page Aug 12, 2024 · 11 revisions

driver

A constant mysql. The driver needs to be discovered by name.

Required if using URL Discovery and Programmatic Discovery.

Since 0.8.1

host

A hostname or IP. The host of MySQL server.

Required if unixSocket is not present.

Since 0.8.1

unixSocket

An absolute or relative path. The .sock file of Unix Domain Socket which is used to connect to MySQL server.

Required if host is not present.

Since 0.8.1

port

A positive integer less than 65536. The port of MySQL server.

Optional, default 3306.

Since 0.8.1

user

A valid MySQL username and not be empty.

Required.

Since 0.8.1

password

Any printable string. The password of the connecting user.

Optional, default to connecting without password.

Since 0.8.1

passwordPublisher

A Publisher<String> which emit a password.

Optional, default to connecting without password. It will override the password option.

Every time the client attempts to authenticate, it will use the password provided by the passwordPublisher. For example, users can employ this method for IAM-based authentication when connecting to an AWS Aurora RDS database.

Tips: users can use Mono.cache(Duration) (with Reactor) or Single.cache (with RxJava) to avoid high-frequency repeated requests. Of course, this should only be used if the authentication is not a one-time password.

Since 1.0.5 / 0.9.6

database

A valid MySQL database name.

Optional, default does not initialize/use database.

It will be initialized when logging in to the MySQL server (by default), or used immediately after logging in if createDatabaseIfNotExist is set.

Since 0.8.1

createDatabaseIfNotExist

Boolean, true or false. It will cause the driver to create the database after login if the database does not exist.

Optional, default false.

It also causes the driver to not initialize the database during the login phase, because if the database does not exist, the MySQL server will cause the login to fail due to the database not existing.

After the database is created, driver will use the database.

Since 1.0.6 / 0.9.7

connectTimeout

A Duration which must be positive duration. TCP connect timeout.

Optional, default has no timeout.

Since 0.8.1

serverZoneId

Deprecated since 1.1.2, use connectionTimeZone instead.

An identifier of ZoneId. The time zone of the MySQL server.

Optional.

Since 0.8.2, the time zone is queried by default after initializing sessionVariables

Since 1.1.2, default to use JVM local time zone by default

preserveInstants

Optional, default to true.

Default to true means enable conversion between JVM and connectionTimeZone when the driver sends a date time.

Simply put, this will force the driver to send the server a date time in the specified time zone.

Since 1.1.2

connectionTimeZone

A string which can be "LOCAL", "SERVER", or an identifier of time zone. The time zone of the connection.

Optional, default to "LOCAL".

Special values:

Since 1.1.2

forceConnectionTimeZoneToSession

A boolean, true or false. Set the session time zone as connectionTimeZone when initializing sessionVariables.

Optional, default to false. Used only if the connectionTimeZone is not SERVER.

Simply put, this will force the MySQL server to send the driver a date time in the specified time zone.

Since 1.1.2

tcpKeepAlive

Boolean, true or false. It controls TCP KeepAlive.

Optional, default false.

See also io.netty.channel.ChannelOption.SO_KEEPALIVE.

Since 0.8.2

tcpNoDelay

Boolean, true or false. It controls TCP NoDelay.

Optional, default false.

See also io.netty.channel.ChannelOption.TCP_NODELAY.

Since 0.8.2

sslMode

A value of enum SslMode.

Optional, default PREFERRED if using hosting connection, DISABLED if using Unix Domain Socket.

It considers security level and verification for SSL, make sure the database server supports SSL before changing SSL mode to REQUIRED or higher.

The Unix Domain Socket only offers DISABLED available.

All available enum values:

  • DISABLED: I don't care about security and don't want to pay the overhead for encryption
  • PREFERRED: I don't care about encryption but will pay the overhead of encryption if the server supports it
  • REQUIRED: I want my data to be encrypted, and I accept the overhead. I trust that the network will make sure I always connect to the server I want
  • VERIFY_CA: I want my data encrypted, and I accept the overhead. I want to be sure I connect to a server that I trust
  • VERIFY_IDENTITY: I want my data encrypted, and I accept the overhead. I want to be sure I connect to a server I trust, and that it's the one I specify. It is the highest level, most like web browser
  • TUNNEL: I'm using a SSL tunnel/proxy to connect to MySQL, do NOT use the native SSL protocol of MySQL. It may be useful for some RDS that's using SSL proxy

Since 0.8.1, value TUNNEL since 0.9.0

sslCa

A path of local file which type is PEM. The CA cert of MySQL server.

Required if sslMode is VERIFY_CA or VERIFY_IDENTITY.

sslCert

A path of local file which type is PEM. The SSL cert of client.

Required if sslKey is present.

sslKey

A path of local file which type is PEM. The SSL key of client.

Required if sslCert is present.

sslKeyPassword

Any valid password for PEM file. The password for client SSL key, i.e. sslKey.

Optional, default read sslKey without password.

tlsVersion

Any value list of TlsVersions. The TLS versions for SSL. Used only if connection is using the native SSL protocol of MySQL.

Optional, default is auto-selected by the server.

It considers TLS versions for SSL.

It can be multi-values in the configuration, usually sorted from higher to lower, e.g. tlsVersion=TLSv1.3,TLSv1.2.

Unavailable on Unix Domain Socket.

All values of TlsVersions will be a String which is case-sensitive.

All available values:

  • TLSv1 / TlsVersions.TLS1: Under generic circumstances, MySQL database supports it if database supports SSL
  • TLSv1.1 / TlsVersions.TLS1_1: Under generic circumstances, MySQL database supports it if database supports SSL
  • TLSv1.2 / TlsVersions.TLS1_2: Supported only in Community Edition 8.0.4 and above, and Enterprise Edition 5.6.0 and above
  • TLSv1.3 / TlsVersions.TLS1_3: Supported only available as of MySQL 8.0.16 and above, requires compiling MySQL using OpenSSL 1.1.1 and above

Since 0.8.1

sslHostnameVerifier

An implementation of javax.net.ssl.HostnameVerifier. Used only if sslMode is VERIFY_CA or higher.

Optional, default use RFC standard.

Since 0.8.2

sslContextBuilderCustomizer

An implementation of java.util.function.Function<io.netty.handler.ssl.SslContextBuilder, SslContextBuilder>. Used only if sslMode is not DISABLED.

Optional, default is NO-OP function.

Since 0.8.1

zeroDate / zeroDateOption

A value of enum ZeroDateOption. It considers special handling when MySQL server returning "zero date", i.e. 0000-00-00 00:00:00.

Optional, default USE_NULL.

All available enum values:

  • EXCEPTION: Throw an exception if the MySQL server returns "zero date"
  • USE_NULL: Use null if the MySQL server returns "zero date"
  • USE_ROUND: NOT RECOMMENDED, only for compatibility. Use "round" date (i.e. 0001-01-01 00:00:00) if the MySQL server returns "zero date"

Since 0.8.1

useClientPrepareStatement / useServerPrepareStatement

A boolean or an implementation of Predicate<String>. It considers whether prepared statements should be based on server preparation or client preparation.

Optional, default is false.

Why default false? Some reasons:

  • Stateless. Overall, people avoid using prepared statements because it's tied to the current session and if the connection goes down or has been reset, driver will lose everything. By default, mysql-connector-j also uses client-preparing
  • Some distributions may not support server preparation. Such as earlier versions of Vitess
  • Some statements do NOT support server preparation, e.g. LOAD DATA LOCAL INFILE ? INTO TABLE users

Available values description:

  • useServerPrepareStatement=false / useClientPrepareStatement(): use MySQL text protocol for all statements, which means it uses client preparation for parametrized statements
  • useServerPrepareStatement=true / useServerPrepareStatement(): use server preparation for parametrized statements, and text protocol for non-parameterized statements
  • useServerPrepareStatement=foo.bar.PreparedPredicate / useServerPrepareStatement(Predicate<String>): use server preparation for parameterized statements. For non-parameterized statements, the usage is judged through Predicate, which accepts a non-parameterized statement. If it returns true, it forces to use server preparation

Since 0.8.1

allowLoadLocalInfileInPath

A local path of folder. The path that allows LOAD DATA LOCAL INFILE to load file data.

Optional, default is null which means do not allow LOAD DATA LOCAL INFILE statement.

Since 1.1.0

localInfileBufferSize

A positive integer. The buffer size for reading local files, used with LOAD DATA LOCAL INFILE statements.

Optional, default 8192.

Since 1.1.2

compressionAlgorithms

A list of enum CompressionAlgorithm. The available compression algorithms for connection.

Optional, default is UNCOMPRESSED.

It considers compression protocol for MySQL connection, it is NOT RECOMMENDED to use compression protocol in the general case, because it will increase the CPU usage and decrease the performance. For scenarios where the network environment is poor or the amount of data is always large, using a compression protocol may be useful.

All available enum values:

  • UNCOMPRESSED: No compression
  • ZLIB: Use Zlib compression protocol, it is available on almost all MySQL versions (5.x and above)
  • ZSTD: Use Z-standard compression protocol, it is available since MySQL 8.0.18 and above, requires an extern dependency com.github.luben:zstd-jni

Since 1.1.2

zstdCompressionLevel

An integer between 1 and 22. The zstd compression level, used only if zstd compression protocol is chosen for the connection.

Optional, default is 3.

Note: MySQL protocol does not allow to set the zlib compression level of the server, only zstd is configurable.

Since 1.1.2

sessionVariables

A list of key-value pairs. It will be used to set session variables immediately after login.

Optional, default no session variable need to be set.

For example:

  • sessionVariables=sql_mode='ANSI_QUOTES,STRICT_TRANS_TABLES',time_zone=00:00 in URL Discovery
  • option(Option.valueOf("sessionVariables"), new String[] { "sql_mode=ANSI_QUOTES", "time_zone=00:00" }) in Programmatic Discovery
  • sessionVariables("sql_mode='ANSI_QUOTES'", "time_zone=00:00") in Programmatic Configuration

Since 1.1.2

loopResources

An implementation of reactor.netty.resources.LoopResources. It configures EventLoopGroup for Netty connection.

Optional, default is null which means use default global TcpResources.get().

Since 1.1.2

autodetectExtensions / extendWith

See also Extensions page for more information.

autodetectExtensions

Boolean, true or false. It controls auto-detect Extensions.

Optional, default is true.

Since 0.8.2

extendWith

It is available only in Programmatic Configuration.

Manually add an instance of Extension to the connection configuration.

Since 0.8.2

Clone this wiki locally