Module rollback 

Undo a run (#706): the shared types behind faucet rollback.

A run that should not have happened — a wrong parameter, a corrupt upstream extract, a bad deploy — is reverted by the sink that wrote it, one dataset at a time, through the defaulted Sink::rollback_run hook. What “revert” means depends on how the run wrote:

• append — delete the rows stamped with the run id (the _faucet_run_id metadata column, which the rollback: block turns on);
• upsert / delete — deleting is not enough, because the run overwrote older values; with the opt-in before-image journal (RUN_JOURNAL_TABLE) the sink recorded the prior row of every key it changed, in the same transaction as the page, and rollback restores it;
• overwrite — with keep_previous, the replaced table is kept as <table>__faucet_prev (PREVIOUS_TABLE_SUFFIX) and rollback swaps it back.

The pipeline’s state bookmark and exactly-once commit token are rewound by the CLI from the pre-run marker it recorded, so the next run re-reads what the reverted run consumed. Everything here is pure data; the sinks and the CLI carry the I/O.

Structs

JournalEntry

One journaled key, decoded: the key object and its before-image (None when the key did not exist before the run).

JournalSql

Dialect-neutral SQL for the before-image journal and the run-scoped delete.

RollbackOptions

What a sink is asked to undo.

RollbackOutcome

What a sink did (or would do) for one dataset.

RollbackWriteSpec

Runtime rollback settings the executor hands a sink through its WriteSpec (rollback: field). Not user config: the top-level rollback: block decides these, and the CLI injects them per invocation.

Enums

RollbackMode

How the run being rolled back wrote, which decides the undo strategy.

Constants

DEFAULT_RUN_ID_COLUMN

Default name of the run-id column rollback keys on ({metadata prefix}_{run_id} with the default prefix).

KEY_COLUMN_TEXT

The key_json definition for dialects that can index the text directly.

PREVIOUS_TABLE_SUFFIX

Suffix of the table an overwrite run keeps its replaced contents in when keep_previous is on.

PRIMARY_KEY_TEXT

The primary key over the JSON text itself.

RUN_JOURNAL_TABLE

The before-image journal table a journaling sink maintains next to its data tables: (run_id, table_name, key_json, before_json); a NULL before-image means the key did not exist before the run.

Functions

canonical_key

A key tuple with every scalar rendered as its text form, so a key read back from the database (7) and the same key in a source record ("7") journal identically. Nulls stay null; the SQL sinks bind the text through the key column’s own type, so the restore addresses the right row.

key_json

The canonical JSON text of a key tuple — the journal’s row identity. Columns are emitted in the configured key order, so the same key always serialises identically.

plan_keys

Every key a planned page touches — upserts and deletes — as canonical tuples, deduplicated, in page order. What a sink journals before it applies the plan.

plan_restore

restorable

Split journal entries into what a restore does: keys to delete (the run created them) and before-images to write back (the run changed or deleted them). Pure. Journaled keys whose undo would re-insert a before-image. When a later run wrote the dataset, each of these that no longer has a row is a conflict (see RollbackOptions::later_runs).

touched_later

The restorable entries whose key a later run also journaled (later_keys holds that run’s key_json texts, from JournalSql::later_keys). Only such a key’s missing row was deleted by a later run; a key the undone run deleted itself is not among them, so restoring it is the undo, not a conflict.