MariaDB4j

Please :star: Star on GitHub and 💸 support on OpenCollective, via GitHub Sponsoring or through a Tidelift subscription to ensure active maintenance of this project used by hundreds, since 2011! 🫶

• What?
• Usage
• DB API
• Spring
• JUnit
• Maven Plugin
• CLI
• Maven Artifacts
• Binaries
• Why?
• FAQ
• Related Projects
• Release Notes
• Contributors
• End Users
• Sponsors

What?

MariaDB4j is a Java (!) "launcher" for MariaDB (the "backward compatible, drop-in replacement of the MySQL® Database Server", see Wikipedia), allowing you to use MariaDB (MySQL®) from Java without ANY installation / external dependencies. Read again: You do NOT have to have MariaDB binaries installed on your system to use MariaDB4j!

Usage

DB API

The MariaDB native binaries are in the MariaDB4j-DB-win/linux/mac*.JARs on which the main MariaDB4j JAR depends on by Maven transitive dependencies and, by default, are extracted from the classpath to a temporary base directory on the fly, then started by Java.

An example of this can be found in the source tree, in MariaDB4jSampleTutorialTest.java. Basically, you can simply:

1. Install the database with a particular configuration, using short-cut:

java DB db = DB.newEmbeddedDB(3306);

1. (Optional) The data directory will, by default, be in a temporary directory too, and will automatically get scratched at every restart; this is suitable for integration tests. If you use MariaDB4j for something more permanent (maybe an all-in-one application package?), then you can simply specify a more durable location of your data directory in the DBConfiguration, like so:

java DBConfigurationBuilder configBuilder = DBConfigurationBuilder.newBuilder(); configBuilder.setPort(3306); // OR, default: setPort(0); => autom. detect free port configBuilder.setDataDir("/home/theapp/db"); // just an example DB db = DB.newEmbeddedDB(configBuilder.build());

1. Start the database

java db.start();

1. Use the database as per standard JDBC usage. In this example, you're acquiring a JDBC Connection from the DriverManager; note that you could easily configure this URL to be used in any JDBC connection pool. MySQL uses a test database by default, and a root user with no password is also a default.

java Connection conn = DriverManager.getConnection("jdbc:mariadb://localhost/test", "root", "");

A similar suitable JDBC URL as String can normally also be directly obtained directly from the MariaDB4j API, if you prefer (this is especially useful for tests if you let MariaDB4j automatically choose a free port, in which case a hard-coded URL is problematic):

java Connection conn = DriverManager.getConnection(configBuilder.getURL(dbName), "root", "");

1. If desired, load data from a SQL resource, located in the classpath:

java db.source("path/to/resource.sql");

If you would like to / need to start a specific DB version you already have, instead of the version currently packaged in the JAR, you can use DBConfigurationBuilder setUnpackingFromClasspath(false) & setBaseDir("/my/db/") or -DmariaDB4j.unpack=false -DmariaDB4j.baseDir=/home/you/stuff/myFavouritemMariadDBVersion. Similarly, you can also pack your own version in a JAR and put it on the classpath, and @Override getBinariesClassPathLocation() in DBConfigurationBuilder to return where to find it (check the source of the default implementation).

To reopen a previously created database, use

DB.openEmbeddedDB(configBuilder.build());

Spring

MariaDB4j can be used in any Java Application on its own. It is not dependent on dependency injection or the Spring Framework (the dependency to the spring-core*.jar is for a utility, and is unrelated to DI).

If you want to use MariaDB4j with Spring-boot the opinionated presets for spring applications, then you can easily use this the ready-made MariaDB4jSpringService to reduce your coding/configuration to get you going, we have an example application (mariaDB4j-app) which illustrates how to wire it up or as an alternative approach via the MariaDB4jSpringServiceTestSpringConfiguration.

The DataSource initialization have to wait until MariaDB is ready to receive connections, so we provide mariaDB4j-springboot to implement it. You can use it by :

dependencies {
   testCompile("ch.vorburger.mariaDB4j:mariaDB4j-springboot:3.1.0")
}

In the module, bean name of MariaDB4jSpringService is mariaDB4j, and dataSource depends on it by name. So if you want to customize your mariaDB4j, please make sure the name is correctly.

In issue #64 there is also a discussion about it and pointing to a TestDbConfig.java gist.

JUnit

Using the JUnit feature of Rules a MariaDB4JRule class is available to be used in your tests.

Add it as a @Rule to your test class

public class TestClass {
    @Rule
    public MariaDB4jRule dbRule = new MariaDB4jRule(0); //port 0 means select random available port

    @Test
    public void test() {
        // Do whatever you want with the running DB
    }
}

The MariaDB4jRule provides 2 methods for getting data on the running DB:

• getURL() - Get the JDBC connection string to the running DB

java @Test public void test() { Connection conn = DriverManager.getConnection(dbRule.getURL(), "root", ""); }

• getDBConfiguration() - Get the Configuration object of the running DB, exposing properties such as DB Port, Data directory, Lib Directory and even a reference to the ProcessListener for the DB process.

```java public class TestClass { @Rule public MariaDB4jRule dbRule = new MariaDB4jRule(3307);

@Test
public void test() {
    assertEquals(3307, dbRule.getDBConfiguration().getPort());
}

}

```

The MariaDB4jRule class extends the JUnit ExternalResource - which means it starts the DB process before each test method is run, and stops it at the end of that test method.

The MariaDB4jRule(DBConfiguration dbConfiguration, String dbName, String resource) Constructor, allows to initialize your DB with a provided SQL Script (resource = path to script file) to setup needed database, tables and data.

This rule, can also be used as a @ClassRule to avoid DB Process starting every test - just make sure to clean/reset your data in the DB.

Maven Plugin

mariadb4j-maven-plugin is a Maven plugin that starts and stops a MariaDB instance for the integration test phase.

See POM and integration test in https://github.com/MariaDB4j/MariaDB4j/tree/mariaDB4j-maven-plugin/mariaDB4j-maven-plugin/src/it/mariadb4j-maven-plugin-test-basic for usage example.

Example

An example usage of this plugin is to install and start a database at the start of the integration test phase, and stop and uninstall the database afterwards.

This is done by configuring the plugin to execute the start goal in the pre-integration-test phase and the stop goal in the post-integration-test phase:

<plugin>
  <groupId>ch.vorburger.mariaDB4j</groupId>
  <artifactId>mariaDB4j-maven-plugin</artifactId>
  ...
  <executions>
    <execution>
      <id>pre-integration-test</id>
      <goals>
        <goal>start</goal>
      </goals>
    </execution>
    <execution>
      <id>post-integration-test</id>
      <goals>
        <goal>stop</goal>
      </goals>
    </execution>
  </executions>
</plugin>

This will ensure there is a MariaDB instance running on a random port, and expose the database URL as a Maven Project property.

To access the database in your integration tests, you can pass the database URL as system property to your integration tests:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-failsafe-plugin</artifactId>
  ...
  <configuration>
    <systemProperties>
      <mariadb.databaseurl>${mariadb4j.databaseurl}</mariadb.databaseurl>
    </systemProperties>
  </configuration>
</plugin>

CLI

Because the MariaDB4j JAR is executable, you can also quickly fire up a database from a command line interface:

java [-DmariaDB4j.port=3718] [-DmariaDB4j.baseDir=/home/theapp/bin/mariadb4j] [-DmariaDB4j.dataDir=/home/theapp/db] -jar mariaDB4j-app*.jar

Note the use of the special mariaDB4j-app*.jar for this use-case, its a fat/shaded/über-JAR, based on a Spring Boot launcher.

Maven Artifacts

MariaDB4j JARs are available from:

1. Maven Central; we're proud to be a reproducible build:

xml <dependency> <groupId>ch.vorburger.mariaDB4j</groupId> <artifactId>mariaDB4j</artifactId> <version>3.1.0</version> </dependency>

1. https://jitpack.io: main-SNAPSHOT, releases, see also issue #41 discussion

2. Not Bintray! (Up to version 2.1.3 MariaDB4j was on Bintray. Starting with version 2.2.1 we’re only using Maven central. The 2.2.1 that is on Bintray is broken.)

3. Local build: For bleeding edge -SNAPSHOT versions, you (or your build server) can easily build it yourself from source; just git clone this repo, and then ./mvnw install (or deploy) it. -- MariaDB4j's Maven then coordinates are:

Binaries

MariaDB4j also supports using existing native MariaDB binaries on the host system rather than unpacking MariaDB from the classpath. This is useful if you need a newer version than is currently distributed. You can control this via the DBConfigurationBuilder:

import static ch.vorburger.mariadb4j.DBConfiguration.Executable.Server;
import ch.vorburger.mariadb4j.DBConfigurationBuilder;

DBConfigurationBuilder config = DBConfigurationBuilder.newBuilder();
config.setPort(0); // 0 => autom. detect free port
config.setUnpackingFromClasspath(false);
config.setLibDir(System.getProperty("java.io.tmpdir") + "/MariaDB4j/no-libs");

// On Linux it may be necessary to set both the base dir and the server executable
// as the `mysqld` binary lives in `/usr/sbin` rather than `/usr/bin`
config.setBaseDir("/usr");
config.setExecutable(Server, "/usr/sbin/mysqld");

// On MacOS with MariaDB installed via homebrew, you can just set base dir to the output of `brew --prefix`
config.setBaseDir("/usr/local") // or "/opt/homebrew" for M1 Macs

Core

If you use your own packaged versions of MariaDB native binaries, then the mariaDB4j-core artifact JAR, which contains only the launcher Java code but no embedded native binaries, will be more suitable for you.

You can also exclude one of artifacts of the currently 3 packaged OS platforms to save download if your project / community is mono-platform.

You could also override the version(s) of the respective (transitive) mariaDB4j-db-* dependency to downgrade it, and should so be able to use the latest mariaDB4j-core artifact JARs, even with older`versions of the JAR archives containing the native mariaDB executables etc. This may be useful if your project for some reason needs a fixed older DB version, but wants to get the latest MariaDB4j launcher Java code.

Why?

Being able to start a database without any installation / external dependencies is useful in a number of scenarios, such as all-in-one application