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"

Without PG_RUNTIME_DIR and PG_DATA_DIR the helper derives both under /var/tmp/pg-embed-{uid} on Linux and the BSDs, one tree per user that every project on the host shares. Set PG_EMBED_ROOT to give a project or a test run its own base (<root>/install and <root>/data); the two leaf variables still win when set. A derived <root>/data holds one directory per cluster, so concurrent test processes can share one root (see "Per-cluster data directories" below). On macOS and Windows there is no per-user default tree: without PG_EMBED_ROOT the postgresql_embedded defaults apply, and with it the same two leaves are derived.

Test clusters cap max_connections at 20 (a postgres container defaults to 100); set PG_MAX_CONNECTIONS when parallel test runners need more. The override applies to plain bootstrap() runs as well as test bootstraps, and values below 4 are rejected because PostgreSQL keeps three connection slots for superusers below max_connections.

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.