CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-org-testcontainers--jdbc

Testcontainers JDBC driver that provides lightweight, throwaway database instances for testing

Overview
Eval results
Files

url-configuration.mddocs/

URL Configuration

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

Capabilities

URL Creation and Validation

Factory methods for creating and validating connection URLs.

/**
 * Create new ConnectionUrl instance from JDBC URL string
 * Automatically parses the URL and extracts all components
 * @param url JDBC URL string in jdbc:tc: format
 * @return parsed ConnectionUrl instance
 * @throws IllegalArgumentException if URL format is invalid
 */
public static ConnectionUrl newInstance(String url);

/**
 * Test if URL is acceptable for Testcontainers JDBC
 * @param url JDBC URL string to test
 * @return true if URL starts with "jdbc:tc:", false otherwise
 */
public static boolean accepts(String url);

Usage Example:

// Create and parse URL
String jdbcUrl = "jdbc:tc:mysql:8.0://localhost/testdb?user=test&TC_INITSCRIPT=schema.sql";
ConnectionUrl connectionUrl = ConnectionUrl.newInstance(jdbcUrl);

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

URL Components Access

Getter methods for accessing parsed URL components.

/**
 * Get the original URL string
 * @return complete original JDBC URL
 */
public String getUrl();

/**
 * Get database type extracted from URL
 * @return database type (e.g., "mysql", "postgresql")
 */
public String getDatabaseType();

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

/**
 * Get database host string part of URL
 * May contain host:port/database format varying by database type
 * @return database host string for further parsing by clients
 */
public String getDbHostString();

Usage Example:

ConnectionUrl url = ConnectionUrl.newInstance("jdbc:tc:postgresql:13.7://localhost:5432/myapp");

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

Database Connection Details

Methods for accessing parsed database connection information.

/**
 * Get database host if parseable from URL
 * @return Optional containing host, or empty if not parseable
 */
public Optional<String> getDatabaseHost();

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

/**
 * Get database name from URL
 * @return Optional containing database name, or empty if not parseable
 */
public Optional<String> getDatabaseName();

Usage Example:

ConnectionUrl url = ConnectionUrl.newInstance("jdbc:tc:mysql://testhost:3306/appdb");

Optional<String> host = url.getDatabaseHost(); // Optional.of("testhost")
Optional<Integer> port = url.getDatabasePort(); // Optional.of(3306)
Optional<String> dbName = url.getDatabaseName(); // Optional.of("appdb")

Container Configuration

Methods for accessing container-specific configuration options.

/**
 * Check if container should run in daemon mode
 * Daemon mode keeps container running across multiple connection cycles
 * @return true if TC_DAEMON=true in URL, false otherwise
 */
public boolean isInDaemonMode();

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

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

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

/**
 * Get tmpfs mount options for performance optimization
 * @return Map of tmpfs paths to mount options
 */
public Map<String, String> getTmpfsOptions();

Usage Example:

String url = "jdbc:tc:mysql://localhost/test?TC_DAEMON=true&TC_INITSCRIPT=init.sql&TC_TMPFS=/var/lib/mysql:rw,noexec";
ConnectionUrl connectionUrl = ConnectionUrl.newInstance(url);

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

Parameter Access

Methods for accessing query parameters and container parameters.

/**
 * Get query string portion of URL if present
 * @return Optional containing query string with leading '?', or empty if no parameters
 */
public Optional<String> getQueryString();

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

/**
 * Get all standard query parameters (excludes TC_* parameters)
 * @return Map of query parameter names to values
 */
public Map<String, String> getQueryParameters();

Usage Example:

String url = "jdbc:tc:postgresql://localhost/test?user=app&password=secret&TC_INITSCRIPT=schema.sql&ssl=true";
ConnectionUrl connectionUrl = ConnectionUrl.newInstance(url);

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

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

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

Nested Classes and Types

InitFunctionDef

Class representing initialization function method references.

/**
 * Definition of initialization function with class and method names
 */
public class InitFunctionDef {
    /**
     * Get the fully qualified class name
     * @return class name (e.g., "com.example.DbInit")
     */
    public String getClassName();
    
    /**
     * Get the method name
     * @return method name (e.g., "setupSchema")
     */
    public String getMethodName();
}

Usage Example:

String url = "jdbc:tc:mysql://localhost/test?TC_INITFUNCTION=com.example.DbInit::setupSchema";
ConnectionUrl connectionUrl = ConnectionUrl.newInstance(url);

Optional<InitFunctionDef> initFunc = connectionUrl.getInitFunction();
if (initFunc.isPresent()) {
    String className = initFunc.get().getClassName(); // "com.example.DbInit"
    String methodName = initFunc.get().getMethodName(); // "setupSchema"
}

URL Parsing Implementation

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

/**
 * Parse the URL components (called internally during construction)
 * This method applies various REGEX patterns to parse the URL
 * @throws IllegalArgumentException if URL format is invalid
 */
private void parseUrl();

URL Pattern Constants

Interface containing regex patterns for URL parsing.

/**
 * Interface defining regex patterns used for URL parsing
 */
public interface Patterns {
    /** Main URL pattern for standard database URLs */
    Pattern URL_MATCHING_PATTERN;
    
    /** Oracle-specific URL pattern supporting thin client format */
    Pattern ORACLE_URL_MATCHING_PATTERN;
    
    /** Pattern for parsing database instance details (host:port/database) */
    Pattern DB_INSTANCE_MATCHING_PATTERN;
    
    /** Pattern for detecting daemon mode parameter */
    Pattern DAEMON_MATCHING_PATTERN;
    
    /** Pattern for detecting initialization function parameter */
    Pattern INITFUNCTION_MATCHING_PATTERN;
    
    /** 
     * Pattern for detecting initialization script parameter
     * @deprecated Kept for compatibility, use container parameters parsing instead
     */
    @Deprecated
    Pattern INITSCRIPT_MATCHING_PATTERN;
    
    /** Pattern for Testcontainers parameter names (TC_*) */
    String TC_PARAM_NAME_PATTERN = "(TC_[A-Z_]+)";
    
    /** Pattern for matching Testcontainers parameters */
    Pattern TC_PARAM_MATCHING_PATTERN;
    
    /** Pattern for matching query parameters */
    Pattern QUERY_PARAM_MATCHING_PATTERN;
}

Supported URL Formats

Standard Format

jdbc:tc:<database_type>[:<image_tag>]://[<host>[:<port>]]/<database_name>[?<parameters>]

Examples:

// Minimal MySQL URL
"jdbc:tc:mysql://localhost/testdb"

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

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

Oracle Thin Client Format

Special format supporting Oracle's thin client URL structure:

jdbc:tc:oracle[:<image_tag>]:thin:[//][<username>/<password>]@<host>[:<port>]/<service_name>[?<parameters>]

Examples:

// Oracle with credentials in URL
"jdbc:tc:oracle:19.3:thin://scott/tiger@localhost:1521/xe"

// Oracle with service name
"jdbc:tc:oracle:thin:@localhost:1521/ORCLPDB1"

Container Parameters (TC_*)

Initialization Parameters

Parameters for database initialization:

  • TC_INITSCRIPT: Path to SQL initialization script

    "jdbc:tc:mysql://localhost/test?TC_INITSCRIPT=schema.sql"
"jdbc:tc:postgresql://localhost/app?TC_INITSCRIPT=file:///path/to/init.sql"

  • TC_INITFUNCTION: Method reference for programmatic initialization

    "jdbc:tc:mysql://localhost/test?TC_INITFUNCTION=com.example.DbInit::setupSchema"

Lifecycle Parameters

Parameters controlling container lifecycle:

  • TC_DAEMON: Keep container running across connection cycles

    "jdbc:tc:postgresql://localhost/test?TC_DAEMON=true"

  • TC_REUSABLE: Mark container for potential reuse across test runs

    "jdbc:tc:mysql://localhost/test?TC_REUSABLE=true"

Performance Parameters

Parameters for performance optimization:

  • TC_TMPFS: Configure tmpfs mounts for faster I/O 
    "jdbc:tc:mysql://localhost/test?TC_TMPFS=/var/lib/mysql:rw,noexec,size=1g"
"jdbc:tc:postgresql://localhost/test?TC_TMPFS=/var/lib/postgresql/data:rw,size=512m"

URL Parsing Process

The parsing process follows these steps:

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

Error Handling

The URL parsing handles various error conditions:

Invalid URL Format

try {
    ConnectionUrl.newInstance("invalid-url");
} catch (IllegalArgumentException e) {
    // Handle malformed URL
}

Unsupported Database Type

// This will succeed in URL parsing but fail during container creation
ConnectionUrl url = ConnectionUrl.newInstance("jdbc:tc:unsupporteddb://localhost/test");
// Later: UnsupportedOperationException when no provider supports "unsupporteddb"

Parameter Validation

Individual parameters are validated when used:

  • Script paths are validated when containers attempt to load them
  • Function references are validated via reflection when invoked
  • Tmpfs options are validated by Docker when containers start

Install with Tessl CLI

npx tessl i tessl/maven-org-testcontainers--jdbc

docs

container-providers.md

database-containers.md

index.md

jdbc-driver.md

url-configuration.md

tile.json