IDatabaseConnection

The IDatabaseConnection interface represents a dbUnit connection to a database: it wraps a JDBC connection, and is the factory for creating datasets/tables from the live database (createDataSet(), createQueryTable(), createTable()), reading row counts, and accessing the connection’s DatabaseConfig.

These are typically not constructed directly in test code — an IDatabaseTester implementation constructs and returns one from getConnection(). Reach for them directly only when writing a custom IDatabaseTester/DBTestCase subclass, or when using dbUnit outside a test (e.g. a one-off import/export script).

DatabaseDataSet

DatabaseDataSet is the IDataSet adapter that provides access to a database instance as a dataset. It is not usually instantiated directly, but obtained from the factory method IDatabaseConnection.createDataSet().

CachingConnectionProvider

CachingConnectionProvider (new in 3.4.0) caches a single IDatabaseConnection — and the table metadata it accumulates — so it can be reused across many test methods instead of being rebuilt on every call. A Callable<IDatabaseConnection> supplies the connection-creation logic; the factory runs only when there is no cached connection yet, or the previously cached one is no longer alive (checked with Connection.isValid(int)), in which case the dead connection is closed and transparently replaced.

Construct one instance per target database and share it across the JdbcDatabaseTester, DataSourceDatabaseTester, JndiDatabaseTester, or DefaultDatabaseTester instances created for each test — typically a static field on a common test base class:

private static final CachingConnectionProvider CONNECTION_PROVIDER =
        new CachingConnectionProvider();

@BeforeEach
void setUp() throws Exception
{
    final IDatabaseTester tester = new JdbcDatabaseTester(driverClass,
            connectionUrl, username, password, schema, CONNECTION_PROVIDER);
    // The default IOperationListener closes the connection after every
    // onSetup()/onTearDown() call, which would defeat the cache. Pair it
    // with a listener that leaves the connection open, e.g.:
    tester.setOperationListener(IOperationListener.NO_OP_OPERATION_LISTENER);
    ...
}

Thread safety. Access to the cached connection is synchronized, so concurrent callers cannot create or replace it at the same time. The returned IDatabaseConnection — and the underlying JDBC Connection it wraps — is not itself synchronized, so this is only appropriate for test suites that run sequentially, not test methods executing concurrently against the same cached connection.

Metadata staleness. Because the whole point of reuse is avoiding re-fetching table metadata, a cached connection’s DatabaseDataSet does not notice schema changes (new/dropped/altered tables) made after it was first cached. Do not share a provider across tests that alter DDL mid-run.

See the IDatabaseTester guide for the full setup/teardown lifecycle this fits into, and Best Practices for when connection reuse across test methods is (and isn’t) a good idea.