Package org.jdbi.v3.testing.junit5.tc

Class TestcontainersDatabaseInformation

java.lang.Object

org.jdbi.v3.testing.junit5.tc.TestcontainersDatabaseInformation

@Beta
public final class TestcontainersDatabaseInformation
extends Object

Describes the parameters needed to create a new test-specific database or schema to isolate a test. Testcontainers supports many different databases and the Jdbi specific extension requires parameterization.

The Testcontainers project provides a convenient way to spin up dependencies as containers and offers a Java API to access these instances. Jdbi can use these instances for testing and offers the same functionality as the builtin support for PostgreSQL, H2 and Sqlite.

As every database engine is slightly different and supports different features, there is some "glue" needed, which is specific to the testcontainer class. Out of the box, Jdbi works with the testcontainer support for MySQL, MariaDB, TiDB, PostgreSQL (inclusive PostGIS), CockroachDB, YugabyteDB, ClickhouseDB, Oracle XE, Oracle Free, TrinoDB and MSSQL Server.
Any of the testcontainer instances for these databases, can be used with JdbiTestcontainersExtension.instance(JdbcDatabaseContainer) to create a JUnit 5 Extension instance that will manage database and schema instances for tests.

If a testcontainer class is not supported by Jdbi or the current Jdbi behavior does not match what is required for a test (e.g. schema or user creation), a custom TestcontainersDatabaseInformation instance can be created using the of(String, String, String, BiFunction) method.
This instance can be passed into the JdbiTestcontainersExtension.instance(TestcontainersDatabaseInformation, JdbcDatabaseContainer) method to create a custom JUnit 5 Extension.

Method Summary

Modifier and Type	Method	Description
static TestcontainersDatabaseInformation	forTestcontainerClass(Class<? extends JdbcDatabaseContainer> containerClazz)	Returns a TestcontainersDatabaseInformation instance for a given container instance class.
int	getShutdownWaitTimeInSeconds()	Returns the time in seconds that a test will wait to shut down the Jdbi extension.
static TestcontainersDatabaseInformation	of(String user, String catalog, String schema, BiFunction<String,String,String> createStatement)	Creates a new database information instance that describes a database.
static TestcontainersDatabaseInformation	ofScript(String user, String catalog, String schema, BiFunction<String,String,List<String>> createStatement)
void	setShutdownWaitTimeInSeconds(int shutdownWaitTimeInSeconds)	Sets the wait time in seconds that a test will wait to shut down the Jdbi extension.
String	toString()

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Details

forTestcontainerClass

public static TestcontainersDatabaseInformation forTestcontainerClass(Class<? extends JdbcDatabaseContainer> containerClazz)

Returns a TestcontainersDatabaseInformation instance for a given container instance class.

Parameters:

containerClazz - A JdbcDatabaseContainer class object. Must not be null.

Returns:

A TestcontainersDatabaseInformation instance describing how to use the database with the JdbiTestcontainersExtension or null if the container class is unknown.

of

public static TestcontainersDatabaseInformation of(String user,
 String catalog,
 String schema,
 BiFunction<String,String,String> createStatement)

Creates a new database information instance that describes a database.

Parameters:

user - Specify a user that can create a new schema or database. If this parameter is null, the testcontainer specific default user, returned by JdbcDatabaseContainer.getUsername() is used.

catalog - Specify a catalog that should be used. This is for databases that do not support creating a new catalog or require a fixed catalog for schema creation (e.g. Trino). If null, use a random catalog identifier.

schema - Specify a schema that should be used. This is for databases that do not support schemas but create a new database for each test. If null, use a random schema identifier.

createStatement - A BiFunction that returns a single statement to create a new database or schema for test isolation. The function is called with the catalog and schema name and must return a single, valid SQL statement.

Returns:

A TestcontainersDatabaseInformation object

ofScript

public static TestcontainersDatabaseInformation ofScript(String user,
 String catalog,
 String schema,
 BiFunction<String,String,List<String>> createStatement)

Parameters:

user - Specify a user that can create a new schema or database. If this parameter is null, the testcontainer specific default user, returned by JdbcDatabaseContainer.getUsername() is used.

catalog - Specify a catalog that should be used. This is for databases that do not support creating a new catalog or require a fixed catalog for schema creation (e.g. Trino). If null, use a random catalog identifier.

schema - Specify a schema that should be used. This is for databases that do not support schemas but create a new database for each test. If null, use a random schema identifier.

createStatement - A BiFunction that returns a single statement to create a new database or schema for test isolation. The function is called with the catalog and schema name and must return a list of one or more valid SQL statements.

Returns:

A TestcontainersDatabaseInformation object

getShutdownWaitTimeInSeconds

@Alpha
public int getShutdownWaitTimeInSeconds()

Returns the time in seconds that a test will wait to shut down the Jdbi extension.

Returns:

The time to wait in seconds to shut down the Jdbi extension. 0 means wait infinitely until the extension has been stopped. This can lead to infinite hangs in test cases and should be used with caution.

Since:

3.45.0

setShutdownWaitTimeInSeconds

@Alpha
public void setShutdownWaitTimeInSeconds(int shutdownWaitTimeInSeconds)

Sets the wait time in seconds that a test will wait to shut down the Jdbi extension.

Parameters:

shutdownWaitTimeInSeconds - The wait time in seconds to shut down the Jdbi extension. Can be set to 0 which means that it will wait infinitely until the extension has shut down. 0 may lead to infinite hangs in tests and should be used with caution.

Since:

3.45.0

toString

public String toString()

Overrides:

toString in class Object