About MariaDB Connector/J
The most recent Stable (GA) release of MariaDB Connector/J is:
MariaDB Connector/J 3.3.3
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.
Date | Release | Status | Release Notes | Changelog |
---|---|---|---|---|
13 Oct 2016 | MariaDB Connector/J 1.5.4 | Stable (GA) | Release Notes | Changelog |
4 Oct 2016 | MariaDB Connector/J 1.5.3 | Stable (GA) | Release Notes | Changelog |
1 Sep 2016 | MariaDB Connector/J 1.5.2 | Stable (GA) | Release Notes | Changelog |
16 Aug 2016 | MariaDB Connector/J 1.5.1 | Release Candidate (RC) | Release Notes | Changelog |
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 MariaDB and MySQL database servers. It was originally based on the Drizzle JDBC code with numerous 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>
Requirements
- 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
https://github.com/twall/jna
- only needed when connecting to the server with unix sockets or windows shared memory
- A MariaDB or MySQL Server
- maven (only if you want to build from source)
Source code
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
License
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
This 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 building. 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 the default TCP port 3306) and a database called 'testj', and user 'root' with an 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 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 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.
Example:
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 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
jdbc:(mysql|mariadb):[replication:|failover:|sequential:|aurora:]//<hostDescription>[,<hostDescription>...]/[database][?<key1>=<value1>[&<key2>=<value2>]]
HostDescription:
<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
is 3306
. The default type is master
. If replication
failover is
set, by default the first host is master, and the others are slaves.
Examples :
localhost:3306
[2001:0660:7401:0200:0000:0000:0edf:bdd7]:3306
somehost.com:3306
address=(host=localhost)(port=3306)(type=master)
Failover parameters
Failover was introduced in Connector/J 1.2.0.
sequential | Failover support for master replication cluster (for example Galera) without High availability. The hosts will be connected in the order in which they were declared. Example when using the jdbc url string "jdbc:mysql:replication:host1,host2,host3/testdb" : When connecting, the driver will always first try host1, and if not available host2 and so on. After a host fail, the driver will reconnect according to this order. since 1.3.0 |
---|---|
failover | High availability (random picking connection initialisation) with failover support for master replication cluster (for example Galera). since 1.2.0 |
replication | High availability (random picking connection initialisation) with failover support for master/slave replication cluster (one or multiple masters) since 1.2.0 |
aurora | High availability (random picking connection initialisation) with failover support for Amazon Aurora replication cluster since 1.2.0 |
See failover description for more information.
Optional URL parameters
General remark: Unknown options are accepted and silently ignored.
The following options are currently supported.
Essential options
user | Database user name. since 1.0.0 |
---|---|
password | Password of database user. since 1.0.0 |
rewriteBatchedStatements | For insert queries, rewrite batchedStatement to execute in a single executeQuery. example: insert into ab (i) values (?) with first batch values = 1, second = 2 will be rewritteninsert into ab (i) values (1), (2) . If query cannot be rewriten in "multi-values", rewrite will use multi-queries : INSERT INTO TABLE(col1) VALUES (?) ON DUPLICATE KEY UPDATE col2=? with values [1,2] and [2,3]" will be rewrittenINSERT INTO TABLE(col1) VALUES (1) ON DUPLICATE KEY UPDATE col2=2; INSERT INTO TABLE(col1) VALUES (3) ON DUPLICATE KEY UPDATE col2=4 when active, the useServerPrepStmts option is set to false Default: false. Since 1.1.8 |
connectTimeout | The connect timeout value, in milliseconds, or zero for no timeout. Default: 0. Since 1.1.8 |
useServerPrepStmts | Queries are prepared on the server side before executing, permitting faster execution next time. if rewriteBatchedStatements is set to true, this option will be set to false. Default: true. Since 1.3.0 |
useBatchMultiSend | Driver will can send queries by batch. If disable, queries are send one by one, waiting for result before sending next one. If enable, queries will be send by batch corresponding to option useBatchMultiSendNumber value (default 100) or according to server variable @@max_allowed_packet if packet size cannot permit to send as many queries. Results will be read afterwhile, avoiding a lot of network latency when client and server aren't on same host. There is 2 differents use case : JDBC executeBatch() and when option useServerPrepStmts is enable and MariaDB server >= 10.2.1, PREPARE commands will be delayed, to send PREPARE + EXECUTE in the same packet. This option if mainly effective when client is distant from server. Default: true. Since 1.5.0 |
TLS (SSL)
useSSL | Force SSL/TLS on connection. Default: false. Since 1.1.0 |
---|---|
trustServerCertificate | When using SSL/TLS, do not check server's certificate. Default: false. Since 1.1.1 |
serverSslCert | Server's certificate 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-----" . since 1.1.3 |
keyStore | File path of the keyStore file that contain client private key store and associate certificates (similar to java System property "javax.net.ssl.keyStore", but ensure that only the private key's entries are used).(legacy alias clientCertificateKeyStoreUrl). Since 1.3.4 |
keyStorePassword | Password for the client certificate keyStore (similar to java System property "javax.net.ssl.keyStorePassword").(legacy alias clientCertificateKeyStorePassword) Since 1.3.4 |
keyPassword | Password for the private key in client certificate keyStore. (only needed if private key password differ from keyStore password). Since 1.5.3 |
trustStore | File path of the trustStore file (similar to java System property "javax.net.ssl.trustStore"). (legacy alias trustCertificateKeyStoreUrl) Use the specified file for trusted root certificates. When set, overrides serverSslCert. Since 1.3.4 |
trustStorePassword | Password for the trusted root certificate file (similar to java System property "javax.net.ssl.trustStorePassword"). (legacy alias trustCertificateKeyStorePassword). Since 1.3.4 |
enabledSslProtocolSuites | Force TLS/SSL protocol to a specific set of TLS versions (comma separated list). Example : "TLSv1, TLSv1.1, TLSv1.2" Default: TLSv1, TLSv1.1. Since 1.5.0 |
enabledSslCipherSuites | Force TLS/SSL cipher (comma separated list). Example : "TLS_DHE_RSA_WITH_AES_256_GCM_SHA384, TLS_DHE_DSS_WITH_AES_256_GCM_SHA384" Default: use JRE ciphers. Since 1.5.0 |
Log
log | Enable log information. require Slf4j version > 1.4 dependency. Log level correspond to Slf4j logging implementation Default: false. Since 1.5.0 |
---|---|
maxQuerySizeToLog | Only the first characters corresponding to this options size will be displayed in logs Default: 1024. Since 1.5.0 |
slowQueryThresholdNanos | Will log query with execution time superior to this value (if defined ) Default: 1024. Since 1.5.0 |
profileSql | log query execution time. Default: false. Since 1.5.0 |
Infrequently used
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 |
---|---|
allowMultiQueries | permit multi-queries like insert into ab (i) values (1); insert into ab (i) values (2) . Default: false. Since 1.0.0 |
dumpQueriesOnException | If set to 'true', an exception is thrown during query execution containing a query string. Default: false. Since 1.1.0 |
useCompression | allow compression in the MySQL Protocol. Default: false. Since 1.0.0 |
socketFactory | to use a custom socket factory, set it to the full name of the class that implements javax.net.SocketFactory. since 1.0.0 |
tcpNoDelay | Sets corresponding option on the connection socket. since 1.0.0 |
tcpKeepAlive | Sets corresponding option on the connection socket. since 1.0.0 |
tcpAbortiveClose | Sets corresponding option on the connection socket. since 1.1.1 |
tcpRcvBuf | set buffer size for TCP buffer (SO_RCVBUF). since 1.0.0 |
tcpSndBuf | set buffer size for TCP buffer (SO_SNDBUF). since 1.0.0 |
pipe | On Windows, specify named pipe name to connect to mysqld.exe. since 1.1.3 |
tinyInt1isBit | Datatype mapping flag, handle MySQL Tiny as BIT(boolean). Default: true. Since 1.0.0 |
yearIsDateType | Year is date type, rather than numerical. Default: true. Since 1.0.0 |
sessionVariables | <var>=<value> pairs separated by comma, mysql session variables, set upon establishing successful connection. since 1.1.0 |
localSocket | Permits connecting to the database via Unix domain socket, if the server allows it. The value is the path of Unix domain socket (i.e "socket" database parameter : select @@socket) . since 1.1.4 |
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 |
localSocketAddress | Hostname or IP address to bind the connection socket to a local (UNIX domain) socket. since 1.1.7 |
socketTimeout | Defined the network socket timeout (SO_TIMEOUT) in milliseconds. Default: 0 milliseconds(0 disable this timeout). since 1.1.7 |
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 |
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 |
createDatabaseIfNotExist | the specified database in the url will be created if nonexistent. Default: false. Since 1.1.7 |
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 |
prepStmtCacheSize | if useServerPrepStmts = true, defines the prepared statement cache size. Default: 250. Since 1.3.0 |
prepStmtCacheSqlLimit | if useServerPrepStmts = true, defined queries larger 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 an error, and not as a 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 |
useBatchMultiSendNumber | When option useBatchMultiSend is active, indicate the maximum query send in a row before reading results. Default: 100. Since 1.5.0 |
connectionAttributes | When performance_schema is active, permit to send server some client information in a key;value pair format (example: connectionAttributes=key1:value1,key2,value2). Those informations can be retrieved on server within tables performance_schema.session_connect_attrs and performance_schema.session_account_connect_attrs. This can permit from server an identification of client/application 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. since 1.1.7 |
---|---|
retriesAllDown | When searching a valid host, maximum number of connection attempts before throwing an exception. Default: 120 seconds. since 1.2.0 |
failoverLoopRetries | When searching silently for a valid host, maximum number of connection attempts. This differs from the "retriesAllDown" parameter because this silent search is for example used after a disconnection of a slave connection when using the master connection Default: 120. since 1.2.0 |
validConnectionTimeout | With multiple hosts, after this time in seconds has elapsed, verifies that the connections haven’t been lost. When 0, no verification will be done. Default:120 seconds since 1.2.0 |
loadBalanceBlacklistTimeout | When a connection fails, this host will be blacklisted for the "loadBalanceBlacklistTimeout" amount of time. 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 |
assureReadOnly | If true, in high availability, and switching to a read-only host, assure that this host is in read-only mode by setting the session to read-only. Default to false. Since 1.3.0 |
JDBC API implementation notes
"LOAD DATA INFILE"
The fastest way to load lots of data is using LOAD DATA INFILE.
However, using "LOAD DATA LOCAL INFILE" (ie : loading a file from client) may be a security problem :
- A "man in the middle" proxy server can change the actual file requested from the server so the client will send a local file to this proxy.
- if someone can execute a query from the client, he can have access to any file on the client (according to the rights of the user running the client process).
A specific option "allowLocalInfile" (default to true) can deactivate functionality on the client side. The global variable local_infile can disable LOAD DATA LOCAL INFILE on the server side.
A non-JDBC method can permit using this kind of query without this security issue: The application has to create an InputStream with the file to load. If MariaDbStatement.setLocalInfileInputStream(InputStream inputStream) is set, the inputStream will be sent to the server, replacing the file content (working even with the "allowLocalInfile" option disabled).
Code example:
Statement statement = ... InputStream in = new FileInputStream("/file.sql"); if (statement.isWrapperFor(MariaDbStatement.class)) { MariaDbStatement mariaDbStatement = statement.unwrap(MariaDbStatement.class); mariaDbStatement.setLocalInfileInputStream(in); String sql = "LOAD DATA LOCAL INFILE 'dummyFileName'" + " INTO TABLE gigantic_load_data_infile " + " FIELDS TERMINATED BY '\\t' ENCLOSED BY ''" + " ESCAPED BY '\\\\' LINES TERMINATED BY '\\n'"; statement.execute(sql); } else { in.close(); throw new RuntimeException("Mariadb JDBC adaptor must be used"); }
Since 1.5.0, Interceptors can now filter LOAD DATA LOCAL INFILE queries according to filename.
These interceptors must implement the org.mariadb.jdbc.LocalInfileInterceptor
interface.
Interceptors use the ServiceLoader pattern, so interceptors must be defined in the META-INF/services/org.mariadb.jdbc.LocalInfileInterceptor file.
Example :
Create the META-INF/services/org.mariadb.jdbc.LocalInfileInterceptor file with content org.project.LocalInfileInterceptorImpl.
public class LocalInfileInterceptorImpl implements LocalInfileInterceptor { @Override public boolean validate(String fileName) { File file = new File(fileName); String absolutePath = file.getAbsolutePath(); String filePath = absolutePath.substring(0,absolutePath.lastIndexOf(File.separator)); return filePath.equals("/var/tmp/exchanges"); } }
You can avoid defining the META-INF/services file using google auto-service framework
Using the previous example, just add @AutoService(LocalInfileInterceptor.class)
, and your interceptor will be automatically defined.
@AutoService(LocalInfileInterceptor.class) public class LocalInfileInterceptorImpl implements LocalInfileInterceptor { @Override public boolean validate(String fileName) { File file = new File(fileName); String absolutePath = file.getAbsolutePath(); String filePath = absolutePath.substring(0,absolutePath.lastIndexOf(File.separator)); return filePath.equals("/var/tmp/exchanges"); } }
Streaming result sets
By default, Statement.executeQuery()
will read the full result set from the server.
With large result sets, this will require large amounts of memory.
To avoid using too much memory, rather use Statement.setFetchSize(int numberOfRowInMemory) to indicate the number of rows that will be stored in memory
Example :
using Statement.setFetchSize(1000)
indicates that 1000 rows will be stored in memory.
So, when the query has executed, 1000 rows will be in memory. After 1000 ResultSet.next()
, the next 1000 rows will be stored in memory, and so on.
Note that the server usually expects clients to read off the result set relatively quickly. The server variable "net_write_timeout" controls this behavior (defaults to 60s). If you don't expect results to be handled in this amount of time there is a different possibility :
- if your server version > 10.1.2, you can use the query "SET STATEMENT net_write_timeout=10000 FOR XXX" with XXX your "normal" query. This will indicate that specifically for this query, net_write_timeout will be set to a longer time (10000 in this example).
- for older servers, a specific query will have to temporarily set net_write_timeout ("SET STATEMENT net_write_timeout=..."), and set it back afterwards.
- if your application usually uses a lot of long queries with fetch size, the connection can be set using option "sessionVariables=net_write_timeout=xxx"
Even using setFetchSize, the server will send all results to the client. Sending another query on the same connection will throw an exception until all results aren't read.
Before version 1.4.0, the only accepted value for fetch size was Statement.setFetchSize(Integer.MIN_VALUE)
(equivalent to Statement.setFetchSize(1)
). This value is still accepted for compatilibity reasons but rather use Statement.setFetchSize(1)
, since according to JDBC the value must be >= 0.
Prepared statements
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.
CallableStatement
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
The 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 should be replaced with org.mariadb.jdbc.MariaDbDataSource since v1.3.0
Usage examples
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();