Database Test Lab

The Database Test Lab provides small, pinned Docker Compose environments for testing DBX against real database versions. Every recipe uses a named data volume, a health check, initialization data or smoke data created during verification, and listens on 127.0.0.1 by default.

Available recipes

Every network recipe uses a host port one greater than the database standard port, and the recipe validator enforces that contract. The default password is 123456, and the default database is dbx. Redis has no named databases, so it uses DB 0 with a dbx: smoke-key prefix. Compose uses the CNB image column; the Docker Hub column preserves the official upstream reference for provenance and direct pulls. Redis 3.0.7 is amd64-only; on arm64 hosts the command prints an architecture warning and Docker uses emulation. Every other recipe supports both amd64 and arm64.

Redis 3.0.7 and Redis 7.4.9 intentionally cover the compatibility endpoints. Redis 3 predates ACLs, RESP3, Streams, and many modern commands, while Redis 7 covers the current protocol and command set. Keeping 6.2 and 7.4 together would provide less compatibility coverage for this lab.

Versions of the same product intentionally share that default host port. Start them one at a time, or give one version another port when comparing versions concurrently:

DB_PORT=13307 make db DB=mysql@5.7
make db DB=mysql@8.4

Start and verify an environment

Run commands from the repository root. List the available recipes, then choose a database and version:

make db
make db-list
make db DB=postgresql@17.4
make db-verify DB=postgresql@17.4

make db without parameters prints every currently supported copy-and-paste start command, plus optional parameters. With DB=product@version, it waits for the Compose health check and prints the DBX connection fields. db-verify also runs the recipe's smoke command inside the database container and checks its expected output. It is the preferred command before reporting a database-specific fix.

Commands and variables

DB_BIND_ADDRESS changes the host-side bind address, DB_PORT changes the host-side port, and DB_PASSWORD changes the default password. For example:

DB_PORT=13306 DB_PASSWORD=local-secret make db-verify DB=mysql@8.4

Remote access must be enabled explicitly:

DB_BIND_ADDRESS=0.0.0.0 DB_PASSWORD=local-secret make db DB=mysql@8.4

db-reset is intentionally guarded: it will not remove a named volume unless CONFIRM=1 is set. Redis has no image initialization-directory convention; its init/README.md documents the smoke key created and read by verify. The lower-level info, status, logs, and shell commands remain available as pnpm db:env -- <command> <product> <version> when needed for diagnosis.

Tab completion

The repository includes dynamic completion for Make targets and DB=product@version values. It reads the current recipe directories, so newly added versions appear without editing the completion scripts.

# Bash
source deploy/database/completion/dbx-make.bash

# Zsh
autoload -Uz compinit && compinit
source deploy/database/completion/_dbx-make.zsh

# PowerShell
. .\deploy\database\completion\Dbx.Make.ps1

Run make db-completion to print these commands. After sourcing the appropriate file, press Tab after make db DB= to select a recipe. The Make targets themselves avoid POSIX-shell conditionals, so they work with GNU Make in PowerShell, Git Bash, or WSL; Docker Desktop and Node.js/pnpm must be available.

Add a recipe

Add a directory under deploy/database/<product>/<version>/ containing:

recipe.json
compose.yaml
init/

recipe.json supplies the DBX connection fields and smoke command array. Do not use a shell string for smoke checks: commands execute as argument arrays. Compose files must pin an image, use a named volume and health check, default port bindings to ${DB_BIND_ADDRESS:-127.0.0.1}, and set container_name to dbx-<product>-<version>.

Finish by running:

pnpm test:db-env
make db-check