# firebird-testcontainers-java

**Repository Path**: mirrors_FirebirdSQL/firebird-testcontainers-java

## Basic Information

- **Project Name**: firebird-testcontainers-java
- **Description**: Firebird-testcontainers-java is a module for Testcontainers.org to provide lightweight, throwaway instances of Firebird for JUnit tests.
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-09-24
- **Last Updated**: 2026-03-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

firebird-testcontainers-java
============================
[![Java CI with Maven](https://github.com/FirebirdSQL/firebird-testcontainers-java/actions/workflows/maven.yml/badge.svg?branch=master)](https://github.com/FirebirdSQL/firebird-testcontainers-java/actions/workflows/maven.yml?query=branch%3Amaster)
[![MavenCentral](https://maven-badges.sml.io/sonatype-central/org.firebirdsql/firebird-testcontainers-java/badge.svg)](https://maven-badges.sml.io/sonatype-central/org.firebirdsql/firebird-testcontainers-java/)

Firebird-testcontainers-java is a module for [Testcontainers](https://www.testcontainers.org/)
to provide lightweight, throwaway instances of Firebird for JUnit tests.

The default Docker image used is [firebirdsql/firebird](https://hub.docker.com/r/firebirdsql/firebird), and also supports 
 [jacobalberty/firebird](https://hub.docker.com/r/jacobalberty/firebird/).

If you want to use Firebird 2.5, use the 2.5.x-sc (SuperClassic) variant of 
the `jacobalberty/firebird` image, or 2.5.9-ss as earlier versions of the 2.5.x-ss 
(SuperServer) variant seem to be broken. However, recently, it seems that the
2.5.x-sc variants also no longer work reliably.

Prerequisites
-------------

- Docker
- A supported JVM testing framework

See [Testcontainers prerequisites](https://www.testcontainers.org/#prerequisites) for details.

Dependency
----------

In addition to the firebird-testcontainers-java dependency, you will also need
to explicitly depend on [Jaybird](https://github.com/FirebirdSQL/jaybird).

### Gradle

```groovy
testImplementation "org.firebirdsql:firebird-testcontainers-java:2.0.0"
```

### Maven

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

Usage
-----

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

### JUnit support

Starting with `firebird-testcontainers-java` 2.0.0, use of JUnit 4 is no longer
supported directly. If you still need JUnit 4 support, use `firebird-testcontainers-java`
1.6.1, use URL based, or derive your own rule implementation to start and stop
the container.

For JUnit 5 support, add `org.testcontainers:testcontainers-junit-jupiter` as
a test dependency. Annotate the test class with `@Testcontainers`. Define
a `FirebirdContainer` static (shared by all tests), or instance (per test)
field. Annotate this field with `@Container`.

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 `firebirdsql/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` (`firebirdsql/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` (`firebirdsql/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` (`firebirdsql/firebird`) to the specified value.

Example of use:

```java
package org.firebirdsql.testcontainers.examples;

import org.firebirdsql.testcontainers.FirebirdContainer;
import org.junit.jupiter.api.Test;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;

import java.sql.*;

import static org.junit.jupiter.api.Assertions.*;

/**
 * Simple test demonstrating use of {@code @Testcontainers} and {@code @Container}.
 */
@Testcontainers
public class ExampleContainerTest {

  @Container
  public final FirebirdContainer container = new FirebirdContainer("firebirdsql/firebird:5.0.3")
          .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(rs.next(), "has row");
      assertEquals("TESTUSER", rs.getString(1), "user name");
    }
  }
}
```

### 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

These URLs use the `firebirdsql/firebird` images, except for tags starting with
`2.`, `v2`, `v3`, `v4` or `v5`, which will select the `jacobalberty/firebird`
images for backwards compatibility.

Example of use:

```java
import org.junit.jupiter.api.Test;

import java.sql.*;

import static org.junit.jupiter.api.Assertions.*;

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

  @Test
  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(rs.next(), "has row");
      assertEquals("SOMEUSER", rs.getString(1), "user name");
    }
  }
}
```

For this type of use, it is not necessary to add `org.testcontainers:testcontainers-junit-jupiter`
as a test dependency.

License
-------

See [LICENSE](LICENSE)