foundationdb

FoundationDB Testcontainer

Testcontainer module for FoundationDB. Spins up a single-node FDB instance for testing, with a published coordinator port for host clients and a bridge-IP cluster file for containers on the same network. Clients must also be able to reach the server-advertised bridge addresses. No socat proxy is provided.

Installation

go get fdb.dev/pkg/testcontainers/foundationdb@master

Quick Start

import (
    "context"
    "testing"
    "time"

    "fdb.dev/pkg/fdbgo/fdb"
    foundationdbtc "fdb.dev/pkg/testcontainers/foundationdb"
)

func TestSomething(t *testing.T) {
    ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
    defer cancel()

    // Start container — auto-initialized, ready to use.
    container, err := foundationdbtc.Run(ctx, "")
    if err != nil {
        t.Fatal(err)
    }
    t.Cleanup(func() {
        cleanupCtx, cancel := context.WithTimeout(context.Background(), time.Minute)
        defer cancel()
        if err := container.Terminate(cleanupCtx); err != nil {
            t.Errorf("terminate FoundationDB: %v", err)
        }
    })

    // Get cluster file path for your FDB client.
    path, err := container.ClusterFilePath(ctx)
    if err != nil {
        t.Fatal(err)
    }
    fdb.MustAPIVersion(730)
    db, err := fdb.OpenDatabase(path)
    if err != nil {
        t.Fatal(err)
    }
    defer db.Close()
    // Use db in your test.
}

How It Works

1. Starts FDB container with Docker port mapping (4500/tcp exposed)
2. Waits for FDBD joined cluster log
3. Reads the cluster file from inside the container (via Exec with multiplexed stream demuxing)
4. Constructs an external cluster file using the Docker host's address and mapped port (usually localhost:mappedPort)
5. Runs fdbcli configure new single memory tenant_mode=optional_experimental
6. Returns ready-to-use container

External clients use ClusterFile or ClusterFilePath to bootstrap through the published Docker-host port. The fixture rewrites only the cluster file's coordinator address; it does not change the server's advertised GRV, commit, or storage addresses. Clients must also route to those bridge-IP endpoints to execute transactions (foundationdb.go, run). A reachable published port alone is insufficient: the default fixture does not support Docker Desktop or remote-daemon setups whose bridge addresses are unreachable from the test process.

Internal clients (containers on the same Docker network) use InternalClusterFile to connect via containerIP:4500 (or the configured FDB port).

Options

// FDB version (Docker image tag). Default: FDB_VERSION env or 7.3.77.
foundationdbtc.WithVersion("7.3.77")

// FDB API version (metadata for callers). Default: 730.
foundationdbtc.WithAPIVersion(730)

// Skip auto-initialization (call InitializeDatabase manually).
foundationdbtc.WithoutInit()

// Storage engine: "memory" (default), "ssd", "ssd-redwood-1", etc.
foundationdbtc.WithStorageEngine("memory")

// Redundancy: "single" (default), "double", "triple".
foundationdbtc.WithRedundancyMode("single")

// Tenant mode: "disabled", "optional_experimental" (default), "required".
foundationdbtc.WithTenantMode("optional_experimental")

// Custom FDB port (default: 4500).
foundationdbtc.WithFDBPort(4500)

// Attach to an existing Docker network (for multi-container setups).
foundationdbtc.WithNetwork(nw, "fdb-node-1")

// Use the bridge-IP coordinator address instead of the published Docker-host port.
// This changes bootstrap only; both modes require routing to advertised bridge endpoints.
foundationdbtc.WithDirectIP()

// Startup timeout (default: 60s).
foundationdbtc.WithStartupTimeout(2 * time.Minute)

// Mix with standard testcontainers options:
testcontainers.WithEnv(map[string]string{"KEY": "VALUE"})

File I/O backend

Fixture servers default to --knob_disable_posix_kernel_aio=1 (FDB's supported EIO backend) on both tmpfs and disk. FoundationDB 7.3.77's KAIO file-growth path turns an interrupted fallocate into a fatal disk error instead of retrying; EIO grows files with eio_ftruncate and avoids that path. This does not disable sync/durability or change the client protocol or stored formats. The evidence and syscall-injection regression are recorded in RFC-250.

Callers specifically exercising KAIO can override the default with foundationdbtc.WithKnob("disable_posix_kernel_aio", "0"). That opt-in retains the upstream failure behavior until the server is upgraded or fixed.

Multi-Container Setup

For tests that need multiple containers on the same network (e.g., binding tester):

// Create a shared network first.
nw, _ := foundationdbtc.CreateNetwork(ctx)
defer nw.Remove(ctx)

fdb, _ := foundationdbtc.Run(ctx, "", foundationdbtc.WithNetwork(nw))

// Attach another container to the same network.
testerReq := testcontainers.ContainerRequest{
    Networks: []string{fdb.NetworkName()},
}

// The other container can reach FDB via the internal cluster file.
clusterFile := fdb.InternalClusterFile()  // "docker:docker@172.17.0.2:4500"

Chaos Testing

// Pause FDB (simulates network partition).
err := container.Pause(ctx)

// ... verify your application handles the outage ...

// Resume FDB.
err = container.Unpause(ctx)

Container Methods

Requirements

• Docker, with the coordinator address in the selected cluster file reachable from the test process
• Routing from the test process to all server-advertised bridge-IP endpoints, with or without WithDirectIP; Docker Desktop and remote daemons without that routing are not supported by the default fixture
• No FDB client libraries needed on host (pure Go client or connects via cluster file)