postgres

PostgreSQL service. Source-built against a no-spaces install prefix under ~/Library/Caches/unibench/binaries/postgres/<version>/. Binds loopback-only (127.0.0.1) so it's never accidentally exposed off-box.

Manifest knobs

[services.pg]
type = "postgres"
version = "16.10"              # default; pick any blessed major.minor
port = "auto"                   # or pin: port = 5432
isolation = "per-project"       # default; "shared" is unusual for SQL
healthcheck_retries = 3         # default

pg_isready -h 127.0.0.1 -p <port> is the healthcheck; the orchestrator runs it with the standard 5/15/45s retry backoff.

On-disk layout

<project>/.unibench-data/<service>/
├── postmaster.pid
└── …                          # PGDATA contents

unibench start --fresh wipes this directory before reinitializing.

Inspection drawer

The Inspect tab exposes:

  • Connection string — postgresql://postgres@127.0.0.1:<port>/postgres (trust auth on loopback; no password component).
  • Tables — every user table with pg_class's planner row estimate. Refresh button re-queries.
  • External tools — one-click jump-out to psql, pgcli, pgAdmin, or TablePlus if they're installed locally.

$<NAME>_PORT injection

Dependent services that declare depends_on = [{ service = "pg", condition = "healthy" }] see $PG_PORT and $PG_HOST in their environment. The variable name is the upper-cased service name with non-alphanumeric chars folded to _ (so a service named my-db exports $MY_DB_PORT).

Common gotchas

  • Apple-Silicon-only builds. The blessed binaries are aarch64-apple-darwin. Running under Rosetta is unsupported — install the native arm64 build of Unibench.
  • Data-dir version skew. initdb refuses to write into a non-empty directory; bumping version from 15 to 16 means running unibench start --fresh so initdb can rebuild the catalog. The known-issues lookup catches this signature (known issue: postgres.initdb_data_dir_not_empty).
  • Locale. initdb uses the system locale. On a fresh macOS this is usually en_US.UTF-8; setting LC_ALL=C in your shell before unibench start causes Postgres to come up with a non-UTF8 default collation that won't match what production probably uses.

Escape hatch

Need PG ≥17 or a contrib extension we don't ship? Drop down to a process service that runs your own Postgres binary, or a container service against the official postgres image.