Quick start

1. Choose directories for the staged PostgreSQL distribution and the cluster’s data files. They must be writable by whichever user will run the helper; the tool reapplies ownership and permissions on every invocation.

2. Export configuration:

   export PG_VERSION_REQ="=16.4.0"
   export PG_RUNTIME_DIR="/var/tmp/pg-embedded-setup-it/install"
   export PG_DATA_DIR="/var/tmp/pg-embedded-setup-it/data"
   export PG_SUPERUSER="postgres"
   export PG_PASSWORD="postgres_pass"

Optionally set PG_SHUTDOWN_TIMEOUT_SECS to override the 15-second drop budget. The helper accepts values between 1 and 600 seconds and reports an error when the override falls outside that range or cannot be parsed.

3. Run the helper (cargo run --release --bin pg_embedded_setup_unpriv). The command downloads the specified PostgreSQL release, ensures the directories exist, applies PostgreSQL-compatible permissions (0755 for the installation cache, 0700 for the runtime and data directories), and initialises the cluster with the provided credentials. Invocations that begin as root prepare directories for nobody and execute lifecycle commands through the worker helper so the privileged operations run entirely under the sandbox user. Ownership fix-ups occur on every call so running the tool twice remains idempotent.

4. Pass the resulting paths and credentials to your tests. If you use postgresql_embedded directly after the setup step, it can reuse the staged binaries and data directory without needing root.