README
¶
Examples
Seven small, self-contained programs that show what
river-workflow can do and how. Each is a single package main
you can read top to bottom and run on its own.
Prerequisites
A reachable Postgres. Point the examples at it with DATABASE_URL (the default is
postgres://localhost:5432/river_dev?sslmode=disable):
export DATABASE_URL="postgres://localhost:5432/river_dev?sslmode=disable"
Each program creates River's tables itself on first run (via rivermigrate),
so you only need an empty database — no separate migration step.
Running
go run ./examples/order-pipeline
go run ./examples/parallel-batch
go run ./examples/trip-booking
go run ./examples/approval
go run ./examples/periodic-poller
go run ./examples/payment-timeout
go run ./examples/durable-store
What each one shows
| Example | Demonstrates |
|---|---|
order-pipeline |
An order-fulfilment saga: reserve → authorize → capture → ship, where each committed step registers a compensation (release, void, refund) that runs in reverse when a later step fails. Business outcomes complete with a status rather than an error; also shows SideEffect and the typed Result. |
parallel-batch |
Fan out over many items in parallel, capped to K at a time with a dedicated queue's MaxWorkers, then fan the results back in. |
trip-booking |
Child workflows run in parallel and a saga: it awaits both legs, then compensates by cancelling whichever booking succeeded when the other leg fails. |
approval |
Durable, human-in-the-loop signals (AwaitSignal / Signal) plus the control API (GetStatus, Cancel). |
periodic-poller |
Durable timers (Sleep) and ContinueAsNew to repeat work on an interval with a flat, bounded history. |
payment-timeout |
Select: wait for whichever comes first — a payment signal or a timeout — and take that branch deterministically (ship if paid, release stock if it expires). |
durable-store |
The opt-in pgstore supplemental store: durable results that outlive River's job retention, push-based Await (no polling), and List. |
The one thing to remember
A workflow function is deterministic — it replays from the top on every
resume. So it contains only orchestration: Execute, Sleep, SideEffect,
ChildWorkflow, AwaitSignal, Select, and plain logic on their results. All real work
and side effects (I/O, the clock, randomness) live in activities. Define an
activity with RegisterActivity — a typed function whose return value is recorded
for you (shown in durable-store) — or, as most examples here
do, a raw River worker that calls river.RecordOutput. Either way the recorded
value is what Future.Get decodes. Every example is commented with this split in
mind.
See ../docs for the full guides.
Directories
¶
| Path | Synopsis |
|---|---|
|
Command approval shows signals (human-in-the-loop) and the control API.
|
Command approval shows signals (human-in-the-loop) and the control API. |
|
Command durable-store shows the opt-in pgstore supplemental store: durable results that outlive River's job retention, push-based Await (no polling), and listing workflows.
|
Command durable-store shows the opt-in pgstore supplemental store: durable results that outlive River's job retention, push-based Await (no polling), and listing workflows. |
|
Command order-pipeline is a realistic order-fulfilment **saga**: the workflow commits a sequence of steps, and if a later step fails it runs a compensation for each committed step, in reverse, to leave the world consistent.
|
Command order-pipeline is a realistic order-fulfilment **saga**: the workflow commits a sequence of steps, and if a later step fails it runs a compensation for each committed step, in reverse, to leave the world consistent. |
|
Command parallel-batch shows how to fan a workflow out over many items that run in parallel, while capping how many run at once.
|
Command parallel-batch shows how to fan a workflow out over many items that run in parallel, while capping how many run at once. |
|
Command payment-timeout shows Select: waiting for whichever of several things happens first — here, a payment signal OR a timeout.
|
Command payment-timeout shows Select: waiting for whichever of several things happens first — here, a payment signal OR a timeout. |
|
Command periodic-poller shows durable timers (Sleep) and ContinueAsNew for a workflow that repeats work on an interval without its history growing.
|
Command periodic-poller shows durable timers (Sleep) and ContinueAsNew for a workflow that repeats work on an interval without its history growing. |
|
Command trip-booking shows child workflows running in parallel and a saga: when one leg of a trip can't be booked, the workflow compensates by cancelling the leg that already succeeded, then completes with a domain result rather than failing.
|
Command trip-booking shows child workflows running in parallel and a saga: when one leg of a trip can't be booked, the workflow compensates by cancelling the leg that already succeeded, then completes with a domain result rather than failing. |