or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

container-providers.md database-containers.md index.md jdbc-driver.md url-configuration.md

tile.json

tessl/maven-org-testcontainers--jdbc

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

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:maven/org.testcontainers/jdbc@1.21.x

To install, run

npx @tessl/cli install tessl/maven-org-testcontainers--jdbc@1.21.0

Testcontainers JDBC

Testcontainers JDBC provides a JDBC driver proxy that automatically provisions Docker containers running database engines for testing purposes. It handles JDBC URLs with the 'jdbc:tc:' prefix, automatically launching appropriate database containers and routing connections to them, enabling developers to write integration tests against real database instances in isolated, reproducible environments.

Package Information

Package Name: org.testcontainers:jdbc
Package Type: maven
Language: Java

Installation:

<dependency>
  <groupId>org.testcontainers</groupId>
  <artifactId>jdbc</artifactId>
  <version>1.21.3</version>
</dependency>

Core Imports

import org.testcontainers.jdbc.ContainerDatabaseDriver;
import org.testcontainers.containers.JdbcDatabaseContainer;
import org.testcontainers.containers.JdbcDatabaseContainerProvider;
import org.testcontainers.jdbc.ConnectionUrl;
import org.testcontainers.jdbc.JdbcDatabaseDelegate;
import org.testcontainers.jdbc.ConnectionWrapper;

Basic Usage

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;

public class DatabaseTest {
    public void testWithJdbcUrl() throws SQLException {
        // The JDBC URL automatically provisions a MySQL container
        String jdbcUrl = "jdbc:tc:mysql:8.0.33://localhost/testdb?TC_INITSCRIPT=init.sql";
        
        try (Connection connection = DriverManager.getConnection(jdbcUrl)) {
            // Use the connection - container is automatically managed
            // Container will be stopped when all connections are closed
        }
    }
}

Architecture

Testcontainers JDBC is built around several key components:

Driver Proxy: ContainerDatabaseDriver intercepts JDBC connections and manages container lifecycle
Container Abstraction: JdbcDatabaseContainer provides database-agnostic container operations
Provider System: Service loader pattern with JdbcDatabaseContainerProvider for database-specific implementations
URL Parsing: ConnectionUrl handles complex JDBC URL parsing and parameter extraction
Connection Management: Automatic container lifecycle tied to connection usage patterns
Initialization Support: Built-in script execution and programmatic initialization capabilities

Capabilities

JDBC Driver Proxy

Core JDBC driver implementation that intercepts tc: URLs and manages database containers automatically.

public class ContainerDatabaseDriver implements java.sql.Driver {
    public boolean acceptsURL(String url) throws SQLException;
    public Connection connect(String url, Properties info) throws SQLException;
    public DriverPropertyInfo[] getPropertyInfo(String url, Properties info) throws SQLException;
    public int getMajorVersion();
    public int getMinorVersion();
    public boolean jdbcCompliant();
    public Logger getParentLogger() throws SQLFeatureNotSupportedException;
    
    // Utility methods for container management
    public static void killContainers();
    public static void killContainer(String jdbcUrl);
    static JdbcDatabaseContainer getContainer(String jdbcUrl);
}

JDBC Driver

Database Container Management

Abstract base class for database containers that provide JDBC connectivity with lifecycle management and initialization support.

public abstract class JdbcDatabaseContainer<SELF extends JdbcDatabaseContainer<SELF>> 
    extends GenericContainer<SELF> implements LinkableContainer {
    
    // Abstract methods that must be implemented
    public abstract String getDriverClassName();
    public abstract String getJdbcUrl();
    public abstract String getUsername();
    public abstract String getPassword();
    protected abstract String getTestQueryString();
    
    // Configuration methods
    public SELF withUsername(String username);
    public SELF withPassword(String password);
    public SELF withDatabaseName(String dbName);
    public SELF withUrlParam(String paramName, String paramValue);
    public SELF withStartupTimeoutSeconds(int startupTimeoutSeconds);
    public SELF withConnectTimeoutSeconds(int connectTimeoutSeconds);
    public SELF withInitScript(String initScriptPath);
    public SELF withInitScripts(String... initScriptPaths);
    public SELF withInitScripts(Iterable<String> initScriptPaths);
    
    // Connection methods
    public Driver getJdbcDriverInstance() throws NoDriverFoundException;
    public Connection createConnection(String queryString) throws SQLException, NoDriverFoundException;
    public Connection createConnection(String queryString, Properties info) throws SQLException, NoDriverFoundException;
}

Database Containers

Container Provider System

Service provider interface for creating database-specific container implementations based on JDBC URL database types.

public abstract class JdbcDatabaseContainerProvider {
    public abstract boolean supports(String databaseType);
    public abstract JdbcDatabaseContainer newInstance(String tag);
    public JdbcDatabaseContainer newInstance();
    public JdbcDatabaseContainer newInstance(ConnectionUrl url);
    
    protected JdbcDatabaseContainer newInstanceFromConnectionUrl(
        ConnectionUrl connectionUrl,
        String userParamName,
        String pwdParamName
    );
}

Container Providers

URL Parsing and Configuration

Comprehensive URL parsing for JDBC connection strings with Testcontainers-specific parameters and database configuration.

public class ConnectionUrl {
    public static ConnectionUrl newInstance(String url);
    public static boolean accepts(String url);
    
    // Getters for parsed components
    public String getUrl();
    public String getDatabaseType();
    public Optional<String> getImageTag();
    public String getDbHostString();
    public boolean isInDaemonMode();
    public Optional<String> getDatabaseHost();
    public Optional<Integer> getDatabasePort();
    public Optional<String> getDatabaseName();
    public Optional<String> getInitScriptPath();
    public boolean isReusable();
    public Optional<InitFunctionDef> getInitFunction();
    public Optional<String> getQueryString();
    public Map<String, String> getContainerParameters();
    public Map<String, String> getQueryParameters();
    public Map<String, String> getTmpfsOptions();
}

URL Configuration

Common URL Parameters

Database Configuration

Standard JDBC parameters (user, password, etc.)
Database-specific options passed through to underlying driver

Container Parameters (TC_*)

TC_INITSCRIPT - Path to SQL initialization script (classpath or file:// resource)
TC_INITFUNCTION - Method reference for programmatic initialization (format: com.example.Class::method)
TC_DAEMON - Keep container running across multiple connection cycles
TC_REUSABLE - Mark container for potential reuse across test runs
TC_TMPFS - Configure tmpfs mounts for performance (format: path:options)

Connection Management Classes

Connection Wrapper

Internal connection wrapper that provides lifecycle callbacks for container cleanup.

public class ConnectionWrapper extends ConnectionDelegate {
    public ConnectionWrapper(Connection connection, Runnable closeCallback);
    
    @Override
    public void close() throws SQLException;
}

Connection Delegate

Simple JDBC Connection delegate that forwards all calls to the underlying connection.

class ConnectionDelegate implements Connection {
    // Implements all Connection interface methods via delegation
}

Database Delegates

JDBC-based database delegates for executing SQL scripts and statements.

public class JdbcDatabaseDelegate extends AbstractDatabaseDelegate<Statement> {
    public JdbcDatabaseDelegate(JdbcDatabaseContainer container, String queryString);
    
    @Override
    protected Statement createNewConnection();
    
    @Override
    public void execute(String statement, String scriptPath, int lineNumber, 
                       boolean continueOnError, boolean ignoreFailedDrops);
}

/**
 * @deprecated Used only with deprecated ScriptUtils
 */
@Deprecated
public class ContainerLessJdbcDelegate extends JdbcDatabaseDelegate {
    public ContainerLessJdbcDelegate(Connection connection);
    
    @Override
    protected Statement createNewConnection();
}

Legacy Utilities

Deprecated Script Utilities

Legacy SQL script utilities maintained for backward compatibility.

/**
 * @deprecated Use database-agnostic ScriptUtils instead
 */
@Deprecated
public abstract class org.testcontainers.jdbc.ext.ScriptUtils {
    public static final String DEFAULT_STATEMENT_SEPARATOR = ";";
    public static final String FALLBACK_STATEMENT_SEPARATOR = "\n";
    public static final String DEFAULT_COMMENT_PREFIX = "--";
    public static final String DEFAULT_BLOCK_COMMENT_START_DELIMITER = "/*";
    public static final String DEFAULT_BLOCK_COMMENT_END_DELIMITER = "*/";
    
    public static void splitSqlScript(String resource, String script, String separator, 
                                     String commentPrefix, String blockCommentStartDelimiter, 
                                     String blockCommentEndDelimiter, List<String> statements);
    public static boolean containsSqlScriptDelimiters(String script, String delim);
    public static void executeSqlScript(Connection connection, String scriptPath, String script) 
                                       throws ScriptException;
    public static void executeSqlScript(Connection connection, String scriptPath, String script, 
                                       boolean continueOnError, boolean ignoreFailedDrops, 
                                       String commentPrefix, String separator, 
                                       String blockCommentStartDelimiter, 
                                       String blockCommentEndDelimiter) throws ScriptException;
}

Exception Types

public static class NoDriverFoundException extends RuntimeException {
    public NoDriverFoundException(String message, Throwable cause);
}