About the MariaDB Java Client

You are viewing an old version of this article. View the current version here.
DateReleaseStatusRelease NotesChangelog
2 May 2013MariaDB Java Client 1.1.2Stable (GA)Release NotesChangelog
1 Mar 2013MariaDB Java Client 1.1.1Stable (GA)Release NotesChangelog
15 Jan 2013MariaDB Java Client 1.1.0Stable (GA)Release NotesChangelog
29 Nov 2012MariaDB Java Client 1.0.0Stable (GA)

The MariaDB Client Library for Java Applications is used to connect applications developed in Java to MariaDB and MySQL databases using the standard JDBC API. The client library is LGPL licensed.

Introduction

The MariaDB Client Library for Java Applications 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

The driver (jar and source code) can be downloaded from https://downloads.mariadb.org/client-java/

Installing the driver

Installation is as simple as placing the .jar file in your classpath.

Requirements

  • Java 6
  • A MariaDB or MySQL Server
  • maven (only if you want build from source)

Source code

The source code is available on Launchpad: https://launchpad.net/mariadb-java-client. Development version can be obtained using

bzr branch lp:mariadb-java-client

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

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 and a database called 'test ', and user root with empty password

$ bzr branch lp:mariadb-java-client #  Or, unpack the source distribution tarball
$ cd mariadb-java-client
# 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

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 the MariaDB Client Library for Java Applications rather than your current connector.

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.

Driver Manager

Applications designed to use the driver manager to locate the entry point need no further configuration, the MariaDB Client Library for Java Applications will automatically be loaded and used in the way any previous MySQL driver would have been.

Driver Class

The driver class provided by the MariaDB Client Library for Java Applications is org.mariadb.jdbc.Driver.

Connection strings

Format of the JDBC connection string is

jdbc:mysql:<host>:<port>/<database>?<key1>=<value1>&<key2>=<value2>...

Altenatively

jdbc:mariadb:<host>:<port>/<database>?<key1>=<value1>&<key2>=<value2>...

can also be used.

Optional URL parameters

General remark: Unknown options accepted and are silently ignored.

Following options are currently supported.

keydescriptionsupported since version
userDatabase user name1.0.0
passwordPassword of database user1.0.0
fastConnectIf set, skips check for sql_mode, assumes NO_BACKSLASH_ESCAPES is *not* set1.0.0
useFractionalSecondsCorrectly handle subsecond precision in timestamps (feature available with MariaDB 5.3 and later).May confuse 3rd party components (Hibernated)1.0.0
allowMultiQueriesAllows multiple statements in single executeQuery1.0.0
dumpQueriesOnExceptionIf set to 'true', exception thrown during query execution contain query string1.1.0
useCompressionallow compression in MySQL Protocol1.0.0
useSSLForce SSL on connection (client certificates are not yet supported)1.1.0
socketFactoryto use custom socket factory, set it to full name of the class that implements javax.net.SocketFactory1.0.0
tcpNoDelaySets corresponding option on the connection socket1.0.0
tcpKeepAliveSets corresponding option on the connection socket1.0.0
tcpRcvBufset buffer size for TCP buffer (SO_RCVBUF)1.0.0
tcpSndBufset buffer size for TCP buffer (SO_SNDBUF)1.0.0
tinyInt1isBitDatatype mapping flag, handle MySQL Tiny as BIT(boolean)1.0.0
yearIsDateTypeYear is date type, rather than numerical1.0.0
sessionVariables<var>=<value> pairs separated by comma, mysql session variables, set upon establishing successfull connection1.1.0

JDBC API Implementation Notes

Streaming result sets

By default, 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, with ResultSet.next(), so called "streaming" feature. It is activated using ResultSet.setFetchSize(Integer.MIN_VALUE)

Prepared statements

The driver only uses text protocol to communicate with the database. 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 is true

  • CallableStatement.getMetadata() is not used
  • Parameters are accessed by index, not by name

When possible, following 2 rules above provides both better speed and eliminates concerns about SELECT privileges on mysql.proc table

Optional JDBC classes

Following optional interfaces are implemented by the org.mariadb.jdbc.MySQLDataSource class : javax.sql.DataSource, javax.sql.ConnectionPoolDataSource, javax.sql.XADataSource

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();

Comments

Comments loading...
Content reproduced on this site is the property of its respective owners, and this content is not reviewed in advance by MariaDB. The views, information and opinions expressed by this content do not necessarily represent those of MariaDB or any other party.