pg-embed-setup-unpriv 0.5.0

Initialises postgresql_embedded clusters as root while handing off filesystem work to nobody
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91

# pg_embedded_setup_unpriv

*Zero-configuration PostgreSQL test fixtures for Rust—whether you're root or
not.*

## Why pg_embedded_setup_unpriv?

Writing integration tests against PostgreSQL should be straightforward, but
environments vary: CI containers often run as root, developer laptops don't,
and everyone wants the same tests to pass everywhere. This crate makes that
happen:

- **Zero configuration**: Spin up a real PostgreSQL instance with a single
  line of code. No environment variables, config files, or manual setup
  required.
- **Works anywhere**: The same test code runs on root CI (Codex, containers)
  and unprivileged machines (GitHub Actions, your laptop)—the library detects
  privileges at runtime and adapts.
- **RAII lifecycle**: `TestCluster` starts PostgreSQL on construction and
  stops it on drop. No orphan processes, no cleanup code.
- **Fast test isolation**: Clone pre-migrated template databases in
  milliseconds instead of bootstrapping fresh clusters for each test.

## Quick start

### Installation

Add to your `Cargo.toml`:

```toml
[dev-dependencies]
pg-embed-setup-unpriv = "0.5"
rstest = "0.26"
```

### Basic usage

```rust
use pg_embedded_setup_unpriv::{test_support::test_cluster, TestCluster};
use rstest::rstest;

#[rstest]
fn test_my_database_logic(test_cluster: TestCluster) {
    let url = test_cluster.connection().database_url("postgres");
    // Connect with your preferred client and run queries
    assert!(url.starts_with("postgresql://"));
}
```

That's it. The `test_cluster` fixture handles downloading PostgreSQL, creating
directories, starting the server, and cleaning up when the test ends.

## Features

- **Automatic privilege detection**: Root executions delegate filesystem work
  to a `pg_worker` subprocess running as `nobody`; unprivileged executions run
  entirely in-process.
- **rstest integration**: Ready-made fixtures (`test_cluster`,
  `shared_test_cluster`) for declarative test setup.
- **Async support**: Use `TestCluster::start_async()` in `#[tokio::test]`
  contexts (requires the `async-api` feature).
- **Template databases**: Clone databases via PostgreSQL's `TEMPLATE`
  mechanism for sub-second test isolation.
- **Diesel support**: Optional `diesel-support` feature provides
  `diesel_connection()` for direct database access.
- **Observability**: Tracing spans for lifecycle events, with sensitive values
  automatically redacted.

## Running as root / pg_worker

If your tests run as `root` (common in containers/CI) and you hit privilege
errors, ensure the `pg_worker` helper is configured via `PG_EMBEDDED_WORKER`.
See the Users' Guide section on root-only test agents for the required setup
and environment variables.[^root-worker]

[^root-worker]: docs/users-guide.md#integrating-with-root-only-test-agents

## Learn more

- [Users' Guide](docs/users-guide.md) — full documentation, async API,
  template databases, and performance tuning
- [Developers' Guide](docs/developers-guide.md) — contributing and development
- [Roadmap](docs/roadmap.md) — planned features and progress

## Licence

ISC — see the licence in [LICENSE](LICENSE) for details.

## Contributing

Contributions welcome! Please see [AGENTS.md](AGENTS.md) for guidelines.