MariaDB Client for Java

The MariaDB Client for Java 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 for Java is a Type 4 JDBC driver. It was developed specifically as a lightweight JDBC connector for use with MySQL and Drizzle database servers. It's based on the Drizzle JDBC driver with a lot of additions and fixes.

Obtaining the driver

The driver is downloaded from http://downloads.mariadb.org

Installing the driver

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

Requirements

• Java 5 or Java 6
• maven (if you are testing / building from source)
• A MariaDB, MySQL or Drizzle Server (both MariaDB/MySQL and Drizzle are needed if building/ testing from source)

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 for Java uses maven. You first need to ensure you have both java and maven installed on your server before you can build the driver.

Currently, the test suite is more development oriented, but we provide information on how to run it in case the user wishes to do so.

Note You will need a drizzle server running on localhost and a schema called test_units_jdbc to be able to package the JDBC jar binary (tests need to be run successfully to build the package)

Note You will also need a MariaDB or MySQL server running on localhost with a no-username-password user which has access to a test_units_jdbc database. The username/password can be changed, look in the constructor of src/test/java/org/mariadb/jdbc/MySQLDriverTest.java

To execute the test suite: To run the test suite, you need a running version of drizzled on localhost with a database called test_units_jdbc: $ mvn test

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 for Java rather than your current connector.

Using the driver

The following subsections show the formatting of JDBC connection strings for MariaDB, MySQL and Drizzle database servers. Additionally, sample code is provided that demonstrates how to connect to one of these servers and create a table.

As this is a standard JDBC driver, it should be a drop-in replacement for any other driver. Certain features outside the standard from other drivers may not currently be implemented / available.

Driver Manager

Applications designed to use the driver manager to locate the entry point need no further configuration, the MariaDB Client for Java 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 for Java is org.mariadb.jdbc.Driver. This provides a standard JDBC driver interface and also allows used of the javax PoolConnections.

Connection strings

Use the following connection strings when connecting to one of the listed database servers.

MariaDB and MySQL connections

jdbc:mysql:<host>:<port>/<database>;username=<username>;password=<password>

Drizzle connections

jdbc:drizzle:<username>:<password>@<host>:<port>/<database>

Usage examples

The following code provides a basic example of how to connect to a MariaDB, MySQL or Drizzle server and create a table.

Creating a table on a MariaDB or MySQL Server

Connection connection = DriverManager.getConnection("jdbc:mysql:localhost:3306/test_units_jdbc", "username", "password"); Statement stmt = connection.createStatement(); stmt.executeUpdate("CREATE TABLE a (id int not null primary key, value varchar(20))"); stmt.close(); connection.close();

Creating a table on a Drizzle Server

Connection connection = DriverManager.getConnection("jdbc:drizzle:localhost:4427/test_units_jdbc"); Statement stmt = connection.createStatement(); stmt.executeUpdate("CREATE TABLE a (id int not null primary key, value varchar(20))"); stmt.close(); connection.close();

Data Types

This section documents anything of note regarding how the driver handles data types

Time

Since Drizzle does not support the JDBC Time datatype, it is stored as milliseconds in an integer in the database. Format is like this

Look at Utils.java for more information about how it is implemented

Bytes

The setBytes(...) method on a PreparedStatement inserts an array of bytes in a binary datatype. This differs from the way Connector/J handles byte arrays - it converts it to a hex string and inserts that.

Plugin interfaces

Batch Query Handler

The batch query handler is used when a client needs to send alot of queries to a server in batch mode. Depending on the client workload there could be places where a better batch query handler could improve performance. Therefore drizzle-jdbc supports pluggable batch query handlers. First you need to build the actual batch handler, this is done by implementing a small interface:

public interface ParameterizedBatchHandler {
    /**
     * called when a set of parameters are added to a batch.
     * @param query the parameterized query.
     */
    void addToBatch(ParameterizedQuery query);

    /**
     * execute the batch using protocol. Return an array of update counts
     * or -2 (Statement.SUCCESS_NO_INFO) if the update count is unknown.
     * @return a list of update counts
     * @throws QueryException if something goes wrong executing the query.
     */