Quick start

Tagged releases publish both CLI binaries in cargo binstall archives for:

Table 1: Host release targets for tagged cargo binstall archives.

Install the host release with:

cargo binstall pg-embed-setup-unpriv

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 Unix 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 installed helper (pg_embedded_setup_unpriv). The command downloads the specified PostgreSQL release, ensures the directories exist, applies PostgreSQL-compatible permissions on Unix (0755 for the installation cache, 0700 for the runtime and data directories), and initializes the cluster with the provided credentials via initdb. On Windows, POSIX mode changes are skipped and the current account's ACL defaults apply. The PostgreSQL server is not started — the installation is left ready for subsequent use by TestCluster or other tools. 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 the test suite. Direct postgresql_embedded usage after the setup step can reuse the staged binaries and data directory without needing root.