ephemeral-postgres 0.1.0

Ephemeral PostgreSQL instances for Rust integration tests, backed by testcontainers (Docker).
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

# ephemeral-postgres

Ephemeral PostgreSQL instances for Rust integration tests, backed by
[testcontainers](https://crates.io/crates/testcontainers) (Docker).

Each test starts its own PostgreSQL container and carves out isolated databases from it, so
tests never share state. Containers are removed automatically when the cluster is dropped.

## Requirements

A running Docker daemon. Docker is needed only at **test runtime** to start containers — it is
not required to build the crate or its documentation.

## Install

```toml
[dev-dependencies]
ephemeral-postgres = "0.1"
```

## Usage

```rust
use ephemeral_postgres::cluster::Cluster;
use sqlx::Row;

#[tokio::test]
async fn each_test_gets_an_isolated_database() {
    let cluster = Cluster::start().await.unwrap();
    let database = cluster.create_database().await.unwrap();

    let value: i32 = sqlx::query("SELECT 1::int AS value")
        .fetch_one(database.pool())
        .await
        .unwrap()
        .get("value");

    assert_eq!(value, 1);
}
```

- `Cluster::start()` starts one PostgreSQL container.
- `create_database()` / `create_database_with_id(uuid)` create freshly-isolated databases that
  share the container.
- `database.pool()` returns an `sqlx::PgPool` connected to that database.
- Dropping the last `Arc<Cluster>` stops and removes the container.

## Configuration

```rust
use std::time::Duration;

use ephemeral_postgres::cluster::Cluster;
use ephemeral_postgres::cluster_params::ClusterParams;

let cluster = Cluster::start_with_params(ClusterParams {
    image_tag: "17".to_owned(),
    readiness_timeout: Duration::from_secs(60),
})
.await?;
```

`ClusterParams::default()` pins a specific `postgres` image digest and waits up to 30 seconds for
the server to accept connections.

## License

Apache-2.0.