The most recent release of MariaDB Connector/J is:
Download MariaDB Connector/J List of MariaDB Connector/J Releases
MariaDB Connector/J is used to connect applications developed in Java to MariaDB and MySQL databases using the standard JDBC API. The library is LGPL licensed. MariaDB Connector/J is a Type 4 JDBC driver. It was developed specifically as a lightweight JDBC connector for use with MariaDB and MySQL database servers. It was originally based on the Drizzle JDBC code with numerous additions and bug fixes. ### Server Compatibility MariaDB Connector/J is compatible with all MariaDB and MySQL server versions. {% hint style="info" %} MariaDB Connector/J releases older than 1.2.0 may be compatible with server versions older than MySQL 5.5, but those MariaDB Connector/J releases aren't supported anymore. {% endhint %} ### Java Compatibility To determine which MariaDB Connector/J release series would be best to use for each Java version, please see the following table: | Java Version(s) | Recommended MariaDB Connector/J Release Series | JDBC Version | | ------------------------------------------ | ------------------------------------------------- | ------------ | | Java 25, Java 21, Java 17, Java 11, Java 8 | MariaDB Connector/J 3.5, 3.4, 3.3\[[1](#_note-0)] | JDBC 4.5 | | Java 17, Java 11, Java 8 | MariaDB Connector/J 2.7 | JDBC 4.2 | 1. [↑](#_ref-0) see parsec authentication restriction ## Installing MariaDB Connector/J MariaDB Connector/J can be installed using [Maven](https://maven.apache.org/what-is-maven.html), [Gradle](https://gradle.org/), or by manually putting the `.jar` file in your [CLASSPATH](https://docs.oracle.com/javase/tutorial/essential/environment/paths.html). See [Installing MariaDB Connector/J](https://mariadb.com/docs/connectors/mariadb-connector-j/installing-mariadb-connectorj) for more information. MariaDB Connector/J `.jar` files and source code tarballs can be downloaded from the following URL: * [#jar](https://mariadb.com/downloads/#connectors) * [#source tar](https://github.com/mariadb-corporation/mariadb-connector-j/releases) * [#github](https://github.com/mariadb-corporation/mariadb-connector-j/) ### Installing Dependencies JNA (net.java.dev.jna:jna) and JNA-PLATFORM (net.java.dev.jna:jna-platform) 4.2.1 or greater are also needed when you would like to connect to the server with Unix sockets or windows pipes. ## Using the Driver The following subsections show the formatting of JDBC connection strings for MariaDB and MySQL database servers. Additionally, sample code is provided that demonstrates how to connect to one of these servers and create a table. ## Getting a New Connection There are two standard ways to get a connection: ### **Using DriverManager** The preferred way to get a connection with MariaDB Connector/J is to use the [DriverManager](https://docs.oracle.com/javase/8/docs/api/java/sql/DriverManager.html) class.\ When the `DriverManager` class is used to locate and load MariaDB Connector/J, the application needs no further configuration. The `DriverManager` class will automatically load MariaDB Connector/J and allow it to be used in the same way as any other JDBC driver. For example: ```java Connection connection = DriverManager.getConnection("jdbc:mariadb://localhost:3306/DB?user=root&password=myPassword"); ``` {% hint style="info" %} The legacy way of loading a JDBC driver also still works for MariaDB Connector/J. e.g.: `Class.forName("org.mariadb.jdbc.Driver")` {% endhint %} #### **jdbc:mysql scheme compatibility** MariaDB Connector/J 3.0 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` (2.x version did permit connection URLs beginning with both `jdbc:mariadb` and `jdbc:mysql`) ### **Using a Pool** Another way to get a connection with MariaDB Connector/J is to use a connection pool. MariaDB Connector/J provides 2 different Datasource pool implementations: * `MariaDbDataSource`: The basic implementation. It creates a new connection each time the `getConnection()` method is called. * `MariaDbPoolDataSource`: A connection pool implementation. It maintains a pool of connections, and when a new connection is requested, one is borrowed from the pool. #### **Internal Pool** The driver's internal pool configuration provides a very fast pool implementation and deals with the issues most of the java pool have: * 2 different connection states cleaning after release * deals with non-activity (connections in the pool will be released if not used after some time, avoiding the issue created when the server closes the connection after @wait\_timeout is reached). See the [pool documentation](https://mariadb.com/docs/connectors/mariadb-connector-j/pool-datasource-implementation) for more information. #### **External pool** When using an external connection pool, the MariaDB Driver class `org.mariadb.jdbc.Driver` must be configured. Example using hikariCP JDBC connection pool : ```java final HikariDataSource ds = new HikariDataSource(); ds.setMaximumPoolSize(20); ds.setDriverClassName("org.mariadb.jdbc.Driver"); ds.setJdbcUrl("jdbc:mariadb://localhost:3306/db"); ds.addDataSourceProperty("user", "root"); ds.addDataSourceProperty("password", "myPassword"); ds.setAutoCommit(false); ``` Please note that the driver class provided by MariaDB Connector/J **is not `com.mysql.jdbc.Driver` but `org.mariadb.jdbc.Driver`**! The `org.mariadb.jdbc.MariaDbDataSource` class can be used when the pool datasource configuration only permits the java.sql.Datasource implementation. ## Connection Strings The format of the JDBC connection string is: ```java jdbc:mariadb:[replication:|loadbalance:|sequential:|load-balance-read:]//| Parameter | Description |
|---|---|
allowMasterDownConnection | When the replication Failover and Load Balancing Mode is in use, allow the creation of connections when the master is down. If no masters are available, then the default connection will be a replica, and Connection.isReadOnly() will return true. Default: false. Since 2.2.0, removed in 3.0.0 |
interactiveClient | Session timeout is defined by the wait_timeout server variable. Setting interactiveClient to true will tell the server to use the interactive_timeout server variable.Default: false. Since 1.1.7 |
assureReadOnly | When this parameter is enabled, when a failover and load balancing mode is in use and a read-only connection is made to a host, ensure that this connection is in read-only mode by setting the session to read-only. Default to false. Since 1.3.0, removed in 3.0.0 |
autoReconnect | If this parameter is enabled and Failover and Load Balancing Mode is not in use, the connector will simply try to reconnect to its host after a failure. This is referred to as Basic Failover. If this parameter is enabled and Failover and Load Balancing Mode is in use, the connector will blacklist the failed host and try to connect to a different host of the same type. This is referred to as Standard Failover. Default is false.since 1.1.7, removed in 3.0.0 |
callableStmtCacheSize | This sets the number of callable statements that the driver will cache per VM if "cacheCallableStmts" is enabled.Default: true. Since 1.4.0, removed in 3.0.0 |
enablePacketDebug | Driver will save the last 16 MySQL packet exchanges (limited to first 1000 bytes). Hexadecimal value of those packets will be added to stacktrace when an IOException occur.This option has no impact on performance but driver will then take 16kb more memory.Default: false. Since 1.6.0, 2.0.1, removed in 3.0.0 |
failoverLoopRetries | When the connector is searching silently for a valid host, this parameter defines the maximum number of connection attempts the connector will make before throwing an exception.This parameter differs from the "retriesAllDown" parameter because this silent search is used in situations where the connector can temporarily workaround the problem, such as by using the master connection to execute reads when the replica connection fails.Default: 120.since 1.2.0, removed in 3.0.0 |
jdbcCompliantTruncation | Truncation error ("Data truncated for column '%' at row %", "Out of range value for column '%' at row %") will be thrown as an error, and not as a warning.Default: true. Since 1.4.0 |
keyPassword | Password for the private key in client certificate keyStore. (only needed if private key password differ from keyStore password).Since 1.5.3, removed in 3.0.0 |
loadBalanceBlacklistTimeout | When a connection fails, this host will be blacklisted for the amount of time defined by this parameter.When connecting to a host, the driver will try to connect to a host in the list of non-blacklisted hosts and, only if none are found, attempt blacklisted ones.This blacklist is shared inside the classloader.Default: 50 seconds.since 1.2.0, removed in 3.0.0 |
log | Enable log information. require Slf4j version > 1.4 dependency.Log level correspond to Slf4j logging implementationDefault: false. Since 1.5.0, removed in 3.0.0 |
passwordCharacterEncoding | Indicate password encoding charset. Charset value must be a Java charset. Example : "UTF-8" Default: null (= platform's default charset) . Since 1.5.9, removed in 3.0.0 |
profileSql | log query execution time.Default: false. Since 1.5.0, removed in 3.0.0 |
slowQueryThresholdNanos | Will log query with execution time superior to this value (if defined )Default: 1024. Since 1.5.0, removed in 3.0.0 |
retriesAllDown | When the connector is performing a failover and all hosts are down, this parameter defines the maximum number of connection attempts the connector will make before throwing an exception.Default: 120 seconds.since 1.2.0, removed in 3.0.0 |
serverTimezone | Defines the server time zone.to use only if the jre server has a different time implementation of the server.(best to have the same server time zone when possible).since 1.1.7, removed in 3.0.0 |
sharedMemory | Permits connecting to the database via shared memory, if the server allows it. The value is the base name of the shared memory.since 1.1.4, removed in 3.0.0 |
staticGlobal | Indicates the values of the global variables max_allowed_packet, wait_timeout, autocommit, auto_increment_increment, time_zone, system_time_zone and tx_isolation) won't be changed, permitting the pool to create new connections faster.Default: false. Since 2.2.0, removed in 3.0.0 |
tcpNoDelay | Sets corresponding option on the connection socket.since 1.0.0, removed in 3.0.0 |
tcpRcvBuf | set buffer size for TCP buffer (SO_RCVBUF).since 1.0.0, removed in 3.0.0 |
tcpSndBuf | set buffer size for TCP buffer (SO_SNDBUF).since 1.0.0, removed in 3.0.0 |
trackSchema | Permit to disabled "session_track_schema" setting when server has CLIENT_SESSION_TRACK capabilityDefault: True. Since 2.5.4, removed in 3.0.0 |
useBatchMultiSend | Not compatible with aurora Driver will can send queries by batch. If set to false, queries are sent one by one, waiting for the result before sending the next one. If set to true, queries will be sent by batch corresponding to the useBatchMultiSendNumber option value (default 100) or according to the max_allowed_packet server variable if the packet size does not permit sending as many queries. Results will be read later, avoiding a lot of network latency when the client and server aren't on the same host. This option is mainly effective when the client is distant from the server. More information here Default: true (false if using aurora failover) . Since 1.5.0, removed in 3.0.0 |
useBatchMultiSendNumber | When option useBatchMultiSend is active, indicate the maximum query send in a row before reading results.Default: 100. Since 1.5.0 |
useFractionalSeconds | Correctly handle subsecond precision in timestamps (feature available with MariaDB 5.3 and later). May confuse 3rd party components (Hibernated).Default: true. Since 1.0.0 |
useOldAliasMetadataBehavior | Metadata ResultSetMetaData.getTableName() returns the physical table name. "useOldAliasMetadataBehavior" permits activating the legacy code that sends the table alias if set. Default: false. Since 1.1.9 |
validConnectionTimeout | When multiple hosts are configured, the connector verifies that the connections haven't been lost after this much time in seconds has elapsed.When this parameter is set to 0, no verification will be done. Default:120 secondssince 1.2.0, removed in 3.0.0 |
| Option | Default in 2.7.x | Default in 3.x | Impact |
|---|---|---|---|
| useBulkStmts | false | true | 3.x uses the COM_STMT_BULK protocol by default for batch inserts. This is faster but changes getGeneratedKeys() behavior (returns the last ID instead of the first). |
| prepStmtCacheSqlLimit | 256 | 2048 | 3.x caches significantly larger queries. This increases client memory usage and the number of prepared statements held open on the server (prepared_stmt_count). |
| useServerPrepStmts | false | false | While the default remains false, if enabled, 3.x is more aggressive in preparing statements. Combined with the larger cache limit, this can exhaust the server's max_prepared_stmt_count. |