A Rust library for durable job execution and workflow orchestration. Postgres is the runtime — and the ledger.
Every claim, every retry, every step is posted transactionally to a table you already own. No queue server. No external state machine. No vendor. The schema you can grep is the schema that runs.
Each row is one workflow step, written in the same transaction as the work it represents. There is no separate queue process. There is no in-memory state. The table you'd SELECT * FROM is the table that runs.
ORDER BY.
Workflows are DAGs of steps. Each step names a job handler and declares its dependencies. Validation — cycles, blank keys, non-positive timeouts, missing job types — runs at enqueue, not at runtime.
Four steps. fetch feeds validate; validate gates charge; notify closes the loop. Each carries its own retry and timeout policy.
invoice_id. Retrying the enqueue is a no-op.WorkflowBuildError is an exhaustive enum. Match it. Log it.use runledger::prelude::*; async fn enqueue_invoice( pool: &PgPool, invoice_id: Uuid,) -> Result<WorkflowRunId, WorkflowBuildError> { let workflow = WorkflowBuilder::new("invoice.process") .idempotency_key(invoice_id.to_string()) .step("fetch") .job("invoice.fetch") .max_attempts(3) .timeout_seconds(30) .step("validate") .after("fetch") .job("invoice.validate") .step("charge") .after("validate") .job("invoice.charge") .max_attempts(5) .timeout_seconds(15) .step("notify") .after("charge") .external() // awaits webhook / approval .build()?; // validates the DAG, then writes the run + steps // in a single transaction. returns the run id. runledger_postgres::enqueue_workflow(pool, workflow).await}
Runledger is not a framework; it is a small, opinionated library that makes a small set of strong promises. Each one is a column in the ledger and a line in the test suite.
No Redis. No Kafka. No external orchestrator. Your database holds the queue, the schedules, the workflow state, the hooks, and the audit log — in tables you already know how to back up.
$ psql -c 'SELECT * FROM runledger.jobs LIMIT 5;'
Cycles, dangling dependencies, blank step keys, non-positive timeouts — caught at build(), before a worker picks up the first step. Exhaustive error enums, not strings.
WorkflowBuildError::Cycle { step_keys: [..] }
Every workflow run carries an idempotency key. Retrying the enqueue is a no-op. Replaying a step is a no-op. The runtime treats your handlers as if they will be called twice — because, eventually, they will be.
.idempotency_key(invoice.id)
Lock ordering is enforced across the cancel, reap, and step-completion paths. The chaos test suite proves that you cannot deadlock the runtime by racing cancellation against completion.
tests/workflow_cancel_lock_order.rs
Subscribe to lifecycle events — enqueued, started, succeeded, failed, cancelled — with ordinary functions. No inheritance, no trait gymnastics, no surprise reflection.
.on_step_failed(|ctx, err| async { .. })
Runledger is three crates that compile into your existing service. You bring the handlers, the process bootstrap, the auth. It brings worker, scheduler, reaper, and a durable schema.
[dependencies]
runledger-runtime = "0.1"
Your application enqueues. Workers claim and execute. The scheduler materializes cron rows. The reaper cleans up after orphans. All four meet in one place — the ledger.
FOR UPDATE SKIP LOCKED, runs your handler, heartbeats, retries.
next_run_at.
Constraints, written down once. Runledger is small on purpose — a smaller surface area is the most reliable kind of reliability.
runledger-server, and there never will be.SELECT. To debug a stuck job, write SELECT. The query layer is the one you already use.tokio, no async-std, no I/O. Persistence and execution are in separate crates so you can swap, fork, or replace them.enum. Match on it. Log it structurally. Alert on the variants that matter, not on substrings.BEGIN. Roll back, and nothing was queued. Commit, and the work is in the ledger. There is no separate broker to fall out of sync.$ cargo add runledger-core \ runledger-postgres \ runledger-runtime # apply the schema (one migration) $ sqlx migrate run \ --source migrations/ # register a handler and start a worker $ cargo run --bin my-service