mariadb-corporation MariaDB Connector/J: Installation and Configuration
Last updated: 2026-08-10
MariaDB Connector/J is the Type 4 JDBC driver for MariaDB, written in pure Java with no dependency on MariaDB Connector/C. This skill covers adding it to a build, configuring the connection URL and datasource, and setting up TLS. For writing JDBC code against it, see mariadb-connector-j-usage.
Default context: Assume the 3.5 stable line unless the user states otherwise. Connector versions are independent of the MariaDB server version.
What LLMs Often Miss
| If the agent writes / assumes… | …prefer the MariaDB form |
|---|---|
Guesses the coordinates from the product name (mariadb-connector-j, mariadb-jdbc) |
The artifact is org.mariadb.jdbc:mariadb-java-client and the driver class is org.mariadb.jdbc.Driver. Nothing else registers the jdbc:mariadb: scheme |
Writes a jdbc:mysql:// URL |
From 3.0 onward only jdbc:mariadb: is accepted by default. jdbc:mysql: works only when the permitMysqlScheme option is present in the URL — and using jdbc:mariadb: is what guarantees this driver is chosen when several drivers are on the classpath |
Configures a Unix domain socket or a Windows named pipe and gets a ClassNotFoundException |
JNA is not pulled in transitively. Those transports use com.sun.jna, so the application must add net.java.dev.jna:jna and net.java.dev.jna:jna-platform (4.2.1 or later) itself. TCP connections need neither |
Sets serverSslCert and assumes the connection is now encrypted |
It is not. sslMode defaults to disable — the certificate option alone changes nothing. TLS starts only when sslMode is set to trust, verify-ca, or verify-full (the exception: a credential plugin that requires TLS forces verify-full) |
Reaches for useSsl=true / trustServerCertificate=true on a 3.x driver |
Those are the 2.x spellings. Since 3.0 the single option is sslMode, with values disable, trust, verify-ca, verify-full; sslMode=true and sslMode=1 are aliases for verify-full |
Uses sslMode=trust in production because it "makes TLS work" |
trust encrypts but verifies nothing, so it defends against passive eavesdropping only. Use it to prove the server has TLS enabled, then move to verify-full |
| Assumes a certificate must be a file on disk | serverSslCert accepts three forms: a full file path, a classpath:-relative path, or the certificate text inline. The last is what makes a certificate deployable through configuration alone |
| Ships a custom truststore and expects the public CAs to stop working | The connector falls back to the JVM's default truststore when serverSslCert does not resolve. Set fallbackToSystemTrustStore=false to make trust exclusive |
| Targets a Java version the chosen release series does not cover | 3.5, 3.4, and 3.3 run on Java 8, 11, 17, 21, and 25. Pick the release series from the Java version, not the other way round |
| Recommends the 2.7 line for a Java 8 project | Unnecessary — the current 3.x lines still support Java 8, and 2.7 is a legacy series. Start new work on 3.5 |
Registers the driver with Class.forName(...) because that is the JDBC habit |
Service loading handles it: DriverManager.getConnection("jdbc:mariadb://…") is enough. Class.forName("org.mariadb.jdbc.Driver") still works but is redundant |
| Reaches for an external pool without setting the driver class | With HikariCP or similar, set driverClassName to org.mariadb.jdbc.Driver. The driver also ships its own pool, MariaDbPoolDataSource, whereas MariaDbDataSource opens a fresh connection on every getConnection() |
Installing
Maven
<dependency>
<groupId>org.mariadb.jdbc</groupId>
<artifactId>mariadb-java-client</artifactId>
<version>3.5.9</version>
</dependency>
Gradle
implementation 'org.mariadb.jdbc:mariadb-java-client:3.5.9'
Optional dependencies
Add these only for the features that need them:
<!-- Unix domain sockets and Windows named pipes: JNA 4.2.1 or later -->
<dependency>
<groupId>net.java.dev.jna</groupId>
<artifactId>jna</artifactId>
<version>$JNA_VERSION</version>
</dependency>
<dependency>
<groupId>net.java.dev.jna</groupId>
<artifactId>jna-platform</artifactId>
<version>$JNA_VERSION</version>
</dependency>
Manual JAR, and building from source
The .jar can be placed on the CLASSPATH directly, though a build tool is the better option. To build:
git clone https://github.com/MariaDB/mariadb-connector-j.git
cd mariadb-connector-j
mvn -Dmaven.test.skip=true package # result: target/mariadb-java-client-x.y.z.jar
Building with the tests enabled (mvn package) needs a MariaDB or MySQL server listening on localhost:3306, a database named testj, and a root account with an empty password.
Configuration
Connection URL
jdbc:mariadb://host:port/database?option1=value1&option2=value2
Connection conn = DriverManager.getConnection(
"jdbc:mariadb://localhost:3306/appdb?user=app&password=secret&sslMode=verify-full");
Options can equally be passed as a Properties object, which keeps credentials out of a URL that might end up in a log.
TLS
// Step 1 — confirm the server offers TLS at all (encrypts, verifies nothing)
"jdbc:mariadb://localhost/appdb?user=app&password=secret&sslMode=trust"
// Step 2 — the production setting
"jdbc:mariadb://localhost/appdb?user=app&password=secret"
+ "&sslMode=verify-full&serverSslCert=/etc/ssl/certs/ca.pem"
| Option | Effect |
|---|---|
sslMode |
disable (default), trust, verify-ca, verify-full |
serverSslCert |
Server or CA certificate: file path, classpath:…, or the certificate text inline |
trustStore, trustStorePassword, trustStoreType |
Use a Java truststore instead of a single certificate |
keyStore, keyStorePassword, keyPassword, keyStoreType |
Client certificate for mutual TLS |
fallbackToSystemTrustStore |
false stops the fallback to the JVM's default CA set |
disableSslHostnameVerification |
Legacy spelling; prefer sslMode=verify-ca |
If the server's certificate chains to a well-known public CA already in the JVM truststore, sslMode=verify-full on its own is enough — no certificate option required.
Pooling
MariaDbPoolDataSource ds = new MariaDbPoolDataSource(
"jdbc:mariadb://localhost:3306/appdb?user=app&password=secret&maxPoolSize=20");
The built-in pool cleans connection state on release and drops connections that have gone idle, which avoids the classic failure of handing out a connection the server has already closed at wait_timeout. With an external pool, configure org.mariadb.jdbc.Driver as the driver class and let that pool own the lifecycle.
See Also
mariadb-connector-j-usage— using the driver once it is on the classpath: statements, batches, generated keys, streaming, transactionsmariadb-connector-r2dbc-install— the reactive alternative for non-blocking applications- Canonical reference on
mariadb.com/docs, consult for edge cases not covered here: https://mariadb.com/docs/connectors/mariadb-connector-j
This page is: Copyright © 2026 MariaDB. All rights reserved.