firebird-testcontainers-java

Firebird-testcontainers-java is a module for Testcontainers to provide lightweight, throwaway instances of Firebird for JUnit tests.

The docker image used is jacobalberty/firebird, and also supports ghcr.io/fdcastel/firebird.

If you want to use Firebird 2.5, use the 2.5.x-sc (SuperClassic) variant of the image, or 2.5.9-ss as earlier versions of the 2.5.x-ss (SuperServer) variant seem to be broken.

Prerequisites

• Docker
• A supported JVM testing framework

See Testcontainers prerequisites for details.

Dependency

In addition to the firebird-testcontainers-java dependency, you will also need to explicitly depend on Jaybird.

Gradle

testImplementation "org.firebirdsql:firebird-testcontainers-java:1.5.0"

Maven

<dependency>
    <groupId>org.firebirdsql</groupId>
    <artifactId>firebird-testcontainers-java</artifactId>
    <version>1.5.0</version>
    <scope>test</scope>
</dependency>

Usage

For extensive documentation, consult https://www.testcontainers.org/modules/databases/

JUnit rule

Using a JUnit @Rule or @ClassRule you can configure a container and start it per test (@Rule) or per class (@ClassRule).

The container defines several withXXX methods for configuration.

Important standard options are:

• withUsername(String) - Sets the username to create (defaults to test); sets docker environment variable FIREBIRD_USER.
  For jacobalberty/firebird, if the value is sysdba, FIREBIRD_USER is not set.
• withPassword(String) - Sets the password of the user (defaults to test); sets the docker environment variable FIREBIRD_PASSWORD.
  For jacobalberty/firebird, if the username is sysdba, ISC_PASSWORD is set instead of FIREBIRD_PASSWORD.
  For ghcr.io/fdcastel/firebird, if the username is sysdba, it also sets FIREBIRD_ROOT_PASSWORD.
• withDatabaseName(String) - Sets the database name (defaults to test); sets docker environment variable FIREBIRD_DATABASE

Firebird specific options are:

• withEnableLegacyClientAuth() - (Firebird 3+) Enables LegacyAuth and uses it as the default for creating users, also relaxes WireCrypt to Enabled; sets docker environment variable EnableLegacyClientAuth (jacobalberty/firebird) or FIREBIRD_USE_LEGACY_AUTH (ghcr.io/fdcastel/firebird) to true; passes connection property authPlugins with value Srp256,Srp,Legacy_Auth if this property is not explicitly set through withUrlParam.
• withEnableWireCrypt - (Firebird 3+) Relaxes WireCrypt from Required to Enabled; sets docker environment variable EnableWireCrypt (jacobalberty/firebird) to true, or FIREBIRD_CONF_WireCrypt (ghcr.io/fdcastel/firebird) to Enabled.
• withTimeZone(String) - Sets the time zone (defaults to JVM default time zone);
• sets docker environment variable TZ to the specified value
• withSysdbaPassword(String) - Sets the SYSDBA password, but if withUsername(String) is set to sysdba (case-insensitive), this property is ignored and the value of withPassword is used instead; sets docker environment variable ISC_PASSWORD (jacobalberty/firebird) or FIREBIRD_ROOT_PASSWORD (ghcr.io/fdcastel/firebird) to the specified value.

Example of use:

import org.firebirdsql.testcontainers.FirebirdContainer;
import org.testcontainers.utility.DockerImageName;

/**
 * Simple test demonstrating use of {@code @Rule}.
 */
public class ExampleRuleTest {

  private static final DockerImageName IMAGE = 
          DockerImageName.parse(FirebirdContainer.IMAGE).withTag("v4.0.2");

  @Rule
  public final FirebirdContainer<?> container = new FirebirdContainer<?>(IMAGE)
          .withUsername("testuser")
          .withPassword("testpassword");

  @Test
  public void canConnectToContainer() throws Exception {
    try (Connection connection = DriverManager
            .getConnection(container.getJdbcUrl(), container.getUsername(), container.getPassword());
         Statement stmt = connection.createStatement();
         ResultSet rs = stmt.executeQuery("select CURRENT_USER from RDB$DATABASE")) {
      assertTrue("has row", rs.next());
      assertEquals("user name", "TESTUSER", rs.getString(1));
    }
  }
}

Testcontainers URL

The testcontainers URL defines the container and connects to it. As long as there are active connections, the container will stay up.

For Firebird the URL format is:

• jdbc:tc:firebird[:<image-tag>]://hostname/<databasename>[?<property>=<value>[&<property>=<value>...]]
• jdbc:tc:firebirdsql[:<image-tag>]://hostname/<databasename>[?<property>=<value>[&<property>=<value>...]]

Where:

• <image-tag> (optional, but recommended) is the tag of the docker image to use, otherwise the default is used (which might change between versions)
• <databasename> (optional) is the name of the database (defaults to test)
• <property> is a connection property (Jaybird properties and testcontainers properties are possible)
  Of special note are the properties:
  • user (optional) specifies the username to create and connect (defaults to test)
  • password (optional) specifies the password for the user (defaults to test)
• <value> is the value of the property

Currently, these URLs can only use the jacobalberty/firebird images.

Example of use:

/**
 * Simple test demonstrating use of url to instantiate container.
 */
public class ExampleUrlTest {

    @Test
    public void canConnectUsingUrl() throws Exception {
        try (Connection connection = DriverManager
                .getConnection("jdbc:tc:firebird://hostname/databasename?user=someuser&password=somepwd");
             Statement stmt = connection.createStatement();
             ResultSet rs = stmt.executeQuery("select CURRENT_USER from RDB$DATABASE")) {
            assertTrue("has row", rs.next());
            assertEquals("user name", "SOMEUSER", rs.getString(1));
        }
    }
}

License

See LICENSE