0
# MariaDB JDBC Driver
1

2
MariaDB Connector/J is a comprehensive JDBC 4.2 compatible driver that provides high-performance database connectivity for Java applications connecting to MariaDB and MySQL databases. It offers enterprise-grade features including connection pooling, high availability configurations, SSL/TLS security, comprehensive authentication methods, and extensive configuration options for both simple applications and complex enterprise deployments.
3

4
## Package Information
5

6
- **Package Name**: mariadb-java-client
7
- **Package Type**: Maven
8
- **Group ID**: org.mariadb.jdbc
9
- **Artifact ID**: mariadb-java-client
10
- **Language**: Java
11
- **Installation**: Add to pom.xml dependencies:
12

13
```xml
14
<dependency>
15
  <groupId>org.mariadb.jdbc</groupId>
16
  <artifactId>mariadb-java-client</artifactId>
17
  <version>3.5.3</version>
18
</dependency>
19
```
20

21
## Core Imports
22

23
```java
24
import java.sql.*;
25
import javax.sql.*;
26
import org.mariadb.jdbc.*;
27
```
28

29
For advanced features:
30

31
```java
32
import org.mariadb.jdbc.export.*;
33
import org.mariadb.jdbc.plugin.*;
34
import org.mariadb.jdbc.type.*;
35
```
36

37
## Basic Usage
38

39
```java
40
import java.sql.*;
41

42
// Simple connection
43
String url = "jdbc:mariadb://localhost:3306/mydb";
44
Connection conn = DriverManager.getConnection(url, "user", "password");
45

46
// Execute query
47
Statement stmt = conn.createStatement();
48
ResultSet rs = stmt.executeQuery("SELECT * FROM users");
49
while (rs.next()) {
50
    System.out.println(rs.getString("name"));
51
}
52

53
// Prepared statement
54
PreparedStatement pstmt = conn.prepareStatement("INSERT INTO users (name, email) VALUES (?, ?)");
55
pstmt.setString(1, "John Doe");
56
pstmt.setString(2, "john@example.com");
57
pstmt.executeUpdate();
58

59
// Clean up
60
rs.close();
61
stmt.close();
62
pstmt.close();
63
conn.close();
64
```
65

66
## Architecture
67

68
The MariaDB JDBC driver is built around several key architectural components:
69

70
- **JDBC Standards Compliance**: Full implementation of JDBC 4.2 specification with Connection, Statement, PreparedStatement, CallableStatement, and DatabaseMetaData
71
- **Multi-Host Support**: High availability modes including replication, load balancing, and sequential failover
72
- **Connection Management**: Built-in connection pooling with JMX monitoring and lifecycle management
73
- **Plugin Architecture**: Extensible authentication, credential management, TLS, and data type codec systems
74
- **Multi-Version Support**: Java 8+ compatibility with multi-release JAR supporting up to Java 15+ features
75

76
## Capabilities
77

78
### Database Connections
79

80
Core connection functionality for establishing and managing database connections with comprehensive configuration options, SSL/TLS security, and multi-host support.
81

82
```java { .api }
83
public class Driver implements java.sql.Driver {
84
  public Connection connect(String url, Properties props) throws SQLException;
85
  public static Connection connect(Configuration configuration) throws SQLException;
86
  public boolean acceptsURL(String url) throws SQLException;
87
  public DriverPropertyInfo[] getPropertyInfo(String url, Properties info) throws SQLException;
88
}
89

90
public class Connection implements java.sql.Connection {
91
  public void cancelCurrentQuery() throws SQLException;
92
  // Standard JDBC Connection methods...
93
}
94
```
95

96
[Database Connections](./connections.md)
97

98
### Data Sources
99

100
DataSource implementations for connection pooling, XA transactions, and enterprise application server integration with comprehensive JNDI support.
101

102
```java { .api }
103
public class MariaDbDataSource implements DataSource, ConnectionPoolDataSource, XADataSource {
104
  public Connection getConnection() throws SQLException;
105
  public Connection getConnection(String username, String password) throws SQLException;
106
  public PooledConnection getPooledConnection() throws SQLException;
107
  public XAConnection getXAConnection() throws SQLException;
108
  public void setUrl(String url);
109
  public String getUrl();
110
}
111

112
public class MariaDbPoolDataSource extends MariaDbDataSource implements Closeable, AutoCloseable {
113
  public void close() throws SQLException;
114
}
115
```
116

117
[Data Sources](./data-sources.md)
118

119
### Configuration Management
120

121
Comprehensive configuration system with 100+ options for connection behavior, performance tuning, security settings, and high availability configuration.
122

123
```java { .api }
124
public class Configuration {
125
  public static Configuration parse(String url, Properties props) throws SQLException;
126
  
127
  // Connection properties
128
  public String user();
129
  public String password();
130
  public String database();
131
  public List<HostAddress> addresses();
132
  public HaMode haMode();
133
  
134
  // SSL/TLS properties
135
  public SslMode sslMode();
136
  public String serverSslCert();
137
  public String keyStore();
138
  public String trustStore();
139
  
140
  // Performance properties
141
  public boolean useCompression();
142
  public boolean cachePrepStmts();
143
  public int prepStmtCacheSize();
144
  public boolean useServerPrepStmts();
145
}
146
```
147

148
[Configuration](./configuration.md)
149

150
### High Availability
151

152
Multi-host connection support with automatic failover, load balancing, and replication awareness for enterprise-grade availability.
153

154
```java { .api }
155
public enum HaMode {
156
  NONE, REPLICATION, SEQUENTIAL, LOADBALANCE, LOAD_BALANCE_READ;
157
  
158
  public Optional<HostAddress> getAvailableHost(
159
    List<HostAddress> hostAddresses,
160
    ConcurrentMap<HostAddress, Long> denyList,
161
    boolean primary
162
  );
163
}
164

165
public class HostAddress {
166
  public static HostAddress from(String host, int port);
167
  public static HostAddress from(String host, int port, boolean primary);
168
  public static HostAddress pipe(String pipe);
169
  public static HostAddress localSocket(String localSocket);
170
  public static List<HostAddress> parse(String spec, HaMode haMode);
171
}
172
```
173

174
[High Availability](./high-availability.md)
175

176
### Statement Execution
177

178
Comprehensive statement execution support including prepared statements, callable statements, batch operations, and streaming result sets.
179

180
```java { .api }
181
public class Statement implements java.sql.Statement {
182
  // Standard JDBC Statement methods
183
}
184

185
public class ClientPreparedStatement extends BasePreparedStatement {
186
  // Client-side prepared statement implementation
187
}
188

189
public class ServerPreparedStatement extends BasePreparedStatement {
190
  // Server-side prepared statement implementation
191
}
192

193
public class BaseCallableStatement extends BasePreparedStatement implements CallableStatement {
194
  // Callable statement for stored procedures and functions
195
}
196
```
197

198
[Statement Execution](./statements.md)
199

200
### Data Types and Codecs
201

202
Comprehensive data type support including JDBC standard types, MariaDB-specific extensions, geometry types, and LOB handling.
203

204
```java { .api }
205
public class MariaDbBlob implements Blob, Serializable {
206
  // BLOB implementation
207
}
208

209
public class MariaDbClob extends MariaDbBlob implements Clob, NClob {
210
  // CLOB/NCLOB implementation
211
}
212

213
// Geometry types (package: org.mariadb.jdbc.type)
214
public interface Geometry {
215
  // Base geometry interface for spatial data types
216
  static Point parsePoint(boolean littleEndian, ReadableByteBuf buf);
217
  static Geometry getGeometry(ReadableByteBuf buf, int length, Column column) throws SQLDataException;
218
}
219

220
public class Point implements Geometry {
221
  // Point geometry type for spatial coordinates
222
}
223

224
public class Polygon implements Geometry {
225
  // Polygon geometry type for spatial regions
226
}
227
```
228

229
[Data Types](./data-types.md)
230

231
### Authentication and Security
232

233
Pluggable authentication system supporting multiple authentication methods, credential providers, and SSL/TLS security configurations.
234

235
```java { .api }
236
public interface AuthenticationPlugin {
237
  String type();
238
  boolean mustUseSsl();
239
  // Authentication implementation methods
240
}
241

242
public interface CredentialPlugin extends Supplier<Credential> {
243
  String type();
244
  default boolean mustUseSsl();
245
  default String defaultAuthenticationPluginType();
246
  default CredentialPlugin initialize(Configuration conf, String userName, HostAddress hostAddress) throws SQLException;
247
}
248

249
public enum SslMode {
250
  DISABLE, TRUST, VERIFY_CA, VERIFY_FULL;
251
}
252
```
253

254
[Authentication and Security](./security.md)
255

256
### Connection Pooling
257

258
Built-in connection pooling with lifecycle management, JMX monitoring, and configurable pool behavior for enterprise applications.
259

260
```java { .api }
261
public class MariaDbPoolConnection implements PooledConnection, XAConnection {
262
  public Connection getConnection() throws SQLException;
263
  public void close() throws SQLException;
264
  public void addConnectionEventListener(ConnectionEventListener listener);
265
  public XAResource getXAResource() throws SQLException;
266
}
267

268
public interface PoolMBean {
269
  // JMX monitoring interface
270
  int getActiveConnections();
271
  int getIdleConnections();
272
  int getTotalConnections();
273
}
274
```
275

276
[Connection Pooling](./pooling.md)
277

278
## Types
279

280
```java { .api }
281
public enum TransactionIsolation {
282
  READ_UNCOMMITTED(Connection.TRANSACTION_READ_UNCOMMITTED),
283
  READ_COMMITTED(Connection.TRANSACTION_READ_COMMITTED),
284
  REPEATABLE_READ(Connection.TRANSACTION_REPEATABLE_READ),
285
  SERIALIZABLE(Connection.TRANSACTION_SERIALIZABLE);
286
}
287

288
public class MariaDbXid implements Xid {
289
  public MariaDbXid(int formatId, byte[] globalTransactionId, byte[] branchQualifier);
290
  public int getFormatId();
291
  public byte[] getGlobalTransactionId();
292
  public byte[] getBranchQualifier();
293
}
294

295
public class MaxAllowedPacketException extends SQLException {
296
  // Exception for packet size limits
297
}
298
```