Upgrade from MariaDB Connector/J 2.7 to 3.3

Overview

When upgrading from MariaDB Connector/J 2.7 to 3.3, application code must be updated to reflect changes in connector behavior.

MariaDB Connector/J 3.3 is fully compatible with MariaDB Connector/J 3.0, so upgrading from MariaDB Connector/J 3.0 to 3.3 should not require application changes.

Installation Changes

Enhanced Support For Features in Newer Java Versions

MariaDB Connector/J 3.3 uses Multi-Release JAR files (MRJAR), so it contains JAR files specific to different Java versions. This allows MariaDB Connector/J to continue supporting Java 8 while providing enhancements for newer versions of Java.

MariaDB Connector/J 3.3 also provides a Java 9 Platform Module System (JPMS) descriptor that provides the following information:

  • The module name

  • The module dependencies

  • The packages it makes available to other modules

  • The services it offers and consumes

Datasource Changes

MariaDB Connector/J 3.1 removes some deprecated methods from the MariaDbDataSource class:

  • void setDatabaseName(String database)

  • void setPort(int port)

  • void setPortNumber(int port)

  • void setProperties(String properties)

  • void setServerName(String serverName)

  • void setUserName(String userName) (but setUser() is still available.)

The setUrl(String url) method can be used to configure the datasource without the above methods.

Easy To Use Logging

In MariaDB Connector/J 3.1, logging can be enabled at runtime. Connector/J uses the slf4j API if it is installed. Otherwise, Connector/J uses the JDK logger / console.

Connector/J supports the following Java logging levels:

Log Levels

Description

  • INFO

Logs connection errors

  • DEBUG

  • FINE

Logs SQL statements

  • TRACE

  • FINEST

Logs network exchanges

New Authentication Plugin Option

MariaDB Connector/J 3.1 adds a new restrictedAuth option to restrict authentication plugins.

The restrictedAuth option can be set to a comma-separated list of client authentication plugins to allow. The following client authentication plugins are supported by default:

For example, the following connection string only allows the mysql_native_password and client_ed25519 client authentication plugins:

jdbc:mariadb://HOST/DATABASE?restrictedAuth=mysql_native_password,client_ed25519

For example, the following connection string only allows the mysql_native_password client authentication plugin:

jdbc:mariadb://HOST/DATABASE?restrictedAuth=mysql_native_password

New SSL/TLS Option

MariaDB Connector/J 3.1 adds a new sslMode option to simplify the configuration of SSL/TLS.

The sslMode option supports the following values:

Value

Description

disable

Do not use SSL/TLS (default)

trust

Only use SSL/TLS for encryption. Do not perform certificate or hostname verification. This mode is not safe for production applications.

verify-ca

Use SSL/TLS for encryption and perform certificates verification, but do not perform hostname verification.

verify-full

Use SSL/TLS for encryption, certificate verification, and hostname verification.

MariaDB Connector/J 3.1 deprecates the following SSL/TLS options, but still supports them for compatibility:

  • disableSslHostnameVerification

  • trustServerCertificate

  • useSsl

New Socket Options

When MariaDB Connector/J 3.1 is used with Java 11 or later, some socket options can be configured:

Socket Option

Connector/J Option

TCP_KEEPCOUNT

tcpKeepCount

TCP_KEEPIDLE

tcpKeepIdle

TCP_KEEPINTERVAL

tcpKeepInterval

These options only have an effect when MariaDB Connector/J 3.1 is used with Java 11 or later.

Connection Strings

jdbc:mariadb: Scheme

MariaDB Connector/J 3.1 only accepts jdbc:mariadb: as the protocol in connection strings by default. When both MariaDB Connector/J and the MySQL drivers are found in the class-path, using jdbc:mariadb: as the protocol helps to ensure that Java chooses MariaDB Connector/J.

Connector/J still allows jdbc:mysql: as the protocol in connection strings when the permitMysqlScheme option is set. For example:

jdbc:mysql://HOST/DATABASE?permitMysqlScheme

Removed Support for Aurora

MariaDB Connector/J 3.1 removes Aurora-specific functions and options. Connection strings using the Aurora-specific HA mode are no longer supported:

jdbc:mariadb:aurora://HOST/DATABASE

Options

Changes to Default Values

Option

Old default value

New default value

tcpKeepAlive

false

true

useBulkStmts

false

true

New Options

Option

Description

Data Type

Default Value

databaseTerm

Accepts one of the two values CATALOG and SCHEMA and determines which connection methods can be used to set or get the current database, which arguments can be used, and which fields contain the database specific information.

String

CATALOG

permitMysqlScheme

Enables the use of jdbc:mysql: as the protocol in connection strings.

Boolean

false

restrictedAuth

Sets a comma-separated list of client authentication plugins to allow. The following client authentication plugins are supported:

String

null

sslMode

Enables SSL/TLS in a specific mode. The following values are supported:

  • disable: Do not use SSL/TLS (default)

  • trust: Only use SSL/TLS for encryption. Do not perform certificate or hostname verification. This mode is not safe for production applications.

  • verify-ca: Use SSL/TLS for encryption and perform certificates verification, but do not perform hostname verification.

  • verify-full: Use SSL/TLS for encryption, certificate verification, and hostname verification.

This new option replaces the deprecated options:

  • disableSslHostnameVerification

  • trustServerCertificate

  • useSsl

String

disable

tcpKeepCount

Sets the TCP_KEEPCOUNT socket option. Only valid when used with Java 11+.

Integer

null

tcpKeepIdle

Sets the TCP_KEEPIDLE socket option. Only valid when used with Java 11+.

Integer

null

tcpKeepInterval

Sets the TCP_KEEPINTERVAL socket option. Only valid when used with Java 11+.

Integer

null

transactionReplay

Enables transaction caching. If a failover occurs before a transaction is committed or rolled back, the transaction's cached statements are re-executed on the new primary server. Connector/J requires that applications only use idempotent queries. If the number of statements in the transaction cache exceeds transactionReplaySize, caching will be disabled until the transaction is committed or rolled back.

Boolean

false

transactionReplaySize

Sets the number of statements that should be saved in the transaction cache when transactionReplay is enabled.

Integer

64

useLocalSessionState

Avoids unnecessary queries using local state if it is explicitly specified that only JDBC methods should be used, for example using the connection.setTransactionIsolation() method, and queries like SET SESSION TRANSACTION ISOLATION LEVEL ... are not run directly.

Boolean

false

Deprecated Options

Deprecated Option

Upgrade Guidance

disableSslHostnameVerification

Use sslMode=verify-ca

trustServerCertificate

Use sslMode=trust

useSsl

Use sslMode

Removed Options

Removed Option

Upgrade Guidance

allowMasterDownConnection

In a Primary/Replica topology, the primary server must now be available.

assureReadOnly

Connections to replica servers are now ensured to be read-only.

autoReconnect

Automatic reconnection can be enabled by setting a high availability (HA) mode in the connection string.

cachePrepStmts

Prepared statements are always cached when using the binary protocol.

callableStmtCacheSize

Callable statements are always cached when using the binary protocol.

continueBatchOnError

The behavior now depends on which batch implementation is used. The batch implementation depends on the values of the useBulkStmts and disablePipeline options.

enablePacketDebug

Network packet logging is now enabled using the TRACE and FINEST standard Java log levels.

ensureSocketState

This option was only relevant for debugging, so no replacement is required.

failOnReadOnly

In a Primary/Replica topology, the primary server must now be available.

failoverLoopRetries

The number of failover attempts is now configured by the retriesAllDown option

jdbcCompliantTruncation

Connector/J now sets sql_mode=STRICT_TRANS_TABLES to ensure that JDBC-compliant truncations are used.

keyPassword

This option is not supported by the default PKCS12 keystore type, so no replacement is required.

loadBalanceBlacklistTimeout

Connector/J now handles deny lists automatically. If all servers are denied, Connector/J will reconnect using the denied servers.

log

Logging is now enabled using the standard Java log levels.

maximizeMysqlCompatibility

Removed

nullCatalogMeansCurrent

Removed

passwordCharacterEncoding

Connection/J now sends passwords to the server encoded in UTF-8.

pinGlobalTxToPhysicalConnection

XA transactions can be used instead.

prepStmtCacheSqlLimit

The cache is now limited to 8 KB.

profileSql

SQL statement logging is now enabled using the DEBUG and FINE standard Java log levels.

retriesAllDown

This option is made obsolete by the new failover implementation.

rewriteBatchedStatements

This option is made obsolete by the new batch implementation.

serverTimezone

The time zone can be changed by setting the time_zone system variable instead.

sharedMemory

Removed

slowQueryThresholdNanos

staticGlobal

System variables can now be passed as arguments or set directly on the server.

tcpNoDelay

Removed

tcpRcvBuf

Connector/J now reads all available data from the socket by default, so the buffer size is not configurable.

tcpSndBuf

Removed

trackSchema

Connector/J now automatically enables this behavior by default.

trustStore

The TrustStore can be set using the serverSslCert option or the standard Java TrustStore.

trustStorePassword

The TrustStore can be set using the serverSslCert option or the standard Java TrustStore.

trustStoreType

The TrustStore can be set using the serverSslCert option or the standard Java TrustStore.

useBatchMultiSend

This option is made obsolete by the new batch implementation.

useBatchMultiSendNumber

This option is made obsolete by the new batch implementation.

useFractionalSeconds

Connector/J now expects all servers to support fractional seconds.

useLegacyDatetimeCode

Connector/J now expects the current datetime implementation to be used.

useOldAliasMetadataBehavior

Remove

validConnectionTimeout

Connector/J no longer automatically validates connections. Connection pools can be used to validate connections.