Stateful Cursor

The cursor persists the pipeline’s position so it survives restarts. Without it, a restart makes Oura start over from its configured intersect point.

Why it matters

Some use-cases — like building a stateful view of the chain — can’t tolerate gaps. If Oura starts from the chain Tip, a restart could miss the blocks produced during bootstrap. You could work around this by always starting from a fixed point and re-processing (safe if your sink is idempotent), but if that point is far back, catching up can take hours.

The cursor solves this directly: the sink stage reports its position as it works, and at a regular interval that position is saved to a backend. On restart, Oura loads the saved position and resumes the source from there.

Configuration

Add a top-level [cursor] section to enable the feature, and pick a backend with type:

Keeps the cursor in memory only — the position is not persisted across restarts. This is the default when no [cursor] section is present, and takes no extra fields.

[cursor]
type = "Memory"

Stores the cursor in a JSON file on the local file system.

[cursor]
type = "File"
path = "./cursor.json"
max_breadcrumbs = 10
flush_interval = 10

path (optional, default = ./cursor.json): where the cursor file lives, relative to the working directory.
max_breadcrumbs (optional, default = 10): how many recent positions to retain, used to recover across rollbacks.
flush_interval (optional, default = 10): how often, in seconds, the position is written to disk.

Stores the cursor in a Redis instance — handy when running multiple environments or ephemeral containers.

[cursor]
type = "Redis"
url = "redis://localhost:6379"
key = "oura-cursor"
max_breadcrumbs = 10
flush_interval = 10

url (required): the Redis connection URL.
key (required): the Redis key the cursor state is stored under.
max_breadcrumbs (optional, default = 10): how many recent positions to retain.
flush_interval (optional, default = 10): how often, in seconds, the position is flushed to Redis.