sayiir-postgres

PostgreSQL persistence backend for the Sayiir durable workflow engine.

Overview

Provides PostgresBackend, a production-grade implementation of SnapshotStore, SignalStore, and TaskClaimStore backed by PostgreSQL via 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

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:

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.

License

MIT