factstr-postgres 0.4.0

PostgreSQL store for FACTSTR with append, query, streams, and durable streams.
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

# factstr-postgres

`factstr-postgres` is the PostgreSQL-backed store implementation for the shared [`factstr`](https://crates.io/crates/factstr) contract.

Use this crate when an application already operates PostgreSQL and wants FACTSTR persistence there.

## What it implements

`factstr-postgres` implements the shared `factstr::EventStore` contract, including:

- `append`
- `query`
- `append_if`
- `stream_all`
- `stream_to`
- `stream_all_durable`
- `stream_to_durable`

## When to use it

Use `factstr-postgres` when:

- you want FACTSTR backed by PostgreSQL
- your application already operates PostgreSQL
- you want durable stream cursor state to persist in PostgreSQL

## Store behavior and boundaries

- Committed facts and durable stream cursors are stored in PostgreSQL.
- SQL transactions and indexes are used internally.
- An internal worker thread keeps the synchronous store API safe to call from inside a running Tokio runtime.
- Durable replay depends on persisted append-batch history.
- Older databases without contiguous append-batch history are rejected for durable replay instead of being silently backfilled.

Integration tests for this crate require a PostgreSQL database.

## Add to `Cargo.toml`

```toml
[dependencies]
factstr = "0.3"
factstr-postgres = "0.3"
```

## Minimal example

```rust
use factstr::{EventQuery, EventStore, NewEvent};
use factstr_postgres::PostgresStore;
use serde_json::json;
use std::env;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let database_url = env::var("DATABASE_URL")?;
    let store = PostgresStore::connect(&database_url)?;

    store.append(vec![NewEvent {
        event_type: "item-added".to_owned(),
        payload: json!({ "sku": "ABC-123", "quantity": 1 }),
    }])?;

    let result = store.query(&EventQuery::all())?;
    assert_eq!(result.event_records.len(), 1);

    Ok(())
}
```

## Related crates

- [`factstr`](https://crates.io/crates/factstr): shared contract and core types
- [`factstr-memory`](https://crates.io/crates/factstr-memory): in-memory store
- [`factstr-sqlite`](https://crates.io/crates/factstr-sqlite): embedded persistent store

## License

Licensed under either of:

- MIT license
- Apache License, Version 2.0