0
# URL Configuration
1

2
The `ConnectionUrl` class provides comprehensive parsing and configuration management for Testcontainers JDBC URLs with support for database parameters, container options, and initialization settings.
3

4
## Capabilities
5

6
### URL Creation and Validation
7

8
Factory methods for creating and validating connection URLs.
9

10
```java { .api }
11
/**
12
 * Create new ConnectionUrl instance from JDBC URL string
13
 * Automatically parses the URL and extracts all components
14
 * @param url JDBC URL string in jdbc:tc: format
15
 * @return parsed ConnectionUrl instance
16
 * @throws IllegalArgumentException if URL format is invalid
17
 */
18
public static ConnectionUrl newInstance(String url);
19

20
/**
21
 * Test if URL is acceptable for Testcontainers JDBC
22
 * @param url JDBC URL string to test
23
 * @return true if URL starts with "jdbc:tc:", false otherwise
24
 */
25
public static boolean accepts(String url);
26
```
27

28
**Usage Example:**
29
```java
30
// Create and parse URL
31
String jdbcUrl = "jdbc:tc:mysql:8.0://localhost/testdb?user=test&TC_INITSCRIPT=schema.sql";
32
ConnectionUrl connectionUrl = ConnectionUrl.newInstance(jdbcUrl);
33

34
// Validate URL format
35
boolean isValid = ConnectionUrl.accepts("jdbc:tc:postgresql://localhost/app"); // true
36
boolean isInvalid = ConnectionUrl.accepts("jdbc:mysql://localhost/app"); // false
37
```
38

39
### URL Components Access
40

41
Getter methods for accessing parsed URL components.
42

43
```java { .api }
44
/**
45
 * Get the original URL string
46
 * @return complete original JDBC URL
47
 */
48
public String getUrl();
49

50
/**
51
 * Get database type extracted from URL
52
 * @return database type (e.g., "mysql", "postgresql")
53
 */
54
public String getDatabaseType();
55

56
/**
57
 * Get Docker image tag if specified
58
 * @return Optional containing image tag, or empty if not specified
59
 */
60
public Optional<String> getImageTag();
61

62
/**
63
 * Get database host string part of URL
64
 * May contain host:port/database format varying by database type
65
 * @return database host string for further parsing by clients
66
 */
67
public String getDbHostString();
68
```
69

70
**Usage Example:**
71
```java
72
ConnectionUrl url = ConnectionUrl.newInstance("jdbc:tc:postgresql:13.7://localhost:5432/myapp");
73

74
String dbType = url.getDatabaseType(); // "postgresql"
75
Optional<String> tag = url.getImageTag(); // Optional.of("13.7")
76
String hostString = url.getDbHostString(); // "localhost:5432/myapp"
77
```
78

79
### Database Connection Details
80

81
Methods for accessing parsed database connection information.
82

83
```java { .api }
84
/**
85
 * Get database host if parseable from URL
86
 * @return Optional containing host, or empty if not parseable
87
 */
88
public Optional<String> getDatabaseHost();
89

90
/**
91
 * Get database port if specified in URL
92
 * @return Optional containing port number, or empty if not specified
93
 */
94
public Optional<Integer> getDatabasePort();
95

96
/**
97
 * Get database name from URL
98
 * @return Optional containing database name, or empty if not parseable
99
 */
100
public Optional<String> getDatabaseName();
101
```
102

103
**Usage Example:**
104
```java
105
ConnectionUrl url = ConnectionUrl.newInstance("jdbc:tc:mysql://testhost:3306/appdb");
106

107
Optional<String> host = url.getDatabaseHost(); // Optional.of("testhost")
108
Optional<Integer> port = url.getDatabasePort(); // Optional.of(3306)
109
Optional<String> dbName = url.getDatabaseName(); // Optional.of("appdb")
110
```
111

112
### Container Configuration
113

114
Methods for accessing container-specific configuration options.
115

116
```java { .api }
117
/**
118
 * Check if container should run in daemon mode
119
 * Daemon mode keeps container running across multiple connection cycles
120
 * @return true if TC_DAEMON=true in URL, false otherwise
121
 */
122
public boolean isInDaemonMode();
123

124
/**
125
 * Check if container is marked as reusable
126
 * Reusable containers may be shared across test runs
127
 * @return true if TC_REUSABLE=true in URL, false otherwise
128
 */
129
@UnstableAPI
130
public boolean isReusable();
131

132
/**
133
 * Get initialization script path if specified
134
 * @return Optional containing classpath resource path, or empty if not specified
135
 */
136
public Optional<String> getInitScriptPath();
137

138
/**
139
 * Get initialization function definition if specified
140
 * @return Optional containing InitFunctionDef, or empty if not specified
141
 */
142
public Optional<InitFunctionDef> getInitFunction();
143

144
/**
145
 * Get tmpfs mount options for performance optimization
146
 * @return Map of tmpfs paths to mount options
147
 */
148
public Map<String, String> getTmpfsOptions();
149
```
150

151
**Usage Example:**
152
```java
153
String url = "jdbc:tc:mysql://localhost/test?TC_DAEMON=true&TC_INITSCRIPT=init.sql&TC_TMPFS=/var/lib/mysql:rw,noexec";
154
ConnectionUrl connectionUrl = ConnectionUrl.newInstance(url);
155

156
boolean daemon = connectionUrl.isInDaemonMode(); // true
157
Optional<String> script = connectionUrl.getInitScriptPath(); // Optional.of("init.sql")
158
Map<String, String> tmpfs = connectionUrl.getTmpfsOptions(); // {"/var/lib/mysql": "rw,noexec"}
159
```
160

161
### Parameter Access
162

163
Methods for accessing query parameters and container parameters.
164

165
```java { .api }
166
/**
167
 * Get query string portion of URL if present
168
 * @return Optional containing query string with leading '?', or empty if no parameters
169
 */
170
public Optional<String> getQueryString();
171

172
/**
173
 * Get all Testcontainers-specific parameters (TC_* parameters)
174
 * @return Map of container parameter names to values
175
 */
176
public Map<String, String> getContainerParameters();
177

178
/**
179
 * Get all standard query parameters (excludes TC_* parameters)
180
 * @return Map of query parameter names to values
181
 */
182
public Map<String, String> getQueryParameters();
183
```
184

185
**Usage Example:**
186
```java
187
String url = "jdbc:tc:postgresql://localhost/test?user=app&password=secret&TC_INITSCRIPT=schema.sql&ssl=true";
188
ConnectionUrl connectionUrl = ConnectionUrl.newInstance(url);
189

190
Optional<String> query = connectionUrl.getQueryString(); 
191
// Optional.of("?user=app&password=secret&ssl=true")
192

193
Map<String, String> containerParams = connectionUrl.getContainerParameters();
194
// {"TC_INITSCRIPT": "schema.sql"}
195

196
Map<String, String> queryParams = connectionUrl.getQueryParameters();
197
// {"user": "app", "password": "secret", "ssl": "true"}
198
```
199

200
## Nested Classes and Types
201

202
### InitFunctionDef
203

204
Class representing initialization function method references.
205

206
```java { .api }
207
/**
208
 * Definition of initialization function with class and method names
209
 */
210
public class InitFunctionDef {
211
    /**
212
     * Get the fully qualified class name
213
     * @return class name (e.g., "com.example.DbInit")
214
     */
215
    public String getClassName();
216
    
217
    /**
218
     * Get the method name
219
     * @return method name (e.g., "setupSchema")
220
     */
221
    public String getMethodName();
222
}
223
```
224

225
**Usage Example:**
226
```java
227
String url = "jdbc:tc:mysql://localhost/test?TC_INITFUNCTION=com.example.DbInit::setupSchema";
228
ConnectionUrl connectionUrl = ConnectionUrl.newInstance(url);
229

230
Optional<InitFunctionDef> initFunc = connectionUrl.getInitFunction();
231
if (initFunc.isPresent()) {
232
    String className = initFunc.get().getClassName(); // "com.example.DbInit"
233
    String methodName = initFunc.get().getMethodName(); // "setupSchema"
234
}
235
```
236

237
### URL Parsing Implementation
238

239
The ConnectionUrl class uses an internal parsing process to extract components from JDBC URLs.
240

241
```java { .api }
242
/**
243
 * Parse the URL components (called internally during construction)
244
 * This method applies various REGEX patterns to parse the URL
245
 * @throws IllegalArgumentException if URL format is invalid
246
 */
247
private void parseUrl();
248
```
249

250
### URL Pattern Constants
251

252
Interface containing regex patterns for URL parsing.
253

254
```java { .api }
255
/**
256
 * Interface defining regex patterns used for URL parsing
257
 */
258
public interface Patterns {
259
    /** Main URL pattern for standard database URLs */
260
    Pattern URL_MATCHING_PATTERN;
261
    
262
    /** Oracle-specific URL pattern supporting thin client format */
263
    Pattern ORACLE_URL_MATCHING_PATTERN;
264
    
265
    /** Pattern for parsing database instance details (host:port/database) */
266
    Pattern DB_INSTANCE_MATCHING_PATTERN;
267
    
268
    /** Pattern for detecting daemon mode parameter */
269
    Pattern DAEMON_MATCHING_PATTERN;
270
    
271
    /** Pattern for detecting initialization function parameter */
272
    Pattern INITFUNCTION_MATCHING_PATTERN;
273
    
274
    /** 
275
     * Pattern for detecting initialization script parameter
276
     * @deprecated Kept for compatibility, use container parameters parsing instead
277
     */
278
    @Deprecated
279
    Pattern INITSCRIPT_MATCHING_PATTERN;
280
    
281
    /** Pattern for Testcontainers parameter names (TC_*) */
282
    String TC_PARAM_NAME_PATTERN = "(TC_[A-Z_]+)";
283
    
284
    /** Pattern for matching Testcontainers parameters */
285
    Pattern TC_PARAM_MATCHING_PATTERN;
286
    
287
    /** Pattern for matching query parameters */
288
    Pattern QUERY_PARAM_MATCHING_PATTERN;
289
}
290
```
291

292
## Supported URL Formats
293

294
### Standard Format
295

296
```
297
jdbc:tc:<database_type>[:<image_tag>]://[<host>[:<port>]]/<database_name>[?<parameters>]
298
```
299

300
**Examples:**
301
```java
302
// Minimal MySQL URL
303
"jdbc:tc:mysql://localhost/testdb"
304

305
// PostgreSQL with version and parameters
306
"jdbc:tc:postgresql:13.7://localhost:5432/appdb?user=app&password=secret"
307

308
// With container parameters
309
"jdbc:tc:mysql:8.0://localhost/test?TC_INITSCRIPT=schema.sql&TC_DAEMON=true"
310
```
311

312
### Oracle Thin Client Format
313

314
Special format supporting Oracle's thin client URL structure:
315

316
```
317
jdbc:tc:oracle[:<image_tag>]:thin:[//][<username>/<password>]@<host>[:<port>]/<service_name>[?<parameters>]
318
```
319

320
**Examples:**
321
```java
322
// Oracle with credentials in URL
323
"jdbc:tc:oracle:19.3:thin://scott/tiger@localhost:1521/xe"
324

325
// Oracle with service name
326
"jdbc:tc:oracle:thin:@localhost:1521/ORCLPDB1"
327
```
328

329
## Container Parameters (TC_*)
330

331
### Initialization Parameters
332

333
Parameters for database initialization:
334

335
- **TC_INITSCRIPT**: Path to SQL initialization script
336
  ```java
337
  "jdbc:tc:mysql://localhost/test?TC_INITSCRIPT=schema.sql"
338
  "jdbc:tc:postgresql://localhost/app?TC_INITSCRIPT=file:///path/to/init.sql"
339
  ```
340

341
- **TC_INITFUNCTION**: Method reference for programmatic initialization
342
  ```java
343
  "jdbc:tc:mysql://localhost/test?TC_INITFUNCTION=com.example.DbInit::setupSchema"
344
  ```
345

346
### Lifecycle Parameters  
347

348
Parameters controlling container lifecycle:
349

350
- **TC_DAEMON**: Keep container running across connection cycles
351
  ```java
352
  "jdbc:tc:postgresql://localhost/test?TC_DAEMON=true"
353
  ```
354

355
- **TC_REUSABLE**: Mark container for potential reuse across test runs
356
  ```java
357
  "jdbc:tc:mysql://localhost/test?TC_REUSABLE=true"
358
  ```
359

360
### Performance Parameters
361

362
Parameters for performance optimization:
363

364
- **TC_TMPFS**: Configure tmpfs mounts for faster I/O
365
  ```java
366
  "jdbc:tc:mysql://localhost/test?TC_TMPFS=/var/lib/mysql:rw,noexec,size=1g"
367
  "jdbc:tc:postgresql://localhost/test?TC_TMPFS=/var/lib/postgresql/data:rw,size=512m"
368
  ```
369

370
## URL Parsing Process
371

372
The parsing process follows these steps:
373

374
1. **URL Validation**: Check if URL starts with "jdbc:tc:"
375
2. **Pattern Matching**: Apply regex patterns to extract components
376
3. **Database Type Extraction**: Extract database type for provider selection
377
4. **Image Tag Parsing**: Extract Docker image tag if specified
378
5. **Host String Extraction**: Extract host:port/database portion
379
6. **Parameter Separation**: Separate TC_* parameters from query parameters
380
7. **Special Handling**: Apply Oracle-specific parsing if needed
381
8. **Component Population**: Populate all optional fields based on successful parsing
382

383
## Error Handling
384

385
The URL parsing handles various error conditions:
386

387
### Invalid URL Format
388
```java
389
try {
390
    ConnectionUrl.newInstance("invalid-url");
391
} catch (IllegalArgumentException e) {
392
    // Handle malformed URL
393
}
394
```
395

396
### Unsupported Database Type
397
```java
398
// This will succeed in URL parsing but fail during container creation
399
ConnectionUrl url = ConnectionUrl.newInstance("jdbc:tc:unsupporteddb://localhost/test");
400
// Later: UnsupportedOperationException when no provider supports "unsupporteddb"
401
```
402

403
### Parameter Validation
404
Individual parameters are validated when used:
405
- Script paths are validated when containers attempt to load them
406
- Function references are validated via reflection when invoked
407
- Tmpfs options are validated by Docker when containers start