Workflows
Workflows are the core abstraction in Orcher. A workflow is a function that orchestrates a sequence of steps, where each step's result is automatically recorded in a persistent journal. If the workflow is interrupted for any reason — a server crash, a deployment, a network failure — it resumes from the last completed step rather than starting over. The journal ensures that no step is ever executed twice.
In a traditional application, if your server crashes halfway through processing an order — after charging the customer's card but before sending the confirmation email — you're left in an inconsistent state. You have to build retry logic, state tracking, and recovery mechanisms yourself. Workflows eliminate this entire class of problems.
Think of it like a bookmark in a book. Every time you finish a page (a step), the system places a bookmark. If you're interrupted, you pick up exactly where the bookmark is — you don't re-read pages you've already finished.
Key Characteristics
-
Durable — A workflow survives process crashes, server restarts, and network failures. When the workflow resumes, it replays its journal to restore its position, then continues from the next unfinished step. Your code doesn't need to handle recovery — the framework does it for you.
-
Deterministic — Workflow code must produce the same sequence of steps every time it runs with the same inputs. This is because the replay mechanism re-executes your workflow function from the beginning, using journaled results for completed steps. If your code took a different path on replay (e.g., because of a random number), it would try to apply the wrong journaled result to the wrong step. See the Determinism section for the full set of rules.
-
Automatically Journaled — Every call to
execute_task,sleep,wait_for_event, and other context methods is recorded in PostgreSQL. You don't write any journaling code yourself — it happens transparently whenever you use the workflow context. -
Composable — Workflows can start and wait on other workflows, creating parent-child relationships. A parent workflow that starts a child workflow gets back the child's result, and the parent-child relationship is itself journaled. This lets you break complex processes into reusable pieces.
-
Resumable — When a workflow calls
sleeporwait_for_event, it releases its worker. The workflow isn't holding a thread or a connection while waiting — it's fully suspended. When the timer fires or the event arrives, the server re-dispatches the workflow to any available worker, which replays the journal and continues.
Explore Workflows
Getting Started
Write your first workflow, understand the execution model, and learn the workflow context API.
Determinism Rules
Understand what is safe and unsafe in workflow code, and why determinism matters for replay.
Patterns
Sequential, parallel, conditional, loop, and error handling patterns for workflows.
Lifecycle
Workflow versioning, lifecycle states, and querying workflows from external code.
Best Practices
Guidelines for writing maintainable, reliable, and performant workflows.