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.
|26 Apr 2016||MariaDB Connector/J 1.4.3||Stable (GA)||Release Notes||Changelog|
|11 Apr 2016||MariaDB Connector/J 1.4.2||Stable (GA)||Release Notes||Changelog|
|11 Apr 2016||MariaDB Connector/J 1.4.1||Stable (GA)||Release Notes||Changelog|
|1 Apr 2016||MariaDB Connector/J 1.4.0||Stable (GA)||Release Notes||Changelog|
|23 Mar 2016||MariaDB Connector/J 1.3.7||Stable (GA)||Release Notes||Changelog|
|29 Feb 2016||MariaDB Connector/J 1.3.6||Stable (GA)||Release Notes||Changelog|
|9 Feb 2016||MariaDB Connector/J 1.3.5||Stable (GA)||Release Notes||Changelog|
|12 Jan 2016||MariaDB Connector/J 1.3.4||Stable (GA)||Release Notes||Changelog|
|8 Dec 2015||MariaDB Connector/J 1.3.3||Stable (GA)||Release Notes||Changelog|
|23 Nov 2015||MariaDB Connector/J 1.3.2||Stable (GA)||Release Notes||Changelog|
|18 Nov 2015||MariaDB Connector/J 1.3.1||Stable (GA)||Release Notes||Changelog|
|16 Nov 2015||MariaDB Connector/J 1.3.0||Stable (GA)||Release Notes||Changelog|
|6 Oct 2015||MariaDB Connector/J 1.2.3||Stable (GA)||Release Notes||Changelog|
|10 Sep 2015||MariaDB Connector/J 1.2.2||Stable (GA)||Release Notes||Changelog|
|17 Jul 2015||MariaDB Connector/J 1.2.0||Stable (GA)||Release Notes||Changelog|
|18 Jun 2015||MariaDB Connector/J 1.1.9||Stable (GA)||Release Notes||Changelog|
|16 Jan 2015||MariaDB Java Client 1.1.8||Stable (GA)||Release Notes||Changelog|
|2 Apr 2014||MariaDB Java Client 1.1.7||Stable (GA)||Release Notes||Changelog|
|18 Feb 2014||MariaDB Java Client 1.1.6||Stable (GA)||Release Notes||Changelog|
|18 Sep 2013||MariaDB Java Client 1.1.5||Stable (GA)||Release Notes||Changelog|
|10 Sep 2013||MariaDB Java Client 1.1.4||Stable (GA)||Release Notes||Changelog|
|1 Jul 2013||MariaDB Java Client 1.1.3||Stable (GA)||Release Notes||Changelog|
|2 May 2013||MariaDB Java Client 1.1.2||Stable (GA)||Release Notes||Changelog|
|1 Mar 2013||MariaDB Java Client 1.1.1||Stable (GA)||Release Notes||Changelog|
|15 Jan 2013||MariaDB Java Client 1.1.0||Stable (GA)||Release Notes||Changelog|
|29 Nov 2012||MariaDB Java Client 1.0.0||Stable (GA)|
- About MariaDB Connector/J
- Obtaining the driver
- Installing the driver
- Source code
- Building and testing the driver
- Using the driver
- Getting a new connection
- Connection strings
- Failover parameters
- Optional URL parameters
- Failover/High availability URL parameters
- JDBC API Implementation Notes
- Usage examples
About MariaDB Connector/J
MariaDB Connector/J is a Type 4 JDBC driver. It was developed specifically as a lightweight JDBC connector for use with MySQL and MariaDB database servers. It's originally based on the Drizzle JDBC code, and with a lot of additions and bug fixes.
Obtaining the driver
MariaDB Connector/J source code tarballs can be downloaded from: https://downloads.mariadb.org/connector-java/
Pre-built .jar files can be downloaded from: https://mariadb.com/my_portal/download/java-client
Installing the driver
Installation of the client library is very simple, the jar file should be saved in an appropriate place for your application and the classpath of your application altered to include MariaDB Connector/J rather than your current connector.
Using maven :
<dependency> <groupId>org.mariadb.jdbc</groupId> <artifactId>mariadb-java-client</artifactId> <version>xxx</version> </dependency>
- Java 7 or 8 (Last compatible version with java 6 is 1.1.9)
- com.sun.JNA is used by some library functions and a jar is available at
- only needed when connecting to the server with unix sockets or windows shared memory
- A MariaDB or MySQL Server
- maven (only if you want build from source)
The source code is available on GitHub: https://github.com/MariaDB/mariadb-connector-j and the most recent development version can be obtained using the following command:
git clone https://github.com/MariaDB/mariadb-connector-j.git
GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.
Building and testing the driver
The section deals with building the connector from source and testing it. If you have downloaded a ready built connector, in a jar file, then this section may be skipped.
MariaDB Client Library for Java Applications uses maven for build. You first need to ensure you have both java and maven installed on your server before you can build the driver.
To run the unit test, you'll need a MariaDB or MySQL server running on localhost (on default TCP port 3306) and a database called 'test', and user 'root' with empty password
git clone https://github.com/MariaDB/mariadb-connector-j.git # Or, unpack the source distribution tarball cd mariadb-connector-j # For the unit test run, start local mysqld mysqld, # ensure that user root with empty password can login mvn package # If you want to build without running unit tests, use # mvn -Dmaven.test.skip=true package
After that, you should have JDBC jar mariadb-java-client-x.y.z.jar in the 'target' subdirectory
Using the driver
The following subsections show the formatting of JDBC connection strings for MariaDB, 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:
The prefered way to connect is to use https:docs.oracle.com/javase/7/docs/api/java/sql/DriverManager.html. Applications designed to use the driver manager to locate the entry point need no further configuration. MariaDB Connector/J will automatically be loaded and used in the way any previous MySQL driver would have been.
Connection connection = DriverManager.getConnection("jdbc:mariadb://localhost:3306/DB?user=root&password=myPassword");
The legacy way of loading a JDBC driver (using Class.forName("org.mariadb.jdbc.Driver")) still works.
Using 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 :
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
org.mariadb.jdbc.MariaDbDataSource class can be used when the pool datasource configuration only permits the java.sql.Datasource implementation.
Format of the JDBC connection string is
<host>[:<portnumber>] or address=(host=<host>)[(port=<portnumber>)][(type=(master|slave))]
Host must be a DNS name or IP address. In case of ipv6 and simple host
description, the IP address must be written inside brackets. The default port
3306. The default type is
replication failover is
set, by default the first host is master, and the others are slaves.
Failover was introduced in Connector/J 1.2.0.
|sequential||Failover support for master replication cluster (for example Galera) without High availability. The host will be connected in the order in which they were declared.|
Example when using the jdbc url string "jdbc:mysql:replication:host1,host2,host3/test" :
When connecting, the driver will always try first host1, and if not available host2 and following. After a host fail, the driver will reconnect according to this order.
|failover||High availability (random picking connection initialisation) with failover support for master replication cluster (for example Galera). |
|replication||High availability (random picking connection initialisation) with failover support for master/slaves replication cluster (one or multiple master) |
|aurora||High availability (random picking connection initialisation) with failover support for Amazon Aurora replication cluster |
See failover description for more information.
Optional URL parameters
General remark: Unknown options accepted and are silently ignored.
Following options are currently supported.
|user||Database user name. |
|password||Password of database user.|
|rewriteBatchedStatements||rewrite batchedStatement to have only one server call.|
|connectTimeout||The connect the timeout value, in milliseconds, or zero for no timeout.|
|useFractionalSeconds||Correctly handle subsecond precision in timestamps (feature available with MariaDB 5.3 and later).|
May confuse 3rd party components (Hibernated).
|allowMultiQueries||Allows multiple statements in single executeQuery.|
will be rewritten
|dumpQueriesOnException||If set to 'true', exception thrown during query execution contain query string.|
|useCompression||allow compression in MySQL Protocol.|
|useSSL||Force TLS on connection.|
|trustServerCertificate||When using TLS, do not check server's certificate.|
|serverSslCert||Server's certificatem in DER form, or server's CA certificate. |
Can be used in one of 3 forms :
* sslServerCert=/path/to/cert.pem (full path to certificate)
* sslServerCert=classpath:relative/cert.pem (relative to current classpath)
* or as verbatim DER-encoded certificate string "------BEGING CERTIFICATE-----" .
|socketFactory||to use custom socket factory, set it to full name of the class that implements javax.net.SocketFactory.|
|tcpNoDelay||Sets corresponding option on the connection socket.|
|tcpKeepAlive||Sets corresponding option on the connection socket.|
|tcpAbortiveClose||Sets corresponding option on the connection socket.|
|tcpRcvBuf||set buffer size for TCP buffer (SO_RCVBUF).|
|tcpSndBuf||set buffer size for TCP buffer (SO_SNDBUF).|
|pipe||On Windows, specify named pipe name to connect to mysqld.exe.|
|tinyInt1isBit||Datatype mapping flag, handle MySQL Tiny as BIT(boolean).|
|yearIsDateType||Year is date type, rather than numerical.|
|sessionVariables||<var>=<value> pairs separated by comma, mysql session variables, set upon establishing successfull connection.|
|localSocket||Allows to connect to database via Unix domain socket, if server allows it. |
The value is the path of Unix domain socket (i.e "socket" database parameter : select @@socket) .
|sharedMemory||Allowed to connect database via shared memory, if server allows it. |
The value is base name of the shared memory.
|localSocketAddress||Hostname or IP address to bind the connection socket to a local (UNIX domain) socket.|
|socketTimeout||Defined the network socket timeout (SO_TIMEOUT) in milliseconds. |
Default: 0 milliseconds(0 disable this timeout).
|interactiveClient||Session timeout is defined by the wait_timeout server variable. Setting interactiveClient to true will tell server to use the interactive_timeout server variable.|
|useOldAliasMetadataBehavior||Metadata ResultSetMetaData.getTableName() return the physical table name. "useOldAliasMetadataBehavior" permit to activate the legacy code that send the table alias if set. |
|createDatabaseIfNotExist||the specified database in url will be created if nonexistent.|
|serverTimezone||Defined the server time zone.|
to use only if jre server as a different time implementation of the server.
(best to have the same server time zone when possible).
|clientCertificateKeyStoreUrl||Use the specified keystore for client certificates (can be the same as the trusted root certificate keystore).|
*Default: false. Since 1.3.4*
|clientCertificateKeyStorePassword||Password for the client certificate keystore.|
*Default: false. Since 1.3.4*
|trustCertificateKeyStoreUrl||Use the specified keystore for trusted root certificates. Overrides serverSslCert.|
*Default: false. Since 1.3.4*
|trustCertificateKeyStorePassword||Password for the trusted root certificate keystore.|
*Default: false. Since 1.3.4*
|useServerPrepStmts||Query are prepared on server side before executing, permitting faster execution next time.|
if allowMultiQueries or rewriteBatchedStatements is set to true, this options will be set to false.
*Default: true. Since 1.3.0*
|prepStmtCacheSize||if useServerPrepStmts = true, defined the prepared statement cache size. |
*Default: 250. Since 1.3.0*
|prepStmtCacheSqlLimit||if useServerPrepStmts = true, defined queries that size is more than this size will not be cached. |
*Default: 2048. Since 1.3.0*
|jdbcCompliantTruncation||Truncation error ("Data truncated for column '%' at row %", "Out of range value for column '%' at row %") will be thrown as error, and not as warning.|
*Default: true. Since 1.4.0*
|cacheCallableStmts||enable/disable callable Statement cache|
*Default: true. Since 1.4.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*
Failover/High availability URL parameters
|autoReconnect||With basic failover: if true, will attempt to recreate connection after a failover. |
With standard failover: if true, will attempt to recreate connection even if there is a temporary solution (like using a master connection temporary until reconnect to a slave connection)
Default is false.
|retriesAllDown||When searching a valid host, maximum number of connection attempts before throwing an exception.|
Default: 120 seconds.
|failoverLoopRetries||When searching silently for a valid host, maximum number of connection attempts.|
This differ from "retriesAllDown" parameter, because this silent search is for example used after a disconnection of a slave connection when using the master connection
|validConnectionTimeout||With multiple hosts, after this time in seconds has elapsed it’s verified that the connections haven’t been lost.|
When 0, no verification will be done.
|loadBalanceBlacklistTimeout||When a connection fails, this host will be blacklisted during the "loadBalanceBlacklistTimeout" amount of time.|
When connecting to a host, the driver will try to connect to a host in the list of not blacklisted hosts and after that only on blacklisted ones if none has been found before that.
This blacklist is shared inside the classloader.
Default: 50 seconds.
|assureReadOnly||If true, in high availability, and switching to a read-only host, assure that this host is in read-only mode by setting session read-only.|
Default to false.
JDBC API Implementation Notes
Streaming result sets
Statement.executeQuery() will read full result set
from server before returning. With large result sets, this will require large
amounts of memory. Better behavior in this case would be reading row-by-row,
ResultSet.next(), so called "streaming" feature. It is
The driver uses server prepared statements as a standard to communicate with the database (since 1.3.0). If the "allowMultiQueries" or "rewriteBatchedStatements" options are set to true, the driver will only use text protocol. Prepared statements (parameter substitution) is handled by the driver, on the client side.
Callable statement implementation won't need to access stored procedure metadata (mysql.proc) table if both of following are true
- CallableStatement.getMetadata() is not used
- Parameters are accessed by index, not by name
When possible, following the two rules above provides both better speed and eliminates concerns about SELECT privileges on the mysql.proc table.
Optional JDBC classes
Following optional interfaces are implemented by the org.mariadb.jdbc.MariaDbDataSource class : javax.sql.DataSource, javax.sql.ConnectionPoolDataSource, javax.sql.XADataSource
careful : org.mariadb.jdbc.MySQLDataSource doesn't exist anymore and is to be replaced by org.mariadb.jdbc.MariaDbDataSource since v1.3.0
The following code provides a basic example of how to connect to a MariaDB or MySQL server and create a table.
Creating a table on a MariaDB or MySQL Server
Connection connection = DriverManager.getConnection("jdbc:mysql://localhost:3306/test", "username", "password"); Statement stmt = connection.createStatement(); stmt.executeUpdate("CREATE TABLE a (id int not null primary key, value varchar(20))"); stmt.close(); connection.close();