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

jdbc-driver.mddocs/

JDBC Driver

The ContainerDatabaseDriver is the core component that implements the JDBC Driver interface to intercept database connections and manage Docker containers automatically.

Capabilities

Driver Registration

The driver automatically registers itself with the JDBC DriverManager when the class is loaded.

/**
 * JDBC Driver implementation that handles jdbc:tc: URLs
 */
public class ContainerDatabaseDriver implements java.sql.Driver {
    // Driver automatically registers itself via static block
}

URL Acceptance

Determines whether the driver can handle a given JDBC URL.

/**
 * Tests whether this driver can connect to the given URL
 * @param url JDBC URL to test
 * @return true if URL starts with "jdbc:tc:", false otherwise
 * @throws SQLException if database access error occurs
 */
public boolean acceptsURL(String url) throws SQLException;

Usage Example:

ContainerDatabaseDriver driver = new ContainerDatabaseDriver();
boolean canHandle = driver.acceptsURL("jdbc:tc:mysql:8.0://localhost/test"); // true
boolean cannotHandle = driver.acceptsURL("jdbc:mysql://localhost/test"); // false

Connection Establishment

Creates database connections by provisioning containers and delegating to the appropriate database driver.

/**
 * Attempts to make a database connection to the given URL
 * @param url JDBC URL in format jdbc:tc:type:tag://host:port/database?params
 * @param info connection properties (user, password, etc.)
 * @return Connection to the containerized database, or null if URL not supported
 * @throws SQLException if database access error occurs
 */
public synchronized Connection connect(String url, Properties info) throws SQLException;

Connection Process:

  1. Parse the JDBC URL to extract database type and parameters
  2. Check cache for existing container with matching URL
  3. If not found, use ServiceLoader to find appropriate JdbcDatabaseContainerProvider
  4. Create and start new database container
  5. Execute initialization scripts/functions if specified
  6. Return wrapped connection with cleanup callbacks

Usage Example:

Properties props = new Properties();
props.setProperty("user", "test");
props.setProperty("password", "test");

String url = "jdbc:tc:postgresql:13.7://localhost/testdb?TC_INITSCRIPT=schema.sql";
Connection conn = DriverManager.getConnection(url, props);

Driver Properties

Provides information about supported connection properties.

/**
 * Gets information about possible properties for connections
 * @param url JDBC URL
 * @param info proposed connection properties
 * @return array of DriverPropertyInfo objects
 * @throws SQLException if database access error occurs
 */
public DriverPropertyInfo[] getPropertyInfo(String url, Properties info) throws SQLException;

Version Information

Provides driver version information.

/**
 * Gets the driver's major version number
 * @return major version number (delegates to underlying driver or returns 1)
 */
public int getMajorVersion();

/**
 * Gets the driver's minor version number  
 * @return minor version number (delegates to underlying driver or returns 0)
 */
public int getMinorVersion();

JDBC Compliance

Indicates whether the driver is JDBC compliant.

/**
 * Reports whether this driver is a genuine JDBC Compliant driver
 * @return true if underlying driver is JDBC compliant, false otherwise
 */
public boolean jdbcCompliant();

Logging Support

Provides access to the driver's logger.

/**
 * Return the parent Logger of all the Loggers used by this driver
 * @return parent Logger for this driver
 * @throws SQLFeatureNotSupportedException if not supported by underlying driver
 */
public Logger getParentLogger() throws SQLFeatureNotSupportedException;

Container Management Utilities

Static utility methods for managing database containers directly.

/**
 * Utility method to kill ALL database containers
 * Provided for cleanup in testing scenarios with resource constraints
 */
public static void killContainers();

/**
 * Utility method to kill a specific database container
 * @param jdbcUrl the JDBC URL of the container to kill
 */
public static void killContainer(String jdbcUrl);

/**
 * Utility method to get container instance by JDBC URL
 * @param jdbcUrl the JDBC URL of the container to retrieve
 * @return container instance or null if not found
 */
static JdbcDatabaseContainer getContainer(String jdbcUrl);

Usage Example:

// Clean up all containers after test suite
@AfterAll
public static void cleanup() {
    ContainerDatabaseDriver.killContainers();
}

// Clean up specific container
ContainerDatabaseDriver.killContainer("jdbc:tc:mysql:8.0://localhost/test");

// Get container for inspection
JdbcDatabaseContainer container = ContainerDatabaseDriver.getContainer(
    "jdbc:tc:postgresql:13://localhost/app"
);
if (container != null) {
    System.out.println("Container is running: " + container.isRunning());
}

Supported URL Format

The driver accepts URLs in the following format:

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

Components:

  • database_type - Database type (mysql, postgresql, oracle, etc.)
  • image_tag - Optional Docker image tag (uses provider default if omitted)
  • host:port - Optional host and port (ignored, container provides these)
  • database_name - Database name to connect to
  • parameters - Query parameters for both JDBC driver and Testcontainers

Examples:

// MySQL with default tag
"jdbc:tc:mysql://localhost/testdb"

// PostgreSQL with specific version
"jdbc:tc:postgresql:13.7://localhost/myapp?user=app&password=secret"

// With initialization script
"jdbc:tc:mysql:8.0://localhost/test?TC_INITSCRIPT=schema.sql"

// With initialization function
"jdbc:tc:postgresql://localhost/test?TC_INITFUNCTION=com.example.DbInit::setupSchema"

Container Lifecycle

The driver manages container lifecycle based on connection usage:

  1. Container Creation: First connection with a new URL creates and starts container
  2. Connection Sharing: Subsequent connections to same URL reuse existing container
  3. Automatic Cleanup: Container stops when all connections are closed (unless in daemon mode)
  4. Daemon Mode: Containers marked with TC_DAEMON=true persist across connection cycles
  5. Reusable Containers: Containers marked with TC_REUSABLE=true may be reused across test runs

Thread Safety

The driver implementation is thread-safe with synchronized access to container caches and connection management.

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