MariaDB Connector/J 3.0.3 Release Notes
The most recent Stable (GA) release of MariaDB Connector/J is:
MariaDB Connector/J 3.5.1
Download Release Notes Changelog Connector/J Overview
Release date: 25 Jan 2022
MariaDB Connector/J 3.0.3 is a Stable (GA) release.
NOTE: MariaDB Connector/J 3.0.3 is NOT fully compatible with the latest release of version 2.7.
For an overview of MariaDB Connector/J see the About MariaDB Connector/J page
New version 3.0 is a complete rewrite of the connector, with code simplification, reduced size (15%), more than 90% coverage tested, with performance gain.
Licence is still LGPL-2.1 or later with copyright to MariaDB Corporation AB only (2.x was a fork from Drizzle-JDBC - BSD licensed)
What’s new :
- Binary prepare statement improvement
- faster connection creation
- Support of new 10.6 metadata skip
- Pipelining PREPARE
- REDO failover transaction
- Better java version support
- New option `tcpKeepIdle`, `tcpKeepCount`, `tcpKeepInterval` for java 11+
- Provide a full JPMS module descriptor
- new option `restrictedAuth` to permit authentication plugin restriction
- metadata queries performance improvement
- Easy logging
- Deprecated option removal
- Support codec registry implementation
Performance
Other than features, connector permit significant performance improvements : Here are real world TPCC benchmarks results, comparing connector version 2.7.4 and 3.0.3
Binary prepare statement improvement
When using option `useServerPrepStmts`, the connector uses BINARY protocol, meaning executing PREPARE + EXECUTE commands.
Pipelining
Queries issued from the application are sent one by one to the server, waiting on the results of the first query before sending the next. Communication with the server follows this synchronous request-response messaging pattern.
When using binary protocol, a PREPARE command is issued (if not in cache) before executing an EXECUTE command.
For MariaDB server 10.2+, the connector will send an optimistic PREPARE + EXECUTE, sending queries one after another. EXECUTE command will be executed only if the PREPARE command succeeds. This avoids some network latency reading PREPARE result before sending EXECUTE command.
Support of new 10.6 metadata skip
10.6 Server with MDEV-19237 permit to avoid resending metadata when they haven’t changed. This concerns SQL commands that return a resultset, when using option `useServerPrepStmts`.
Now, the server will send metadata only if they have changed (DDL change for example). This avoids useless information transiting on the network and parsing those metadata.
Connector internal JMH Benchmark results, selecting one row of a 100 int column table :
Avoiding additional command on connection creation
Connection creation by default won't execute additional command to set session environement. Depending on options, there might be a few commands, but driver avoid them to the maximum.
REDO failover transaction
After a failover occurs, reconnection will be automatically done according to high-availability configuration. Even if implementation is now smaller and clearer, the result will be the same.
After reconnection, the connector might still throw an exception if the state is unsure. Failover on replica are transparent. This is different when the failover occurs during the execution of a query on a master server.
A new option `transactionReplay` permit to replay transactions : Most of the time, queries occur in transactions so redo transaction implementation will solve most of the failover cases transparently. Option is disabled by default. When enabled, all queries in a transaction are cached until transaction resolution. If a failover occurs, the driver will recreate a new connection and replay cache. There is a few limitations: When the last command was a "commit" sent to the server, an exception will be thrown, the driver cannot know the current state. application must have idempotent queries only (queries can be "replayable") If the transaction is too big (cache size limit set with new option `transactionReplaySize`), the driver won’t cache the transaction anymore, so a failover during that specific transaction will result in throwing an exception.
Better java version support
Driver uses Multi-Release JARs (MRJAR), to simultaneously contain implementations for different versions of java. This permit still supports Java 8, but provides solutions for higher versions of java.
Connector now provides a java 9 full module-info JPMS descriptor
Java 11 socket extended option TCP_KEEPIDLE, TCP_KEEPCOUNT and TCP_KEEPINTERVAL are now configurable with `tcpKeepIdle`, `tcpKeepCount`, `tcpKeepInterval` options respectively. (These options don't have any effect if using a java version lower than 11).
Authentication plugin restriction
A new option `restrictedAuth` permits to restrict authentication plugins. Example connection string `jdbc:mariadb:localhost/db?restrictedAuth=mysql_native_password,client_ed25519` will restrict plugin use of standard mysql_native_password and client_ed25519 only.
Metadata queries performance improvement
Metadata queries use of information_schema improvement for partial or exact matching, permitting faster results.
Easy logging
Logging can now be easily enabled at runtime, using slf4j if present, or fallback to JDK logger / console if not.
- INFO level log connection error
- DEBUG/FINE level log commands
- TRACE/FINEST level log network exchanges
jdbc:mariadb scheme
It occurs that mysql AND mariadb driver are sometimes available in the same classpath, so, now, driver only accept `jdbc:mariadb:` by default.
If for some reason, connection string is required to be `jdbc:mysql:` Driver will be used only if connection string contain 'permitMysqlScheme'. example : `jdbc:mysql:localhost/test?permitMysqlScheme`.
Option changed
Ssl configuration use now a new option `sslMode` to simplify configuration Possible value are :
| disable | No ssl (default) |
|---|---|
| trust | Encryption only (no certificate and hostname validation) (DEVELOPMENT ONLY) |
| verify-ca | Encryption, certificates validation, BUT no hostname verification |
| verify-full | Standard SSL use: Encryption, certificate validation and hostname validation |
This can still be done by 2.x options (useSsl, disableSslHostnameVerification, trustServerCertificate) for compatibility, but this is the preferred way.
A new option `timezone` permits to force session timezone in case of client having a different timezone compare to server. if set timezone must to either offset or IANA tz (like '+5:00' or 'America/New_York')': connector will set connection timezone. This replace options `useLegacyDatetimeCode` and `serverTimezone` that did cause some problems when using some functions that are affected by the time zone setting.
Option removal
Even if connectors aim to be compatible with the 2.x version, there has been very few option removal since connection exists. This is now the time :
| allowMasterDownConnection | In master/replica setup, master must be up |
|---|---|
| assureReadOnly | connectors now configure replica connection being read-only |
| autoReconnect | doesn’t have any sense now, better use high availability mode |
| cachePrepStmts | always cache when using binary protocol |
| callableStmtCacheSize | always cache when using binary protocol |
| continueBatchOnError | |
| enablePacketDebug | log are now set using standard logger |
| ensureSocketState | removed, this was a debugging option |
| failOnReadOnly | one master must always be present when using master/replica setup |
| failoverLoopRetries | failover number of attempts rely now only on retriesAllDown option |
| jdbcCompliantTruncation | The connector ensures STRICT_TRANS_TABLES is always set to follow JDBC expected truncation. |
| keyPassword | |
| loadBalanceBlacklistTimeout | denied lists are handled automatically, and if all servers are denied, the connector will reconnect using the denied servers. No need for these options anymore. |
| log | log are now set using standard logger |
| maximizeMysqlCompatibility | very old option for old mysql connector compatibility |
| nullCatalogMeansCurrent | was to permit non JDBC behavior for compatibility with old version correction |
| passwordCharacterEncoding | |
| pinGlobalTxToPhysicalConnection | |
| prepStmtCacheSqlLimit | forced to 8K value |
| profileSql | log are now set using standard logger |
| retriesAllDown | not compatible with new failover implementation |
| rewriteBatchedStatements | replaced by use of faster batching implementation ( COM_STMT_BULK) |
| serverTimezone | |
| sharedMemory | plugin removed |
| slowQueryThresholdNanos | |
| staticGlobal | |
| tcpNoDelay | Who would want to disable NAGLE to have a slow connector |
| tcpRcvBuf | |
| tcpSndBuf | |
| trackSchema | Automatically set |
| trustStore | Use java standard truststore or option serverSslCert to provide certificates. |
| trustStorePassword | Same than trustStore |
| trustStoreType | Same than trustStore |
| useBatchMultiSend | replaced by use of faster batching implementation ( COM_STMT_BULK) |
| useBatchMultiSendNumber | See useBatchMultiSend |
| useFractionalSeconds | server are expected to support fractional seconds (all mariadb server support it, mysql since 5.6) |
| useLegacyDatetimeCode | |
| useOldAliasMetadataBehavior | was to permit non JDBC behavior for compatibility with old version correction |
| validConnectionTimeout | No automatic validation done by connector, pool must validate connection, not connector having a thread for that |
Specific support for aurora has been removed, since Issues were piling up without the community proposing any PR for them and without access for us to test those modifications.
Changelog
For a complete list of changes made in MariaDB Connector/J 3.0.3, with links to detailed information on each push, see the changelog.
