# Zero-config RAII Postgres test fixture roadmap
## Roadmap appendix: platform expectations
### macOS
- Unprivileged runs are expected to behave like the Linux unprivileged flow,
executing in-process with the caller's user ID (UID) / group ID (GID).
- Root executions are expected to fail fast because privilege dropping is not
supported on macOS targets; the worker-based path must not be relied on.
- Behavioural tests that require root privileges should skip on macOS unless a
future milestone introduces supported privilege management for that platform.
- Pull-request CI validates the unprivileged surface on
`aarch64-apple-darwin`. The release workflow publishes and audits both
`aarch64-apple-darwin` and `x86_64-apple-darwin` `cargo binstall` archives.
### Windows
- The runtime always reports unprivileged execution, so tests and fixtures run
the in-process path without requiring `PG_EMBEDDED_WORKER`.
- Root-only scenarios are expected to skip because privilege dropping is not
supported on Windows targets.
- Pull-request CI validates the unprivileged surface and a real
`cargo binstall` install-and-run on `x86_64-pc-windows-msvc`.
- Windows on ARM is not targeted because the upstream PostgreSQL binary archive
does not provide `aarch64-pc-windows-msvc` binaries.
- POSIX file-mode privacy does not apply on Windows. Directory privacy depends
on the account's access control lists (ACLs), so callers should choose
private runtime and data paths when local account separation matters.
## 1. Stabilize zero-configuration bootstrap
### 1.1. Detect and adapt to execution privileges
- [x] 1.1.1. Ship runtime privilege detection that branches between root and
unprivileged flows, verified by integration tests covering both contexts.
- [x] 1.1.2. Introduce mandatory privilege-dropping logic for root executions
that provisions directories under the `nobody` user and proves idempotence
across two consecutive cluster initializations.
### 1.2. Harden bootstrap orchestration
- [x] 1.2.1. Deliver a `bootstrap_for_tests()` helper that wraps configuration
discovery, handles privilege checks, and prepares directories, returning a
structured settings object exercised in sample tests.
- [x] 1.2.2. Automate environment variable preparation (for example `TZDIR` and
`PGPASSFILE`) with traceable defaults validated through assertions in the
bootstrap tests.
## 2. Provide an ergonomic RAII fixture
### 2.1. Implement the `TestCluster` lifecycle
- [x] 2.1.1. Create the `TestCluster` RAII struct with `new` and `Drop`
implementations that guarantee cluster startup and teardown, evidenced by
tests ensuring no processes remain after scope exit.
- [x] 2.1.2. Expose connection metadata and helper methods (for example a
Diesel connection constructor) with documentation examples and smoke tests
that execute simple SQL statements.
### 2.2. Integrate with test frameworks
- [x] 2.2.1. Publish an `rstest` fixture (or equivalent) that yields a ready
`TestCluster`, demonstrated in example tests showing zero explicit setup.
- [x] 2.2.2. Document usage patterns in README excerpts and doctests, so the
fixture becomes the default path for new integration tests.
## 3. Enhance visibility and platform coverage
### 3.1. Instrument setup for observability
- [x] 3.1.1. Add `tracing` spans and logs around privilege changes, directory
mutations, environment variable injection, and PostgreSQL lifecycle events,
verified by log assertions in integration tests.
- [x] 3.1.2. Surface the chosen settings (ports, directories, version) via
debug logging with sanitized output, ensuring sensitive values are redacted.
### 3.2. Strengthen concurrency guarantees
- [x] 3.2.1. Add Loom-based concurrency tests for the `ScopedEnv` mutex, gated
behind a feature flag, and document how to run them.
### 3.3. Validate cross-platform behaviour
- [x] 3.3.1. Confirm Linux root and unprivileged paths through Continuous
Integration (CI) matrix jobs, and document expected outcomes for macOS and
Windows in the roadmap appendix.
- [x] 3.3.2. Establish guardrails that fail fast on unsupported root scenarios
on unsupported Unix targets such as macOS, including unit coverage for the
error messaging and CI target checks for macOS and Windows.
### 3.4 Maintain contributor quality gates
- [x] 3.4.1. Pin the Rust formatting and linting toolchain, import the shared
rustfmt and Clippy policy, and require 100% Python docstring coverage in the
local and CI lint gates.