Skip to content

Latest commit

 

History

History
327 lines (203 loc) · 11.8 KB

README.md

File metadata and controls

327 lines (203 loc) · 11.8 KB

firebird-docker

Docker images for Firebird Database.

Quick reference

Supported tags

firebirdsql/firebird Dockerfile
5, 5.0.2, latest Dockerfile
bullseye, 5-bullseye, 5.0.2-bullseye Dockerfile
jammy, 5-jammy, 5.0.2-jammy Dockerfile
noble, 5-noble, 5.0.2-noble Dockerfile
5.0.1 Dockerfile
5.0.1-bullseye Dockerfile
5.0.1-jammy Dockerfile
5.0.1-noble Dockerfile
5.0.0 Dockerfile
5.0.0-bullseye Dockerfile
5.0.0-jammy Dockerfile
5.0.0-noble Dockerfile
4, 4.0.5 Dockerfile
4-bullseye, 4.0.5-bullseye Dockerfile
4-jammy, 4.0.5-jammy Dockerfile
4-noble, 4.0.5-noble Dockerfile
4.0.4 Dockerfile
4.0.4-bullseye Dockerfile
4.0.4-jammy Dockerfile
4.0.4-noble Dockerfile
4.0.3 Dockerfile
4.0.3-bullseye Dockerfile
4.0.3-jammy Dockerfile
4.0.3-noble Dockerfile
4.0.2 Dockerfile
4.0.2-bullseye Dockerfile
4.0.2-jammy Dockerfile
4.0.2-noble Dockerfile
4.0.1 Dockerfile
4.0.1-bullseye Dockerfile
4.0.1-jammy Dockerfile
4.0.1-noble Dockerfile
4.0.0 Dockerfile
4.0.0-bullseye Dockerfile
4.0.0-jammy Dockerfile
4.0.0-noble Dockerfile
3, 3.0.12 Dockerfile
3-bullseye, 3.0.12-bullseye Dockerfile
3-jammy, 3.0.12-jammy Dockerfile
3.0.11 Dockerfile
3.0.11-bullseye Dockerfile
3.0.11-jammy Dockerfile
3.0.10 Dockerfile
3.0.10-bullseye Dockerfile
3.0.10-jammy Dockerfile
3.0.9 Dockerfile
3.0.9-bullseye Dockerfile
3.0.9-jammy Dockerfile
3.0.8 Dockerfile
3.0.8-bullseye Dockerfile
3.0.8-jammy Dockerfile

Firebird 3 does not have an image for Ubuntu 24.04 LTS (Noble Numbat) due to a dependency (libncurses5) missing from Ubuntu sources.

How to use this image

Image defaults:

  • EXPOSE 3050/tcp
  • VOLUME /var/lib/firebird/data

Start a Firebird server instance

docker run \
    -e FIREBIRD_ROOT_PASSWORD=************ \
    -e FIREBIRD_USER=alice \
    -e FIREBIRD_PASSWORD=************ \
    -e FIREBIRD_DATABASE=mirror.fdb \
    -e FIREBIRD_DATABASE_DEFAULT_CHARSET=UTF8 \
    -v ./data:/var/lib/firebird/data \
    --detach firebirdsql/firebird

Using Docker Compose

services:
  firebird:
    image: firebirdsql/firebird
    restart: always
    environment:
      - FIREBIRD_ROOT_PASSWORD=************
      - FIREBIRD_USER=alice
      - FIREBIRD_PASSWORD=************
      - FIREBIRD_DATABASE=mirror.fdb
      - FIREBIRD_DATABASE_DEFAULT_CHARSET=UTF8
    volumes:
      - ./data:/var/lib/firebird/data

Connect to an existing instance using isql

docker run -it --rm firebirdsql/firebird isql -u SYSDBA -p ************ SERVER:/path/to/file.fdb

Environment variables

The following environment variables can be used to customize the container.

FIREBIRD_ROOT_PASSWORD

Firebird installer generates a one-off password for SYSDBA and stores it in /opt/firebird/SYSDBA.password.

If FIREBIRD_ROOT_PASSWORD is set, SYSDBA password will be changed. And the file /opt/firebird/SYSDBA.password will be removed.

FIREBIRD_USER

Creates an user in Firebird security database.

You must inform a password in FIREBIRD_PASSWORD variable. Otherwise the container initialization will fail.

FIREBIRD_DATABASE

Creates a new database. Ignored if the database already exists.

Database location is /var/lib/firebird/data. Absolute paths (outside this folder) are allowed.

You may use FIREBIRD_DATABASE_PAGE_SIZE to set the database page size. And FIREBIRD_DATABASE_DEFAULT_CHARSET to set the default character set.

FIREBIRD_USE_LEGACY_AUTH

Enables legacy authentication (not recommended).

FIREBIRD_CONF_*

Any variable starting with FIREBIRD_CONF_ can be used to set values in Firebird configuration file (firebird.conf).

E.g. You can use FIREBIRD_CONF_DataTypeCompatibility=3.0 to set the value of key DataTypeCompatibility to 3.0 in firebird.conf.

Please note that keys are case sensitive. And any key not present in firebird.conf will be ignored.

*_FILE

Any of the previously listed environment variables may be loaded from file by appending the _FILE suffix to the variable name.

E.g. FIREBIRD_PASSWORD_FILE=/run/secrets/firebird-passwd will load FIREBIRD_PASSWORD with the content from /run/secrets/firebird-passwd file.

Note that both the original variable and its _FILE variant are mutually exclusive. Trying to use both will cause the container initialization to fail.

Using database aliases

To use database aliases, create your own databases.conf file and configure a Docker bind mount for it at /opt/firebird/databases.conf.

More information:

Using Firebird Events

To use this image with Firebird Events you need to:

  • use FIREBIRD_CONF_RemoteAuxPort environment variable to set the value of RemoteAuxPort configuration to a specific port (e.g. 3051); and
  • Publish this port to the host.

More information:

Initializing the database contents

When creating a new database with FIREBIRD_DATABASE environment variable you can initialize it running one or more shell or SQL scripts.

Any file with extensions .sh, .sql, .sql.gz, .sql.xz and .sql.zst found in /docker-entrypoint-initdb.d/ will be executed in alphabetical order. .sh files without file execute permission (+x) will be sourced rather than executed.

IMPORTANT: Scripts will only run if you start the container with a data directory that is empty. Any pre-existing database will be left untouched on container startup.

Setting container time zone

The container runs in the UTC time zone by default. To change this, you can set the TZ environment variable:

    environment:
      - TZ=America/New_York

Alternatively, you can use the same time zone as your host system by mapping the /etc/localtime and /etc/timezone system files:

    volumes:
      - /etc/localtime:/etc/localtime:ro
      - /etc/timezone:/etc/timezone:ro

Backup and Restore

For online databases

If the database is in use, call gbak inside the running container using Firebird Service Manager (-se switch) for best performance.

The following commands will backup and restore a database in the data directory (/var/lib/firebird/data) of the running container.

# Online backup
FIREBIRD_CONTAINER=MY_CONTAINER_NAME_OR_ID
DATABASE_FILE=MY_DATABASE.fdb
BACKUP_FILE=MY_DATABASE.fbk

docker exec $FIREBIRD_CONTAINER bash -c "gbak -b -user SYSDBA -pas \$FIREBIRD_ROOT_PASSWORD -se localhost:service_mgr \$FIREBIRD_DATA/$DATABASE_FILE \$FIREBIRD_DATA/$BACKUP_FILE"
# Online restore
FIREBIRD_CONTAINER=MY_CONTAINER_NAME_OR_ID
BACKUP_FILE=MY_DATABASE.fbk
DATABASE_FILE=MY_DATABASE.fdb

docker exec $FIREBIRD_CONTAINER bash -c "gbak -c -user SYSDBA -pas \$FIREBIRD_ROOT_PASSWORD -se localhost:service_mgr \$FIREBIRD_DATA/$BACKUP_FILE \$FIREBIRD_DATA/$DATABASE_FILE"

For offline databases

IMPORTANT: Never use this with online (running) database files.

If you don't have a running server, create an ephemeral container to run gbak directly over the database files.

The following commands will backup and restore a database in the current directory ($PWD).

# Offline backup
FIREBIRD_IMAGE=firebirdsql/firebird
DATABASE_FILE=MY_DATABASE.fdb
BACKUP_FILE=MY_DATABASE.fbk

docker run --rm -v .:/pwd $FIREBIRD_IMAGE gbak -b /pwd/$DATABASE_FILE /pwd/$BACKUP_FILE 
# Offline restore
FIREBIRD_IMAGE=firebirdsql/firebird
BACKUP_FILE=MY_DATABASE.fbk
DATABASE_FILE=MY_DATABASE.fdb

docker run --rm -v .:/pwd $FIREBIRD_IMAGE gbak -c /pwd/$BACKUP_FILE /pwd/$DATABASE_FILE

More information:

Development notes

Prerequisites

Build

To generate the source files and build each image from assets.json configuration file, run:

Invoke-Build

You can then check all created images with:

docker image ls firebirdsql/firebird

Tests

To run the test suite for each image, use:

Invoke-Build Test