0
# Container Provider System
1

2
Factory classes for automatic container creation from JDBC URLs and connection options. Enables declarative container management through configuration rather than explicit instantiation, supporting both traditional JDBC patterns and modern testcontainers automation.
3

4
## Capabilities
5

6
### JDBC Container Provider
7

8
Factory for creating MariaDB containers from JDBC connection URLs, enabling automatic container management through specially formatted JDBC URLs.
9

10
```java { .api }
11
/**
12
 * Factory for MariaDB containers supporting JDBC URL-based creation
13
 * Extends JdbcDatabaseContainerProvider for integration with Testcontainers JDBC URL patterns
14
 */
15
public class MariaDBContainerProvider extends JdbcDatabaseContainerProvider {
16
    
17
    /**
18
     * Checks if this provider supports the specified database type
19
     * @param databaseType Database type string to check
20
     * @return true if databaseType equals "mariadb"
21
     */
22
    public boolean supports(String databaseType);
23
    
24
    /**
25
     * Creates new MariaDB container with default settings
26
     * @return MariaDBContainer with default image and tag
27
     */
28
    public JdbcDatabaseContainer newInstance();
29
    
30
    /**
31
     * Creates new MariaDB container with specified version tag
32
     * @param tag Docker image tag/version to use
33
     * @return MariaDBContainer with specified version
34
     */
35
    public JdbcDatabaseContainer newInstance(String tag);
36
    
37
    /**
38
     * Creates MariaDB container from JDBC connection URL
39
     * @param connectionUrl Parsed JDBC URL with parameters
40
     * @return Configured MariaDBContainer based on URL parameters
41
     */
42
    public JdbcDatabaseContainer newInstance(ConnectionUrl connectionUrl);
43
}
44
```
45

46
**Usage Examples:**
47

48
```java
49
import org.testcontainers.containers.MariaDBContainerProvider;
50
import org.testcontainers.jdbc.ConnectionUrl;
51

52
// Direct provider usage
53
MariaDBContainerProvider provider = new MariaDBContainerProvider();
54

55
// Check support
56
boolean supportsMariaDB = provider.supports("mariadb"); // true
57
boolean supportsMySQL = provider.supports("mysql");     // false
58

59
// Create containers
60
JdbcDatabaseContainer defaultContainer = provider.newInstance();
61
JdbcDatabaseContainer versionedContainer = provider.newInstance("10.3.39");
62

63
// From connection URL
64
ConnectionUrl url = ConnectionUrl.newInstance("jdbc:tc:mariadb://hostname/testdb");
65
JdbcDatabaseContainer urlContainer = provider.newInstance(url);
66
```
67

68
### JDBC URL Patterns
69

70
Special JDBC URL formats that automatically create and manage MariaDB containers.
71

72
```java { .api }
73
// Basic MariaDB container URL patterns:
74
// jdbc:tc:mariadb://hostname/databasename
75
// jdbc:tc:mariadb:version://hostname/databasename
76

77
// URL parameters supported:
78
// user=username                    - Database username
79
// password=password               - Database password  
80
// TC_INITSCRIPT=path/to/script   - Initialization SQL script
81
// TC_INITFUNCTION=Class::method  - Initialization function
82
// TC_MY_CNF=path/to/config       - Custom MariaDB configuration
83
```
84

85
**Usage Examples:**
86

87
```java
88
import java.sql.Connection;
89
import java.sql.DriverManager;
90

91
// Basic automatic container
92
String basicUrl = "jdbc:tc:mariadb://hostname/testdb";
93
Connection conn1 = DriverManager.getConnection(basicUrl);
94

95
// With specific version
96
String versionedUrl = "jdbc:tc:mariadb:10.3.39://hostname/myapp";
97
Connection conn2 = DriverManager.getConnection(versionedUrl);
98

99
// With authentication and initialization
100
String configuredUrl = "jdbc:tc:mariadb:10.3.39://hostname/webapp" +
101
    "?user=appuser&password=secret&TC_INITSCRIPT=schema.sql";
102
Connection conn3 = DriverManager.getConnection(configuredUrl);
103

104
// With custom configuration
105
String customConfigUrl = "jdbc:tc:mariadb://hostname/perftest" +
106
    "?TC_MY_CNF=mariadb-performance-config";
107
Connection conn4 = DriverManager.getConnection(customConfigUrl);
108

109
// All connections automatically create, start, and manage containers
110
```
111

112
### URL Parameter Processing
113

114
Handles URL parameters for container configuration and initialization.
115

116
```java { .api }
117
// Parameter constants used internally
118
private static final String USER_PARAM = "user";
119
private static final String PASSWORD_PARAM = "password";
120

121
// Creates container from parsed URL with parameter handling
122
public JdbcDatabaseContainer newInstance(ConnectionUrl connectionUrl) {
123
    return newInstanceFromConnectionUrl(connectionUrl, USER_PARAM, PASSWORD_PARAM);
124
}
125
```
126

127
**Supported URL Parameters:**
128

129
```java
130
// Authentication parameters
131
user=username                       // Sets container username
132
password=secret                     // Sets container password
133

134
// Initialization parameters  
135
TC_INITSCRIPT=path/to/init.sql     // Runs SQL script on startup
136
TC_INITFUNCTION=com.example.DB::init // Calls Java method for initialization
137

138
// Configuration parameters
139
TC_MY_CNF=config/mariadb           // Mounts custom configuration directory
140

141
// Standard JDBC parameters (passed through to connection)
142
connectTimeout=30000               // Connection timeout
143
useUnicode=true                    // Unicode support
144
characterEncoding=utf8             // Character encoding
145
rewriteBatchedStatements=true      // Batch statement optimization
146
```
147

148
### Integration with Testing Frameworks
149

150
Seamless integration with JUnit and other testing frameworks through JDBC URL automation.
151

152
**JUnit 4 Example:**
153

154
```java
155
public class MariaDBJdbcUrlTest {
156
    
157
    private static Connection connection;
158
    
159
    @BeforeClass
160
    public static void setUp() throws SQLException {
161
        // Container automatically created and started
162
        String jdbcUrl = "jdbc:tc:mariadb:10.3.39://hostname/junit4test" +
163
            "?user=testuser&TC_INITSCRIPT=test-schema.sql";
164
        connection = DriverManager.getConnection(jdbcUrl);
165
    }
166
    
167
    @Test
168
    public void testDatabaseAccess() throws SQLException {
169
        Statement stmt = connection.createStatement();
170
        ResultSet rs = stmt.executeQuery("SELECT COUNT(*) FROM users");
171
        assertTrue(rs.next());
172
        assertTrue(rs.getInt(1) >= 0);
173
    }
174
    
175
    @AfterClass
176
    public static void tearDown() throws SQLException {
177
        if (connection != null) {
178
            connection.close(); // Container automatically stopped
179
        }
180
    }
181
}
182
```
183

184
**JUnit 5 with @DataSource Integration:**
185

186
```java
187
@SpringBootTest
188
@Testcontainers
189
class MariaDBIntegrationTest {
190
    
191
    @TestConfiguration
192
    static class TestConfig {
193
        
194
        @Bean
195
        @Primary
196
        public DataSource dataSource() {
197
            HikariConfig config = new HikariConfig();
198
            config.setJdbcUrl("jdbc:tc:mariadb:10.3.39://hostname/springtest" +
199
                "?TC_INITSCRIPT=spring-schema.sql");
200
            config.setUsername("spring");
201
            config.setPassword("test");
202
            return new HikariDataSource(config);
203
        }
204
    }
205
    
206
    @Autowired
207
    private UserRepository userRepository;
208
    
209
    @Test
210
    void testUserRepository() {
211
        // Database automatically available with initialized schema
212
        User user = new User("Alice", "alice@example.com");
213
        User saved = userRepository.save(user);
214
        assertNotNull(saved.getId());
215
    }
216
}
217
```
218

219
### Connection Pooling Integration
220

221
Works with popular connection pool libraries for production-like testing environments.
222

223
**HikariCP Example:**
224

225
```java
226
import com.zaxxer.hikari.HikariConfig;
227
import com.zaxxer.hikari.HikariDataSource;
228

229
HikariConfig config = new HikariConfig();
230
config.setJdbcUrl("jdbc:tc:mariadb:10.3.39://hostname/pooltest?user=pooluser");
231
config.setMaximumPoolSize(10);
232
config.setMinimumIdle(2);
233
config.setConnectionTimeout(30000);
234

235
HikariDataSource dataSource = new HikariDataSource(config);
236

237
// Use DataSource for testing with connection pooling
238
try (Connection conn = dataSource.getConnection()) {
239
    // Perform database operations
240
}
241
```
242

243
**Apache DBCP Example:**
244

245
```java
246
import org.apache.commons.dbcp2.BasicDataSource;
247

248
BasicDataSource dataSource = new BasicDataSource();
249
dataSource.setUrl("jdbc:tc:mariadb://hostname/dbcptest?TC_INITSCRIPT=test-data.sql");
250
dataSource.setUsername("dbcp");
251
dataSource.setPassword("test");
252
dataSource.setInitialSize(5);
253
dataSource.setMaxTotal(20);
254

255
// Container managed automatically by Testcontainers
256
```
257

258
## Advanced URL Patterns
259

260
### Initialization Scripts
261

262
Automatically run SQL scripts when the container starts:
263

264
```java
265
// Single initialization script
266
"jdbc:tc:mariadb://hostname/mydb?TC_INITSCRIPT=schema.sql"
267

268
// Multiple scripts (comma-separated)
269
"jdbc:tc:mariadb://hostname/mydb?TC_INITSCRIPT=schema.sql,data.sql,indexes.sql"
270

271
// Scripts from classpath resources
272
"jdbc:tc:mariadb://hostname/mydb?TC_INITSCRIPT=classpath:db/migration/V1__create_tables.sql"
273
```
274

275
### Initialization Functions
276

277
Call Java methods for programmatic database initialization:
278

279
```java
280
// Static method reference
281
"jdbc:tc:mariadb://hostname/mydb?TC_INITFUNCTION=com.example.DatabaseSetup::initialize"
282

283
// Method signature expected:
284
public class DatabaseSetup {
285
    public static void initialize(Connection connection) throws SQLException {
286
        // Custom database setup logic
287
        Statement stmt = connection.createStatement();
288
        stmt.execute("CREATE TABLE IF NOT EXISTS test_data (id INT PRIMARY KEY, name VARCHAR(100))");
289
        stmt.execute("INSERT INTO test_data VALUES (1, 'Sample Data')");
290
    }
291
}
292
```
293

294
### Custom Configuration
295

296
Mount custom MariaDB configuration files:
297

298
```java
299
// Custom configuration directory
300
"jdbc:tc:mariadb://hostname/mydb?TC_MY_CNF=mariadb-config"
301

302
// Directory structure:
303
// src/test/resources/mariadb-config/
304
//   ├── custom.cnf
305
//   ├── performance.cnf
306
//   └── logging.cnf
307

308
// Files automatically mounted to /etc/mysql/conf.d/ in container
309
```
310

311
## Error Handling
312

313
Common error scenarios and solutions:
314

315
```java
316
// Missing MariaDB JDBC driver
317
try {
318
    Connection conn = DriverManager.getConnection("jdbc:tc:mariadb://hostname/test");
319
} catch (SQLException e) {
320
    // Add mariadb-java-client dependency
321
    // implementation 'org.mariadb.jdbc:mariadb-java-client:3.4.1'
322
}
323

324
// Invalid initialization script path
325
try {
326
    String url = "jdbc:tc:mariadb://hostname/test?TC_INITSCRIPT=nonexistent.sql";
327
    Connection conn = DriverManager.getConnection(url);
328
} catch (ContainerLaunchException e) {
329
    // Ensure script exists in classpath or provide correct path
330
}
331

332
// Container startup timeout
333
try {
334
    String url = "jdbc:tc:mariadb://hostname/test";
335
    Connection conn = DriverManager.getConnection(url);
336
} catch (ContainerLaunchException e) {
337
    // Check Docker daemon, increase timeout, or verify image availability
338
}
339
```
340

341
## Types
342

343
```java { .api }
344
import org.testcontainers.jdbc.JdbcDatabaseContainerProvider;
345
import org.testcontainers.jdbc.ConnectionUrl;
346
import org.testcontainers.containers.JdbcDatabaseContainer;
347

348
// Provider interface methods
349
boolean supports(String databaseType);
350
JdbcDatabaseContainer newInstance();
351
JdbcDatabaseContainer newInstance(String tag);
352
JdbcDatabaseContainer newInstance(ConnectionUrl connectionUrl);
353

354
// URL parameter constants
355
String USER_PARAM = "user";
356
String PASSWORD_PARAM = "password";
357

358
// Testcontainers URL parameters
359
String TC_INITSCRIPT = "TC_INITSCRIPT";     // Initialization script path
360
String TC_INITFUNCTION = "TC_INITFUNCTION"; // Initialization function reference
361
String TC_MY_CNF = "TC_MY_CNF";             // Custom MariaDB configuration path
362
```