0
# MariaDB Testcontainers
1

2
A Java library providing throwaway MariaDB database containers for integration testing. Part of the Testcontainers ecosystem, it enables developers to run real MariaDB instances in Docker containers during tests, ensuring reliable database testing without external dependencies.
3

4
## Package Information
5

6
- **Package Name**: org.testcontainers:mariadb
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: `implementation 'org.testcontainers:mariadb:1.21.3'` (Gradle) or `<dependency><groupId>org.testcontainers</groupId><artifactId>mariadb</artifactId><version>1.21.3</version></dependency>` (Maven)
10

11
## Installation
12

13
Add the MariaDB Testcontainers dependency to your project:
14

15
**Gradle:**
16
```groovy
17
testImplementation 'org.testcontainers:mariadb:1.21.3'
18
// Required: MariaDB JDBC driver
19
testImplementation 'org.mariadb.jdbc:mariadb-java-client:3.4.1'
20
```
21

22
**Maven:**
23
```xml
24
<dependency>
25
    <groupId>org.testcontainers</groupId>
26
    <artifactId>mariadb</artifactId>
27
    <version>1.21.3</version>
28
    <scope>test</scope>
29
</dependency>
30
<!-- Required: MariaDB JDBC driver -->
31
<dependency>
32
    <groupId>org.mariadb.jdbc</groupId>
33
    <artifactId>mariadb-java-client</artifactId>
34
    <version>3.4.1</version>
35
    <scope>test</scope>
36
</dependency>
37
```
38

39
**Important**: The MariaDB JDBC driver is **required** but not automatically included. Without it, you'll get `SQLException: No suitable driver found`.
40

41
For R2DBC support, also add:
42

43
**Gradle:**
44
```groovy
45
testImplementation 'org.testcontainers:r2dbc:1.21.3'
46
testRuntimeOnly 'org.mariadb:r2dbc-mariadb:1.0.3'
47
```
48

49
**Maven:**
50
```xml
51
<dependency>
52
    <groupId>org.testcontainers</groupId>
53
    <artifactId>r2dbc</artifactId>
54
    <version>1.21.3</version>
55
    <scope>test</scope>
56
</dependency>
57
<dependency>
58
    <groupId>org.mariadb</groupId>
59
    <artifactId>r2dbc-mariadb</artifactId>
60
    <version>1.0.3</version>
61
    <scope>test</scope>
62
</dependency>
63
```
64

65
## Core Imports
66

67
```java
68
import org.testcontainers.containers.MariaDBContainer;
69
```
70

71
For R2DBC support:
72

73
```java
74
import org.testcontainers.containers.MariaDBR2DBCDatabaseContainer;
75
import io.r2dbc.spi.ConnectionFactoryOptions;
76
```
77

78
## Basic Usage
79

80
```java
81
import org.testcontainers.containers.MariaDBContainer;
82
import org.testcontainers.utility.DockerImageName;
83
import java.sql.Connection;
84
import java.sql.DriverManager;
85
import java.sql.PreparedStatement;
86
import java.sql.ResultSet;
87
import java.sql.Statement;
88

89
// Create and configure a MariaDB container
90
try (MariaDBContainer<?> mariadb = new MariaDBContainer<>(
91
        DockerImageName.parse("mariadb:10.3.39"))
92
        .withDatabaseName("testdb")
93
        .withUsername("testuser")
94
        .withPassword("testpass")
95
        .withInitScript("schema.sql")) {
96
    
97
    mariadb.start();
98
    
99
    // Get connection details
100
    String jdbcUrl = mariadb.getJdbcUrl();
101
    String username = mariadb.getUsername();
102
    String password = mariadb.getPassword();
103
    
104
    System.out.println("MariaDB container started:");
105
    System.out.println("JDBC URL: " + jdbcUrl);
106
    System.out.println("Username: " + username);
107
    System.out.println("Host: " + mariadb.getHost());
108
    System.out.println("Port: " + mariadb.getMappedPort(3306));
109
    
110
    // Connect and perform database operations
111
    try (Connection conn = DriverManager.getConnection(jdbcUrl, username, password)) {
112
        // Create a table
113
        try (Statement stmt = conn.createStatement()) {
114
            stmt.execute("CREATE TABLE users (id INT PRIMARY KEY AUTO_INCREMENT, name VARCHAR(50), email VARCHAR(100))");
115
        }
116
        
117
        // Insert data
118
        try (PreparedStatement pstmt = conn.prepareStatement(
119
                "INSERT INTO users (name, email) VALUES (?, ?)")) {
120
            pstmt.setString(1, "Alice Smith");
121
            pstmt.setString(2, "alice@example.com");
122
            pstmt.executeUpdate();
123
            
124
            pstmt.setString(1, "Bob Johnson");
125
            pstmt.setString(2, "bob@example.com");
126
            pstmt.executeUpdate();
127
        }
128
        
129
        // Query data
130
        try (Statement stmt = conn.createStatement();
131
             ResultSet rs = stmt.executeQuery("SELECT COUNT(*) as user_count FROM users")) {
132
            
133
            if (rs.next()) {
134
                System.out.println("Total users: " + rs.getInt("user_count"));
135
            }
136
        }
137
        
138
        // Verify container is working
139
        try (Statement stmt = conn.createStatement();
140
             ResultSet rs = stmt.executeQuery("SELECT VERSION()")) {
141
            
142
            if (rs.next()) {
143
                System.out.println("MariaDB version: " + rs.getString(1));
144
            }
145
        }
146
    }
147
}
148
// Container automatically stopped when exiting try-with-resources
149
```
150

151
## Architecture
152

153
MariaDB Testcontainers is built around several key components:
154

155
- **MariaDBContainer**: Main container class extending JdbcDatabaseContainer for JDBC-based database testing
156
- **Provider Classes**: Factory classes for automatic container creation from JDBC URLs and R2DBC connection options
157
- **R2DBC Integration**: Reactive database access support through MariaDBR2DBCDatabaseContainer
158
- **Configuration System**: Environment variables and volume mounting for MariaDB-specific configuration
159
- **JUnit Integration**: Seamless integration with JUnit test lifecycle for automatic container management
160

161
## Capabilities
162

163
### JDBC Container Management
164

165
Core container functionality for creating and managing MariaDB instances with JDBC connectivity. Provides database connection details, lifecycle management, and MariaDB-specific configuration options.
166

167
```java { .api }
168
public class MariaDBContainer<SELF extends MariaDBContainer<SELF>> extends JdbcDatabaseContainer<SELF> {
169
    public MariaDBContainer(String dockerImageName);
170
    public MariaDBContainer(DockerImageName dockerImageName);
171
    
172
    // Database connection methods
173
    public String getJdbcUrl();
174
    public String getDriverClassName();
175
    public String getDatabaseName();
176
    public String getUsername();
177
    public String getPassword();
178
    public String getTestQueryString();
179
    public Connection createConnection(String queryString) throws SQLException, NoDriverFoundException;
180
    
181
    // Configuration methods
182
    public SELF withDatabaseName(String databaseName);
183
    public SELF withUsername(String username);
184
    public SELF withPassword(String password);
185
    public SELF withConfigurationOverride(String configPath);
186
    public SELF withUrlParam(String paramName, String paramValue);
187
    
188
    // Initialization methods (inherited from JdbcDatabaseContainer)
189
    public SELF withInitScript(String initScriptPath);
190
    public SELF withInitScripts(String... initScriptPaths);
191
    
192
    // Container lifecycle methods (inherited from GenericContainer)
193
    public void start();
194
    public void stop();
195
    public boolean isRunning();
196
    public String getHost();
197
    public Integer getMappedPort(int originalPort);
198
    
199
    // Timeout configuration (inherited from JdbcDatabaseContainer)
200
    public SELF withStartupTimeoutSeconds(int startupTimeoutSeconds);
201
    public SELF withConnectTimeoutSeconds(int connectTimeoutSeconds);
202
}
203
```
204

205
[JDBC Containers](./jdbc-containers.md)
206

207
### R2DBC Container Management
208

209
Reactive database access support for MariaDB containers using R2DBC drivers. Enables non-blocking database operations with full container lifecycle integration.
210

211
```java { .api }
212
public class MariaDBR2DBCDatabaseContainer implements R2DBCDatabaseContainer {
213
    public static ConnectionFactoryOptions getOptions(MariaDBContainer<?> container);
214
    public ConnectionFactoryOptions configure(ConnectionFactoryOptions options);
215
}
216

217
public class MariaDBR2DBCDatabaseContainerProvider implements R2DBCDatabaseContainerProvider {
218
    public boolean supports(ConnectionFactoryOptions options);
219
    public R2DBCDatabaseContainer createContainer(ConnectionFactoryOptions options);
220
    public ConnectionFactoryMetadata getMetadata(ConnectionFactoryOptions options);
221
}
222
```
223

224
[R2DBC Containers](./r2dbc-containers.md)
225

226
### Container Provider System
227

228
Factory classes for automatic container creation from JDBC URLs and connection options. Enables declarative container management through configuration rather than explicit instantiation.
229

230
```java { .api }
231
public class MariaDBContainerProvider extends JdbcDatabaseContainerProvider {
232
    public boolean supports(String databaseType);
233
    public JdbcDatabaseContainer newInstance();
234
    public JdbcDatabaseContainer newInstance(String tag);
235
    public JdbcDatabaseContainer newInstance(ConnectionUrl connectionUrl);
236
}
237
```
238

239
[Container Providers](./container-providers.md)
240

241
## Types
242

243
```java { .api }
244
// Container configuration constants (public)
245
public static final String NAME = "mariadb";
246
public static final Integer MARIADB_PORT = 3306;
247
// Note: DEFAULT_USER and DEFAULT_PASSWORD are package-private constants, not part of public API
248

249
// Docker image configuration
250
import org.testcontainers.utility.DockerImageName;
251

252
// JDBC URL patterns for automatic containers
253
// jdbc:tc:mariadb://hostname/databasename
254
// jdbc:tc:mariadb:version://hostname/databasename
255

256
// R2DBC URL patterns for reactive containers  
257
// r2dbc:tc:mariadb:///databasename?TC_IMAGE_TAG=version
258
```