sayiir-postgres 0.1.0-alpha.13

PostgreSQL persistence backend for Sayiir workflow engine
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

# sayiir-postgres

PostgreSQL persistence backend for the [Sayiir](https://github.com/sayiir/sayiir) durable workflow engine.

## Overview

Provides [`PostgresBackend`](https://docs.rs/sayiir-postgres/latest/sayiir_postgres/struct.PostgresBackend.html), a production-grade implementation of `SnapshotStore`, `SignalStore`, and `TaskClaimStore` backed by PostgreSQL via [sqlx](https://crates.io/crates/sqlx).

## Features

- **Codec-generic** — Serialise snapshots with any codec (JSON for debuggability, rkyv/bincode for speed). The data column is always `BYTEA`.
- **ACID transactions** — Composite signal operations use `SELECT … FOR UPDATE` for true atomicity.
- **Snapshot history** — Every checkpoint is appended to an immutable history table for debugging and auditing.
- **Observability-ready** — Indexed metadata columns (`status`, `current_task_id`, `completed_task_count`, `error`, timestamps) plus a denormalised `sayiir_workflow_tasks` table enable monitoring without deserialising blobs.
- **Distributed task claiming** — TTL-based claims with expired-claim replacement and soft worker bias.

## Quick Start

```rust
use sayiir_postgres::PostgresBackend;
use sayiir_runtime::serialization::JsonCodec;
use sayiir_persistence::SnapshotStore;
use sayiir_core::snapshot::WorkflowSnapshot;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let backend = PostgresBackend::<JsonCodec>::connect("postgresql://localhost/sayiir").await?;

    let snapshot = WorkflowSnapshot::new("order-123".to_string(), "hash-abc".to_string());
    backend.save_snapshot(&snapshot).await?;

    let loaded = backend.load_snapshot("order-123").await?;
    Ok(())
}
```

## Schema

`PostgresBackend::connect()` runs migrations automatically. The schema consists of:

| Table | Purpose |
|---|---|
| `sayiir_workflows` | Current snapshot per workflow instance |
| `sayiir_workflow_history` | Immutable append-only snapshot history |
| `sayiir_workflow_tasks` | Denormalised task metadata for querying |
| `sayiir_task_claims` | Distributed task claim tracking |
| `sayiir_workflow_events` | Event log for workflow lifecycle |

## PostgreSQL Version Support

Minimum supported version: **PostgreSQL 13**. Integration tests run against both 13 and 17.

## Documentation

Full API docs are available on [docs.rs](https://docs.rs/sayiir-postgres).

## License

MIT