retrofit

Getting started

Mon, 01 Jan 0001 00:00:00 +0000

Getting started

A 5-minute walkthrough: install retrofit, build (or bootstrap) a small schema, look at the oplog file you just created, and emit DDL.

There are two ways to start an oplog:

From scratch: register a schema and append operators by hand, one DDL change at a time. Best when you’re designing a new schema or learning retrofit. Jump to Track A.
From an existing .sql file: bootstrap an oplog from hand-written DDL or a pg_dump --schema-only. import walks the SQL, mints equivalent operators, and gives you an oplog you can evolve from there. Jump to Track B.

The two tracks share init, snapshot, and op seal; only the middle differs.

Concepts

Mon, 01 Jan 0001 00:00:00 +0000

Concepts

The mental model behind retrofit.

For installation and a hello-world session see getting-started.md. For the rules retrofit upholds see principles.md.

The premise

A traditional migration tool manages what the schema is. You hand-write DDL, the tool tracks which scripts have run, and the production schema is the sum of those scripts.

What retrofit manages is how the schema changes. You don’t write DDL. You record semantic operations (rename this column, cast this type, extract this wide table into two narrower ones) and retrofit materializes the SQL.

Principles

Mon, 01 Jan 0001 00:00:00 +0000

Principles

The rules retrofit upholds. They explain why the tool behaves the way it does, and why a few things you might expect to be configurable aren’t.

Each is enforced in code, tests or review.

For the mental model the principles act on, see concepts.md. For a hands-on tour see getting-started.md.

1. Rows in the target database are the asset

The tool emits schema changes for live databases, whose rows have to survive the change. Four things follow.

import

Mon, 01 Jan 0001 00:00:00 +0000

import

retrofit import bootstraps an oplog from one or more .sql files. It walks the DDL in retrofit’s vocabulary and appends the equivalent op add calls to a fresh (or extended) oplog.

Read concepts.md first for the oplog / cut / element identity vocabulary. This doc covers what import sees, what it produces, what it cannot produce, and why.

Usage

Pass one or more <source> paths (or - for stdin). Schema selection follows the six-step resolver chain: pass --schema <name> explicitly, or rely on [directory_scope] / implicit oplog-dir / default_schema.

drift

Mon, 01 Jan 0001 00:00:00 +0000

drift

retrofit drift reads a schema dump, typically pg_dump --schema-only, though any DDL that re-creates the schema’s current shape will do. It infers what changed since the oplog’s head and appends the ops that bring the oplog to that shape, asking a question where a change has more than one reading. Under --dry-run it reports those ops and writes nothing.

Read concepts.md first for the oplog / cut / element identity vocabulary.

snapshot

Mon, 01 Jan 0001 00:00:00 +0000

snapshot

retrofit snapshot emits canonical DDL for the materialized schema: the SQL equivalent of replaying your oplog forward to a cut. The output is intended to be pg_dump --schema-only parity-shaped (see pg_dump-parity.md for the option-by-option audit).

Read concepts.md first for the oplog / cut / replay vocabulary. This doc covers what snapshot sees, what it produces, what it cannot produce, and why.

What snapshot sees

One genealogy cut: the state of the schema after replaying ops up to --at <opid> (default: last). --at also accepts the canonical anchors root / last / seal, each with an optional ^ / ~N decrement (always older). --at root refuses cleanly (opid-not-found, exit 2): the empty pre-genesis cut has no live elements to render.

migrate

Mon, 01 Jan 0001 00:00:00 +0000

migrate

retrofit migrate emits a migration script between two cuts. Where snapshot emits the post-state of one cut, migrate emits the DDL that transitions one cut to another: forward by default, or the reverse with --down. Its output is the script a CI/CD pipeline applies to a live database.

Read concepts.md first for the oplog / cut vocabulary and snapshot.md for the post-state-emission cousin. This doc covers what migrate sees, what it produces, what it refuses, and why.

data

Mon, 01 Jan 0001 00:00:00 +0000

`retrofit data`: the data corpus

The data verb group works on the data corpus: every addressed *.data.<format> data file under a schema’s declared data_root (written as .data.sql; legacy *.dml.sql files are still read). Data files carry row data (reference tables, fixtures, migration backfills) beside the DDL history the oplog carries, and the emit verbs (snapshot, migrate) fold them into a data band at emit time.

Verb	What it does
`data list`	Show the fold the emit verbs would apply. Read-only.
`data capture`	Capture observed rows from an INSERT-style dump.
`data retire`	Withdraw one table’s data chain at the current head.
`data scaffold`	Mint a data file for a table holding one inert placeholder record to fill.
`data check`	Validate the corpus against the data-file grammar.
`data witness`	Bind reference records’ bytes to the oplog.
`data repin`	Re-point an orphaned data file’s `anchor-op=` at an opid you name.
`schema ref-tables`	Read or edit which tables hold reference data.

`retrofit data list`

data list is the consumer-side dry run of the data band. It answers “what would snapshot / migrate actually apply?” over the same fold those verbs read, and it emits no SQL and writes nothing.

retrofit

Mon, 01 Jan 0001 00:00:00 +0000

`retrofit`

Schema evolution CLI: an append-only oplog of DDL operators that
materializes into canonical SQL.

Bootstrap a new project:

 retrofit init # write retrofit.toml + .gitattributes
 retrofit schema create users # register a schema and create its oplog
 retrofit op add CreateTable people # author your first op
 retrofit snapshot # emit canonical DDL

Bootstrap from an existing schema:

 retrofit init
 retrofit import path/to/source.sql --schema users # lazy-creates if unregistered

Run any subcommand with --help for its flags, or --help-all for its
extended reference. `retrofit help --all` prints the full reference for
every command at once.

Usage:
 retrofit [command]

Available Commands:
 completion Generate the autocompletion script for the specified shell
 data Work with the data corpus
 drift Reconcile an oplog with an out-of-band `.sql`
 help Help about any command
 identify Report which cut a pg_dump --schema-only is at, and how it has diverged
 import Import one or more `.sql` files into an oplog
 init Initialize a new retrofit project
 migrate Emit a one-way migration script between two cuts
 op Edit the oplog
 ops Run bulk maintenance over the oplog
 reconcile Close concurrent forks in the oplog by rebasing onto a linear tail
 schema Manage registered schemas
 snapshot Emit canonical DDL for the materialized schema
 validate Validate retrofit.toml, project layout, and the oplog

Flags:
 --as string output mode: text | json (default "text")
 -C, --chdir string treat <dir> as the working directory for the entire run
 --config string retrofit.toml path (overrides discovery; also accepts $RETROFIT_CONFIG)
 -f, --file string oplog file path; selects a registered [[schema]] path (overrides discovery)
 -h, --help help for retrofit
 --help-all show extended help (vocabulary, semantics, caveats)
 --no-consolidate render every advisory occurrence instead of collapsing repeats
 -q, --quiet count suppress the advisory tier on stderr; stack (-qq) to drop it whole (errors and results still print)
 -v, --verbose reveal info-tier advisories on stderr
 --version version for retrofit

Use "retrofit [command] --help" for more information about a command.

Docs: https://docs.retrofit.sh/current/

retrofit --help-all adds:

retrofit data

Mon, 01 Jan 0001 00:00:00 +0000

`retrofit data`

Work with the data corpus

Usage:
 retrofit data
 retrofit data [command]

Available Commands:
 capture Capture a dump's observed rows onto the data corpus
 check Check data-corpus files against the data-file grammar
 list List the data fold the emit verbs would apply
 repin Re-point one corpus data file's anchor-op at an opid you name
 retire Withdraw a data chain by name, minting an empty floor at the head
 scaffold Mint an empty data-corpus file carrying declared metadata axes
 witness Witness reference-data records: bind their bytes to the oplog

Flags:
 -h, --help help for data
 --help-all show extended help (vocabulary, semantics, caveats)

Global Flags:
 --as string output mode: text | json (default "text")
 -C, --chdir string treat <dir> as the working directory for the entire run
 --config string retrofit.toml path (overrides discovery; also accepts $RETROFIT_CONFIG)
 -f, --file string oplog file path; selects a registered [[schema]] path (overrides discovery)
 --no-consolidate render every advisory occurrence instead of collapsing repeats
 -q, --quiet count suppress the advisory tier on stderr; stack (-qq) to drop it whole (errors and results still print)
 -v, --verbose reveal info-tier advisories on stderr

Use "retrofit data [command] --help" for more information about a command.

Docs: https://docs.retrofit.sh/current/commands/retrofit-data/

retrofit data capture

Mon, 01 Jan 0001 00:00:00 +0000

`retrofit data capture`

Capture a dump's observed rows onto the data corpus.

The verb records what the source's rows are at the current head, never what
changed. Tables declared reference data (`retrofit schema ref-tables add`,
or `--ref` on `import`/`drift`) capture on the `ref` band;
`--label` enables the `seed` band for the rest. A table no declaration and no
label claims is LISTED, not captured, and the run exits 0.

`--from-label <l>` takes the corpus as the source instead of a file: it folds
the label's `seed` chain for each selected declared table at the current head
and captures it on the `ref` band.

Use `retrofit import` for a source that states a CHANGE, and
`retrofit data retire` to withdraw a table by name.

Usage:
 retrofit data capture <source> [flags]

Flags:
 --data-root data_root root that overrides the schema's data_root
 --dry-run classify and report without writing anything
 --extra-seed-path seed_paths root that appends to the declared seed_paths
 --from-label <label> capture <label>'s seed fold at HEAD onto the ref band (the corpus is the source; no operand)
 -h, --help help for capture
 --help-all show extended help (vocabulary, semantics, caveats)
 --label <label> repeatable cohort <label>; enables the seed band for unclaimed tables
 --schema <name> registered schema <name> (resolves via the chain when omitted)
 --seed-path seed_paths root that replaces the declared seed_paths
 --skip-manifest <path> write the skip manifest to <path> as JSONL
 --table <pattern> repeatable source <pattern> filter (bare relname or glob)

Global Flags:
 --as string output mode: text | json (default "text")
 -C, --chdir string treat <dir> as the working directory for the entire run
 --config string retrofit.toml path (overrides discovery; also accepts $RETROFIT_CONFIG)
 -f, --file string oplog file path; selects a registered [[schema]] path (overrides discovery)
 --no-consolidate render every advisory occurrence instead of collapsing repeats
 -q, --quiet count suppress the advisory tier on stderr; stack (-qq) to drop it whole (errors and results still print)
 -v, --verbose reveal info-tier advisories on stderr

Docs: https://docs.retrofit.sh/current/commands/retrofit-data-capture/

retrofit data check

Mon, 01 Jan 0001 00:00:00 +0000

`retrofit data check`

Check data-corpus files against the data-file grammar.

Runs every file-level legality predicate over the working tree, emits no SQL
and mints nothing. Reports all findings in one envelope and exits non-zero when
any file is refused.

With no operands it walks the configured corpus root. Operands narrow the walk;
they do not enable it. A named directory is walked; a named file is checked by
the naming itself.

Usage:
 retrofit data check [path...] [flags]

Flags:
 --data-root data_root root that overrides the schema's data_root
 -h, --help help for check
 --help-all show extended help (vocabulary, semantics, caveats)
 --schema <name> registered schema <name> (resolves via the chain when omitted)

Global Flags:
 --as string output mode: text | json (default "text")
 -C, --chdir string treat <dir> as the working directory for the entire run
 --config string retrofit.toml path (overrides discovery; also accepts $RETROFIT_CONFIG)
 -f, --file string oplog file path; selects a registered [[schema]] path (overrides discovery)
 --no-consolidate render every advisory occurrence instead of collapsing repeats
 -q, --quiet count suppress the advisory tier on stderr; stack (-qq) to drop it whole (errors and results still print)
 -v, --verbose reveal info-tier advisories on stderr

Docs: https://docs.retrofit.sh/current/commands/retrofit-data-check/

retrofit data list

Mon, 01 Jan 0001 00:00:00 +0000

`retrofit data list`

List the data fold the emit verbs would apply.

Read-only: it emits no SQL and mints nothing. With no --label it renders the
reference fold plus an inventory of the labels the corpus carries; naming
labels renders the fold those layers produce, in argv order.

Run with --help-all for what each field of an item line means.

Usage:
 retrofit data list [flags]

Flags:
 --at <cut> render point <cut>: an opid prefix or root/last/seal anchor, optionally with ^ or ~N (default: last)
 --data-root data_root root that overrides the schema's data_root
 --extra-seed-path seed_paths root that appends to the declared seed_paths
 -h, --help help for list
 --help-all show extended help (vocabulary, semantics, caveats)
 --label <label> apply the dataset carrying this exact <label> (repeatable; argv order is layer order; byte-exact)
 --schema <name> registered schema <name> (resolves via the chain when omitted)
 --seed-path seed_paths root that replaces the declared seed_paths

Global Flags:
 --as string output mode: text | json (default "text")
 -C, --chdir string treat <dir> as the working directory for the entire run
 --config string retrofit.toml path (overrides discovery; also accepts $RETROFIT_CONFIG)
 -f, --file string oplog file path; selects a registered [[schema]] path (overrides discovery)
 --no-consolidate render every advisory occurrence instead of collapsing repeats
 -q, --quiet count suppress the advisory tier on stderr; stack (-qq) to drop it whole (errors and results still print)
 -v, --verbose reveal info-tier advisories on stderr

Docs: https://docs.retrofit.sh/current/commands/retrofit-data-list/

retrofit data list --help-all adds:

retrofit data repin

Mon, 01 Jan 0001 00:00:00 +0000

`retrofit data repin`

Re-point one corpus data file's anchor-op at an opid you name.

The recourse of `data-file-anchor-unresolved`: an anchor names an opid
exactly, so when revising an op's content or removing the op drops that opid
from the oplog, a data file anchored on it is orphaned and this verb re-points
the file. One invocation re-pins every record in that file.

Only an orphaned file is eligible. A file whose anchor still resolves is
history-bound at a live op, and moving it is a relocation rather than a
repair; capture the rows at the new point instead.

The target is required: pass the opid, an anchor ref (`last`,
`seal`, each with optional `^`/`~N`) or a 1-12 hex opid prefix.
The resolved 12-hex opid is what is written; the literal spelling never is.

A re-pinned record that carried a witness is re-witnessed: one
WitnessReferenceData entry is appended at the new anchor, over the rewritten
bytes. An unwitnessed record stays unwitnessed; --dry-run appends nothing.

Usage:
 retrofit data repin <file> [flags]

Flags:
 --anchor-op <target> the <target> opid to re-pin on: an opid, an anchor ref (`last`, `seal`, with `^`/`~N`) or a 1-12 hex prefix
 --data-root data_root root that overrides the schema's data_root
 --dry-run rehearse the re-pin without writing
 -h, --help help for repin
 --help-all show extended help (vocabulary, semantics, caveats)

Global Flags:
 --as string output mode: text | json (default "text")
 -C, --chdir string treat <dir> as the working directory for the entire run
 --config string retrofit.toml path (overrides discovery; also accepts $RETROFIT_CONFIG)
 -f, --file string oplog file path; selects a registered [[schema]] path (overrides discovery)
 --no-consolidate render every advisory occurrence instead of collapsing repeats
 -q, --quiet count suppress the advisory tier on stderr; stack (-qq) to drop it whole (errors and results still print)
 -v, --verbose reveal info-tier advisories on stderr

Docs: https://docs.retrofit.sh/current/commands/retrofit-data-repin/

retrofit data retire

Mon, 01 Jan 0001 00:00:00 +0000

`retrofit data retire`

Withdraw a data chain by name, minting an empty floor at the head.

A retire is a DECLARED withdrawal: it states that a table's dataset no longer
applies, at the current head. Silence never withdraws anything: a source that
simply omits a table leaves that table untouched, so this verb is how an
emptied production table leaves the corpus.

With no `--label` it addresses the table's unlabelled reference chain; one
or more labels address the seed chain carrying exactly that label set.

A reference table's rows stop being managed when its declaration ends
(`retrofit schema ref-tables remove`): an unlabelled retire of a declared table
refuses, and one of a table no longer declared mints nothing.

Usage:
 retrofit data retire <schema.table> [flags]

Flags:
 --data-root data_root root that overrides the schema's data_root
 --dry-run rehearse the withdrawal without writing
 --extra-seed-path seed_paths root that appends to the declared seed_paths
 -h, --help help for retire
 --help-all show extended help (vocabulary, semantics, caveats)
 --label <label> repeatable <label>; addresses the seed chain with exactly this label set
 --seed-path seed_paths root that replaces the declared seed_paths
 --skip-manifest <path> write the skip manifest to <path> as JSONL

Global Flags:
 --as string output mode: text | json (default "text")
 -C, --chdir string treat <dir> as the working directory for the entire run
 --config string retrofit.toml path (overrides discovery; also accepts $RETROFIT_CONFIG)
 -f, --file string oplog file path; selects a registered [[schema]] path (overrides discovery)
 --no-consolidate render every advisory occurrence instead of collapsing repeats
 -q, --quiet count suppress the advisory tier on stderr; stack (-qq) to drop it whole (errors and results still print)
 -v, --verbose reveal info-tier advisories on stderr

Docs: https://docs.retrofit.sh/current/commands/retrofit-data-retire/

retrofit data scaffold

Mon, 01 Jan 0001 00:00:00 +0000

`retrofit data scaffold`

Mint an empty data-corpus file carrying declared metadata axes.

The minted file holds a v1 header, one section header carrying the axes you
declare, guidance comments showing the record form, and the section-end
marker. It parses to zero records, so every reader treats it as empty until
you hand-author statements into the section.

The path is derived, not given: the file lands under the target
schema's declared `data_root` at the deterministic path for its mint key.

Usage:
 retrofit data scaffold [flags]

Flags:
 --anchor-op string 12-hex op id the scaffolded records anchor on (default: the reconciled head)
 --disposition <append|restate> declared disposition <append|restate> (omitted: no disposition token)
 -h, --help help for scaffold
 --help-all show extended help (vocabulary, semantics, caveats)
 --label <label> repeatable declared cohort <label> (the axis is a set; canonicalized on emit)
 --purpose <transition|cleanse> declared purpose <transition|cleanse> (exclusive with --label, which resolves seed)
 --schema <name> registered schema <name> (resolves via the chain when omitted)
 --table <schema>.<table> the schema-qualified table this file declares, <schema>.<table> (required)

Global Flags:
 --as string output mode: text | json (default "text")
 -C, --chdir string treat <dir> as the working directory for the entire run
 --config string retrofit.toml path (overrides discovery; also accepts $RETROFIT_CONFIG)
 -f, --file string oplog file path; selects a registered [[schema]] path (overrides discovery)
 --no-consolidate render every advisory occurrence instead of collapsing repeats
 -q, --quiet count suppress the advisory tier on stderr; stack (-qq) to drop it whole (errors and results still print)
 -v, --verbose reveal info-tier advisories on stderr

Docs: https://docs.retrofit.sh/current/commands/retrofit-data-scaffold/

retrofit data witness

Mon, 01 Jan 0001 00:00:00 +0000

`retrofit data witness`

Witness reference-data records: bind their bytes to the oplog.

The verb appends one WitnessReferenceData entry per selected record,
carrying the record's digest over every file at its key
{table, label-set, anchor}. A witnessed record whose anchor a seal covers is
verified by validate, op seal, migrate and snapshot.

With no operands it selects every purpose=ref record under data_root whose
anchor is in the unsealed tail and which has no witness at its current bytes.
Operands name record files; a directory is refused. A named record outside the
selection is refused (witness-band, sealed-anchor); one already witnessed at
its current bytes is reported already-witnessed.

--dry-run renders the same rows and appends nothing.

Usage:
 retrofit data witness [path...] [flags]

Flags:
 --dry-run render the rows the run would produce and append nothing
 -h, --help help for witness
 --help-all show extended help (vocabulary, semantics, caveats)
 --schema <name> registered schema <name> (resolves via the chain when omitted)

Global Flags:
 --as string output mode: text | json (default "text")
 -C, --chdir string treat <dir> as the working directory for the entire run
 --config string retrofit.toml path (overrides discovery; also accepts $RETROFIT_CONFIG)
 -f, --file string oplog file path; selects a registered [[schema]] path (overrides discovery)
 --no-consolidate render every advisory occurrence instead of collapsing repeats
 -q, --quiet count suppress the advisory tier on stderr; stack (-qq) to drop it whole (errors and results still print)
 -v, --verbose reveal info-tier advisories on stderr

Docs: https://docs.retrofit.sh/current/commands/retrofit-data-witness/

retrofit drift

Mon, 01 Jan 0001 00:00:00 +0000

`retrofit drift`

Reconcile an oplog with an out-of-band .sql capture.

drift parses <source>, diffs it against the current cut of <schema-name>'s
unsealed tail, and either appends the SMO sequence that brings the oplog
to the target (default) or reports it (--dry-run).

Reference data: the tables declared at the new head are converged in the
same run, with no flag. Each one whose rows differ from its chain is
captured into the data corpus (one file per changed table,
disposition=replace body=data); see --help-all.

Usage:
 retrofit drift <source> [--schema <name>] [flags]

Flags:
 --allow-capability-gaps accept skips that drop content retrofit has no operator for (exit 0 instead of exit 2; the drift-run-summary record is byte-identical either way)
 --data-root data_root root that overrides the schema's data_root
 --dry-run parse, diff, and emit the report; never open the editor; never write the oplog
 --extra-seed-path seed_paths root that appends to the declared seed_paths
 -h, --help help for drift
 --help-all show extended help (vocabulary, semantics, caveats)
 --ignore-drops string[="*"] suppress Drop op authoring; bare = all kinds, or CSV of: table, column, index, view, materialized-view, constraint, foreign-key, primary-key, not-null, identity, schema (suppressed drops still surface as deferred-drop events)
 -i, --interactive open the editor even when there are no questions
 --on-question string question policy for unattended runs: error|editor|skip (default: editor when $EDITOR or $VISUAL is set, else refuse)
 --ref <table> declare <table> reference data (repeatable): a CreateTable this run mints is written reference_data=true; a table live at the run's starting cut gets SetReferenceData(value=true) appended after the run's DDL ops
 --schema <name> registered schema <name> (resolves via the chain when omitted)
 --seal --seal=<text> append a Seal op covering drift's new tail (bare flag auto-derives reason from source basename; --seal=<text> overrides); refused as `op seal` refuses when the range holds an unwitnessed reference record
 --seed-path seed_paths root that replaces the declared seed_paths
 --show string report-side filter on the live event stream: both|additions|removals (presentation-only; writes proceed for both directions) (default "both")
 --skip-manifest <path> write the reference capture's skip manifest to <path> as JSONL
 --table <pattern> repeatable source <pattern> narrowing the reference capture (bare relname or glob)

Global Flags:
 --as string output mode: text | json (default "text")
 -C, --chdir string treat <dir> as the working directory for the entire run
 --config string retrofit.toml path (overrides discovery; also accepts $RETROFIT_CONFIG)
 -f, --file string oplog file path; selects a registered [[schema]] path (overrides discovery)
 --no-consolidate render every advisory occurrence instead of collapsing repeats
 -q, --quiet count suppress the advisory tier on stderr; stack (-qq) to drop it whole (errors and results still print)
 -v, --verbose reveal info-tier advisories on stderr

Docs: https://docs.retrofit.sh/current/commands/retrofit-drift/

retrofit drift --help-all adds:

retrofit identify

Mon, 01 Jan 0001 00:00:00 +0000

`retrofit identify`

Report which cut a pg_dump --schema-only is at, and how it has diverged

Usage:
 retrofit identify <dump> [flags]

Flags:
 --expect last assert the dump is at this cut: opid prefix or anchor (last/`seal`, optional `^`/`~N`); refuse `expect-mismatch` when it resolves elsewhere
 -h, --help help for identify
 --help-all show extended help (vocabulary, semantics, caveats)
 --schema <name> registered schema <name> (resolves via the chain when omitted)

Global Flags:
 --as string output mode: text | json (default "text")
 -C, --chdir string treat <dir> as the working directory for the entire run
 --config string retrofit.toml path (overrides discovery; also accepts $RETROFIT_CONFIG)
 -f, --file string oplog file path; selects a registered [[schema]] path (overrides discovery)
 --no-consolidate render every advisory occurrence instead of collapsing repeats
 -q, --quiet count suppress the advisory tier on stderr; stack (-qq) to drop it whole (errors and results still print)
 -v, --verbose reveal info-tier advisories on stderr

Docs: https://docs.retrofit.sh/current/commands/retrofit-identify/

retrofit import

Mon, 01 Jan 0001 00:00:00 +0000

`retrofit import`

Import one or more .sql files into an oplog. Walks DDL in
retrofit's vocabulary and appends the equivalent op-add calls. A missing
schema is registered lazily, a populated oplog is extended by default, and
--force replaces its prior content. DML is set aside in data files; other
statements outside the vocabulary (sequences, GRANT/REVOKE, publications) are
reported on the stdout skip manifest and not recorded.

Source argument: one or more filesystem paths with a `.sql` extension,
or `-` for stdin (one source per invocation when reading stdin). When
multiple sources are passed they are imported as a single batch in
argv order with one validate, one event flush, and one atomic write.

Run with --help-all for the main in-vocabulary statements and walker
semantics.

Usage:
 retrofit import <source>... [--schema <name>] [--from-file <path>] [flags]

Flags:
 --allow-capability-gaps import anyway when capability-gap skips drop content: statements retrofit has no SMO for (exit 0 + warning instead of exit 2; the import-summary record is byte-identical either way); the one carve-out is validation-errors and rule-* refusals, which still abort
 --allow-sealed-rewrite opid [sealed history] attest each Seal this run would demote or replace, by its full opid (repeatable, comma-separated); a value attests the Seal it names and selects nothing, and a Seal left unnamed refuses seal-removal-refused
 --data-root data_root root that overrides the schema's data_root
 --ddl-only decline every preserved-DML statement in the run (authored DML, dump data bands and synthesized floors): nothing is minted, the declined tables are listed, and the run exits on its DDL alone; orthogonal to --allow-capability-gaps, which covers DDL retrofit cannot represent
 --disposition <replace|append> asserted <replace|append> disposition on every preserved-DML record
 --dry-run run the full pipeline without writing the oplog file
 --engine-version <15|16|17|18> supported major <15|16|17|18> for the imported schema (default: project engine_version)
 --extra-seed-path seed_paths root that appends to the declared seed_paths
 --force overwrite an existing populated oplog (mint fresh; a bare import extends instead)
 --from-file <path> newline-delimited <path> listing .sql files (relative to the list's directory; # comments and blank lines ignored)
 -h, --help help for import
 --help-all show extended help (vocabulary, semantics, caveats)
 --label <label> opaque <label> stamped onto every preserved-DML record (repeatable set; key:value accepted, not required)
 --purge-orphaned-corpus consent to remove every corpus record whose anchor no longer exists in the replaced oplog (--force only; a same-anchor re-capture replaces its version in place)
 --purge-superseded remove earlier same-chain data blocks superseded by this ingest (positional supersession within one continuous oplog; the anchor is alive at both positions); never a witnessed record, sealed or in the tail; each is reported kept. Default keeps them as --at render assets
 --purpose <transition|cleanse> asserted <transition|cleanse> purpose on every preserved-DML record (one of: transition, cleanse; name a seed cohort with --label, and declare reference tables with --ref <table> or retrofit schema ref-tables add <table>)
 --ref <table> declare <table> reference data (repeatable): a CreateTable this run mints is written reference_data=true; a table live at the run's starting cut gets SetReferenceData(value=true) appended after the run's DDL ops
 --schema <name> registered schema <name> (lazy-creates when unregistered)
 --seal --seal=<text> append a Seal op after the imported prefix (bare flag auto-derives reason from source(s); --seal=<text> overrides); refused as `op seal` refuses when the range holds an unwitnessed reference record, including one this import mints
 --seal-per-file emit one Seal op after each source that minted ops (sources minting none are not sealed; equivalent to a bare '--seal' import per file)
 --seed-path seed_paths root that replaces the declared seed_paths
 --skip-manifest <path> write one JSONL record per skipped statement to <path> (kind/schema.name/line/raw_stmt_kind/raw_text)
 --summary-file <path> write the aggregate import-summary record to <path> as one JSON object (imported/run_raw_script/skipped/skipped_by_kind[/skipped_by_class][/sealed][/sources_zero_op])

Global Flags:
 --as string output mode: text | json (default "text")
 -C, --chdir string treat <dir> as the working directory for the entire run
 --config string retrofit.toml path (overrides discovery; also accepts $RETROFIT_CONFIG)
 -f, --file string oplog file path; selects a registered [[schema]] path (overrides discovery)
 --no-consolidate render every advisory occurrence instead of collapsing repeats
 -q, --quiet count suppress the advisory tier on stderr; stack (-qq) to drop it whole (errors and results still print)
 -v, --verbose reveal info-tier advisories on stderr

Docs: https://docs.retrofit.sh/current/commands/retrofit-import/

retrofit import --help-all adds:

retrofit init

Mon, 01 Jan 0001 00:00:00 +0000

`retrofit init`

Initialize the current project by writing retrofit.toml at
the repo root and ensuring `.gitattributes` carries the
*.oplog merge=union line and the *.data.sql text eol=lf line
(the latter keeps a checkout rewrite from disturbing data
file line endings). Does not create an oplog (use
`retrofit schema create`).

Usage:
 retrofit init [flags]

Flags:
 --add-search-path append [search_path] section with default schemas = ["public"] when missing (upgrade path for configs written before search_path; idempotent)
 --config string destination retrofit.toml path; a relative path anchors to the current directory, not to --dir (default: <repo-root>/retrofit.toml)
 --dir string working directory for .git discovery only; does not anchor a relative --config
 --engine postgres engine identifier (only postgres accepted) (default "postgres")
 --engine-version <15|16|17|18> supported major <15|16|17|18> (overrides build-time default) (default "17")
 --force overwrite an existing retrofit.toml (init is otherwise idempotent: a second run leaves retrofit.toml alone but still finishes the .gitattributes step)
 -h, --help help for init
 --help-all show extended help (vocabulary, semantics, caveats)
 --no-gitattributes skip .gitattributes mutation entirely

Global Flags:
 --as string output mode: text | json (default "text")
 -C, --chdir string treat <dir> as the working directory for the entire run
 -f, --file string oplog file path; selects a registered [[schema]] path (overrides discovery)
 --no-consolidate render every advisory occurrence instead of collapsing repeats
 -q, --quiet count suppress the advisory tier on stderr; stack (-qq) to drop it whole (errors and results still print)
 -v, --verbose reveal info-tier advisories on stderr

Docs: https://docs.retrofit.sh/current/commands/retrofit-init/

retrofit migrate

Mon, 01 Jan 0001 00:00:00 +0000

`retrofit migrate`

Emit a one-way migration script between two cuts

Usage:
 retrofit migrate [flags]

Flags:
 --allow-external-atomicity [apply context] attest that the apply context owns transaction atomicity: the no-wrapper advisory is not raised where a non-own envelope suppressed the wrapper
 --allow-reading-replace-body downgrade the replace-body-reads-relation refusal to a warning; emit the body verbatim under a WARNING comment, and render its table's prologue as a whole-table clear
 --allow-stale-dml downgrade every stale-DML-reference refusal to a warning; emit the body under a stale-reference WARNING comment. It does NOT cover chain-collision, which is not attestable: two live chains for one element is a fork to resolve by retiring one, and exit 2 stands
 --allow-unclassified-dml downgrade every unclassified-DML refusal to a warning; emit each unclassified body as a trailing unclassified-DML WARNING block
 --allow-unnamed-label stringArray attest that the dataset carrying this exact label is deliberately left unnamed in this run (repeatable; byte-exact, never trimmed); every other unnamed dataset still warns
 --allow-unreached-dml downgrade the dml-anchor-unresolved refusal for a record anchored AFTER --to to a warning; the record is omitted from this script, never emitted out of position. It does NOT cover an anchor the oplog does not hold, which is not attestable: that file needs a re-pin (retrofit data repin), and exit 2 stands
 --allow-unscreened-dml attest set-aside DML whose body carries transaction control or psql meta-command lines (or which retrofit cannot parse): emit it anyway and report the window's segment count as a lower bound rather than an exact number
 --at string requires --down: the cut the database is at, an opid prefix or anchor (default: last); --to beside it rolls back the slice (--from, --to] and keeps the ops after it
 --data-root data_root root that overrides the schema's data_root
 --down emit the reverse of the migration window: each touched element's net transition back to --from, rendered by the forward renderer
 --envelope own transactional context the emitted file is applied in: own (retrofit wraps it in one transaction; apply outside any open transaction) | caller (you open the transaction; retrofit emits no wrapper) | independent (each statement applies in its own implicit transaction); default: own
 --extra-seed-path seed_paths root that appends to the declared seed_paths
 --from root from-opid prefix or anchor (root/`last`/`seal`, optional `^`/`~N`); default: latest Seal, or `root` when no Seal exists
 --from-dump string identify the cut the database is at from a pg_dump --schema-only file; it fills --from (forward) or --at (under --down)
 -h, --help help for migrate
 --help-all show extended help (vocabulary, semantics, caveats)
 --into-schema string emit a copy script into <schema>; absence = in-place
 --label stringArray apply the dataset carrying this exact label (repeatable; argv order is layer order; byte-exact, never trimmed; never cuts ref data)
 --lock-timeout string bound each lock wait (per lock acquisition, row locks included): emit SET LOCAL lock_timeout = '<duration>' at the head of every transaction the file opens (a positive integer with ms, s, min or h, e.g. 2s; off = unset); overrides [project] lock_timeout; refused where the file has no transaction to scope it into
 --no-header suppress engine-version banner
 --schema <name> registered schema <name> (resolves via the chain when omitted)
 --seed-path seed_paths root that replaces the declared seed_paths
 --to root to-opid prefix or anchor (root/`last`/`seal`, optional `^`/`~N`); default: last
 --using string one-shot emit-target override (format: <engine>:<major>)

Global Flags:
 --as string output mode: text | json (default "text")
 -C, --chdir string treat <dir> as the working directory for the entire run
 --config string retrofit.toml path (overrides discovery; also accepts $RETROFIT_CONFIG)
 -f, --file string oplog file path; selects a registered [[schema]] path (overrides discovery)
 --no-consolidate render every advisory occurrence instead of collapsing repeats
 -q, --quiet count suppress the advisory tier on stderr; stack (-qq) to drop it whole (errors and results still print)
 -v, --verbose reveal info-tier advisories on stderr

Docs: https://docs.retrofit.sh/current/commands/retrofit-migrate/

retrofit migrate --help-all adds:

retrofit op

Mon, 01 Jan 0001 00:00:00 +0000

`retrofit op`

Edit the oplog

Usage:
 retrofit op
 retrofit op [command]

Available Commands:
 add Append a new operator instance to the active oplog
 compact Drop the oplog's traces (tombstones, replaces=) to a bound
 info Print an operator's reference entry, or the whole catalog with --dump
 remove Drop one or more unsealed ops from the oplog
 revise Patch bound parameters on an unsealed op
 seal Seal the unsealed tail of the oplog
 show Render ops from the oplog
 truncate Rewind the oplog to a checkpoint by removing a suffix of ops
 unseal Demote the most-recent N Seal record(s), keeping their ops as unsealed tail

Flags:
 -h, --help help for op
 --help-all show extended help (vocabulary, semantics, caveats)
 --schema <name> registered schema <name> (resolves via the chain when omitted)

Global Flags:
 --as string output mode: text | json (default "text")
 -C, --chdir string treat <dir> as the working directory for the entire run
 --config string retrofit.toml path (overrides discovery; also accepts $RETROFIT_CONFIG)
 -f, --file string oplog file path; selects a registered [[schema]] path (overrides discovery)
 --no-consolidate render every advisory occurrence instead of collapsing repeats
 -q, --quiet count suppress the advisory tier on stderr; stack (-qq) to drop it whole (errors and results still print)
 -v, --verbose reveal info-tier advisories on stderr

Use "retrofit op [command] --help" for more information about a command.

Docs: https://docs.retrofit.sh/current/commands/retrofit-op/

retrofit op add

Mon, 01 Jan 0001 00:00:00 +0000

`retrofit op add`

Append a new operator instance to the active oplog.

Each call records one operation (a `DropUnique`, `DropPrimaryKey` or
`ChangePrimaryKey` that retires a `USING INDEX` constraint also records
its companion `DropIndex`).
The full set of appendable operators is enumerated below; pass
`retrofit op add <Operator> --help` for the parameter detail of any
one of them, or `retrofit op add --examples` for a worked CREATE TABLE
recipe.

CreateSchema and Seal are not listed: `retrofit schema create` writes
CreateSchema with its registry entry, and `retrofit op seal` computes
a Seal's range and digest from the unsealed tail.

AddUnique, AddForeignKey, AddPrimaryKey, and AddCheck each require a
non-empty `name=` (the constraint's name); e.g.
`op add AddUnique <table> --column <t.col> name=t_a_b_key`.

`--` ends the verb's own flags (--as, --dry-run, -q, ...); every token
after it is passed to the operator verbatim, so a payload value that
is spelled like a flag can be given as `-- --<param> <value>`.

OPERATORS

 Table operators
 AttachPartition Subordinate a free-standing table as a partition of a partitioned parent (its columns end into the parent's).
 CopyTable Create a new table that is an independent copy of source.
 CreatePartition Create a partition under a partitioned parent (columns inherited).
 CreateTable Create a new table inside the target schema.
 DepartitionTable Flatten a partitioned parent back to a plain heap, tombstoning its partition-children.
 DetachPartition Detach a partition into a free-standing table (rows kept).
 DropTable Consume the target table element.
 ExtractTable Extract columns into new related tables (column-axis split; normalizes a wide table). A child copies the source's primary key, keeping every row's data, or designates `key` columns it shares with the source (the lookup: one child row per distinct key, the source rows with a NULL key component losing their moved values). With a remainder the source survives in place holding the unassigned columns; with every live column assigned the source is consumed.
 InlineTable Inline one or more child tables back into a live table along their primary keys (keyed column fold, folding an extracted child back into its survivor). The survivor keeps its identity; each inlined source's columns reparent onto it and the source is consumed. A survivor row with no inlined row is padded with NULL or the column's default.
 JoinTable Join two tables' columns into one (denormalize; column-axis join along a recorded key pairing). Identity-preserving at the column level: each source column is reparented to the new target with its existing ElementID. Rejects on column-name collision across sources (resolve via prior RenameColumn). The key_pairs are the ordered column pairs the sources are joined on (each side's columns a PRIMARY KEY or UNIQUE of that source); kind picks the JOIN flavor (inner/left/right/full).
 MergeTable Move the rows of several tables into a live table of their shape, one predicate recorded per source (row-axis merge).
 MoveColumn Move a column to another table along a recorded key pairing, keeping its identity and carrying each value to its partner row. The column's ElementID survives the move; only the parent table changes. Renames are a separate SMO.
 PartitionTable Convert a plain table to a partitioned parent in place, minting N partitions atomically. (partition_by ∈ {range, list, hash})
 RenameTable Rename the target table to a new name in its schema.
 SetReferenceData Declare or undeclare the target table as reference data.
 SetReplicaIdentity Set the table's REPLICA IDENTITY mode. mode=using_index requires index=<index>, a unique, immediate, non-partial, column-only index on this table over NOT NULL columns. (mode ∈ {default, nothing, full, using_index})
 SetTableComment Set or clear a table comment. Empty text clears (mirrors PG `COMMENT ON TABLE … IS NULL`).
 SplitTable Move a table's rows into N new tables of its shape by first-match predicate; the source stays (row-axis split).
 UnjoinTable Take a join apart along the keys its sides hold into two new related tables (keyed table unjoin, undoing a join of any kind). Every live column of the source is assigned to exactly one child and the source is consumed; each child keeps its columns' identities. (kind ∈ {inner, left, right, full})

 Column operators
 AddColumn Add a column to an existing table.
 AddIdentity Promote an existing column to GENERATED { BY DEFAULT | ALWAYS } AS IDENTITY. PG mints a fresh backing sequence starting at 1 and does NOT advance it past the column's existing values, so migrate emits a realignment statement after the ALTER; without it the migration applies cleanly and the next insert collides. (generation ∈ {by_default, always})
 AddNotNull Set the column's NOT NULL bit on the column vertex.
 CastColumn Change a column's SQL type in place.
 CopyColumn Duplicate a column on the same parent table: mint a fresh column whose initial values are seeded from an existing source column. Type/default/nullability are inherited from the source unless overridden. The new column is born unconstrained; re-attach PK/FK/UNIQUE/CHECK/index against the new ElementID via separate ops.
 DropColumn Consume the target column element.
 DropDefault Clear a column's DEFAULT expression. Replay rejects against a column with no current default.
 DropGeneratedExpression Clear a stored generated column's expression, converting it to a base column. Replay rejects against a column with no current generated expression or a virtual generated column.
 DropIdentity Remove the identity property from a column. The implicit NOT NULL is preserved; use DropNotNull to clear it.
 DropNotNull Clear the column-vertex NOT NULL bit.
 RenameColumn Rename the target column inside its containing table.
 RenameOwnedSequence Rename the sequence a column owns (its serial or identity sequence) without touching the column.
 SetColumnComment Set or clear a column comment. Empty text clears.
 SetDefault Set or replace a column's DEFAULT expression. Single-slot semantics; overwrites whatever default is in effect.
 SetIdentityGeneration Swap an identity column's generation mode between BY DEFAULT and ALWAYS without dropping the underlying sequence. (generation ∈ {by_default, always})

 Constraint operators
 AddCheck Declare a CHECK constraint enforcing a row-level predicate.
 AddForeignKey Declare a foreign-key constraint to referenced_columns in referenced_table.
 AddPrimaryKey Declare a primary-key constraint over the listed columns.
 AddUnique Declare a UNIQUE constraint over the listed columns.
 ChangePrimaryKey Replace a table's primary key with a new column set; preserves the cascade genealogy across the PK and every dependent FK constraint via N+1 EdgeKindCrossElement edges minted at replay.
 DropCheck Consume the target CHECK constraint.
 DropForeignKey Consume the target foreign-key constraint.
 DropPrimaryKey Consume the target primary-key constraint.
 DropUnique Consume the target UNIQUE constraint.
 RenameConstraint Rename a constraint without dropping it. Element identity is preserved; the first rename of a PG-default-named constraint assigns the first explicit name.
 SetConstraintComment Set or clear a constraint comment. Empty text clears (mirrors PG `COMMENT ON CONSTRAINT … ON … IS NULL`).
 SetConstraintDeferrable Toggle the DEFERRABLE bit on an FK constraint (PG's ALTER CONSTRAINT is FK-only; UNIQUE / PK can be born deferrable via AddUnique / AddPrimaryKey but not toggled post-birth). Replay rejects no-op writes.
 SetConstraintEnforced Toggle the ENFORCED bit on a foreign-key (FK) constraint (PG18+; PostgreSQL alters the enforceability of foreign keys only).
 SetConstraintInherit Toggle the NO INHERIT bit on a NOT NULL constraint (PG18+; PG 18's per-constraint INHERIT / NO INHERIT applies to NOT NULL only). Records lineage only: it emits no DDL, sets no bit and does not check the constraint kind.
 SetConstraintInitiallyDeferred Toggle the INITIALLY DEFERRED bit on an FK constraint (PG's ALTER CONSTRAINT is FK-only; UNIQUE / PK can be born initially-deferred via AddUnique / AddPrimaryKey but not toggled post-birth). Requires the constraint to already be DEFERRABLE; replay rejects no-op writes.
 ValidateConstraint Promote a NOT VALID foreign-key or CHECK constraint to validated.

 Index operators
 CreateIndex Create a physical index over the listed columns.
 DropIndex Consume the target index element.
 RenameIndex Rename the target index inside its containing table.

 View operators
 CreateMaterializedView Create a new materialized view inside the target schema.
 CreateView Create a new view inside the target schema.
 DropMaterializedView Consume the target materialized view element.
 DropView Consume the target view element.
 RenameMaterializedView Rename the target materialized view to a new name in its schema.
 RenameView Rename the target view to a new name in its schema.
 ReplaceMaterializedView Replace the body of an existing materialized view (DROP CASCADE + CREATE realization).
 ReplaceView Replace the body of an existing view (PG superset-only column rule).

 Type operators
 AddEnumValue Append a new value to an existing enum type.
 CreateType Create a user-defined type (enum or composite) in the target schema. (kind ∈ {enum, composite})
 DropType Consume a user-defined type element. Refused at op-add when any live column binds to it.
 RenameEnumValue Rename an existing enum value in place.
 RenameType Rename a user-defined type. Element identity (typeRef) is preserved across the rename.

 Policy operators
 CreatePolicy Create a row-level-security policy on a table. Identity is (table, name).
 DropPolicy Consume the target policy element.
 RenamePolicy Rename a policy within its owning table.
 ReplacePolicy Replace a policy's TO / USING / WITH CHECK. Cannot change permissive or command (those are identity-fixed; use Drop+Create).
 SetRowLevelSecurity Set a table's ROW LEVEL SECURITY enabled/forced facets (absolute {enabled, forced} payload).

 Function operators
 CreateFunction Create a new function inside the target schema. Identity is (schema, composite-name).
 DropFunction Consume the target function element.
 RenameFunction Rename the target function to a new name in its schema.
 ReplaceFunction Replace a function's body and mutable attributes. Signature is identity-fixed by on= and cannot change.
 SetFunctionComment Set or clear a function comment. Empty text clears (mirrors PG `COMMENT ON FUNCTION … IS NULL`).

 Trigger operators
 CreateTrigger Create a trigger on a table or view. Identity is (table, name). (timing ∈ {before, after, instead_of})
 DisableTrigger Disable an enabled trigger.
 DropTrigger Consume the target trigger element.
 EnableTrigger Enable a disabled trigger.
 RenameTrigger Rename the target trigger.

 Raw / escape-hatch operators
 RunRawScript Run-once raw statement sequence with no catalog identity (a DO $$ … $$; anonymous block). Body emitted verbatim at migrate time; an optional reverse_body is what migrate --down emits, verbatim and unchecked; no structural diff target; drift has no synthesis path. The escape hatch below the Structural/Definitional partition.

Usage:
 retrofit op add <operator> [<args>...] [flags]

Flags:
 --dry-run preview the proposed op without writing
 --examples print a worked CREATE TABLE recipe of op add calls
 --explain with --dry-run, accept partial input and report bound vs. missing params
 -h, --help help for add
 --help-all show extended help (vocabulary, semantics, caveats)
 --no-prompt force non-TTY behavior; never prompt

Global Flags:
 --as string output mode: text | json (default "text")
 -C, --chdir string treat <dir> as the working directory for the entire run
 --config string retrofit.toml path (overrides discovery; also accepts $RETROFIT_CONFIG)
 -f, --file string oplog file path; selects a registered [[schema]] path (overrides discovery)
 --no-consolidate render every advisory occurrence instead of collapsing repeats
 -q, --quiet count suppress the advisory tier on stderr; stack (-qq) to drop it whole (errors and results still print)
 --schema <name> registered schema <name> (resolves via the chain when omitted)
 -v, --verbose reveal info-tier advisories on stderr

Docs: https://docs.retrofit.sh/current/commands/retrofit-op-add/

retrofit op compact

Mon, 01 Jan 0001 00:00:00 +0000

`retrofit op compact`

Drop the oplog's traces (tombstoned lines and replaces= entries) to
exactly one bound, rewiring each prev= to its effective value; the render
every verb reads is unchanged.

 --frontier <file> a trace drops only when <file> holds the same trace
 --unshared <file> a trace drops only when <file> holds no line,
 tombstone or replacement of its opid
 --all every trace outside sealed ranges drops

A sealed range compacts only when --seal <opid> names its Seal, to the
bound, without resealing. A file holding no trace to drop is not written.

Usage:
 retrofit op compact [flags]

Flags:
 --all drop every trace outside sealed ranges (the flag is the attestation no open branch holds them)
 --frontier string drop a trace only when this file holds the same trace
 -h, --help help for compact
 --help-all show extended help (vocabulary, semantics, caveats)
 --seal strings also compact the sealed range of each named live Seal, to the bound
 --unshared string drop a trace only when this file holds no line, tombstone or replacement of its opid

Global Flags:
 --as string output mode: text | json (default "text")
 -C, --chdir string treat <dir> as the working directory for the entire run
 --config string retrofit.toml path (overrides discovery; also accepts $RETROFIT_CONFIG)
 -f, --file string oplog file path; selects a registered [[schema]] path (overrides discovery)
 --no-consolidate render every advisory occurrence instead of collapsing repeats
 -q, --quiet count suppress the advisory tier on stderr; stack (-qq) to drop it whole (errors and results still print)
 --schema <name> registered schema <name> (resolves via the chain when omitted)
 -v, --verbose reveal info-tier advisories on stderr

Docs: https://docs.retrofit.sh/current/commands/retrofit-op-compact/

retrofit op info

Mon, 01 Jan 0001 00:00:00 +0000

`retrofit op info`

Reasoned reference documentation for a schema modification operator (SMO).

 retrofit op info <Operator> one operator's reference view
 retrofit op info <Operator> --as json that operator's descriptor as JSON
 retrofit op info --dump human roll-up of all operators
 retrofit op info --dump --as json the {"operators":[...]} document for tooling

For an operator's syntax (usage and positional order), run
`op add <Operator> --help`. The output is plain stdout; pipe it:

 retrofit op info CreateTable | less
 retrofit op info --dump --as json | jq '.operators[].name'

Usage:
 retrofit op info [<operator>] [flags]

Flags:
 --dump marshal every registered operator (bulk / machine path)
 -h, --help help for info
 --help-all show extended help (vocabulary, semantics, caveats)

Global Flags:
 --as string output mode: text | json (default "text")
 -C, --chdir string treat <dir> as the working directory for the entire run
 --config string retrofit.toml path (overrides discovery; also accepts $RETROFIT_CONFIG)
 -f, --file string oplog file path; selects a registered [[schema]] path (overrides discovery)
 --no-consolidate render every advisory occurrence instead of collapsing repeats
 -q, --quiet count suppress the advisory tier on stderr; stack (-qq) to drop it whole (errors and results still print)
 --schema <name> registered schema <name> (resolves via the chain when omitted)
 -v, --verbose reveal info-tier advisories on stderr

Docs: https://docs.retrofit.sh/current/commands/retrofit-op-info/

retrofit op remove

Mon, 01 Jan 0001 00:00:00 +0000

`retrofit op remove`

Drop one or more unsealed ops from the oplog

Usage:
 retrofit op remove <selector> [flags]

Flags:
 --dry-run preview the opids that would be removed without writing
 -h, --help help for remove
 --help-all show extended help (vocabulary, semantics, caveats)

Global Flags:
 --as string output mode: text | json (default "text")
 -C, --chdir string treat <dir> as the working directory for the entire run
 --config string retrofit.toml path (overrides discovery; also accepts $RETROFIT_CONFIG)
 -f, --file string oplog file path; selects a registered [[schema]] path (overrides discovery)
 --no-consolidate render every advisory occurrence instead of collapsing repeats
 -q, --quiet count suppress the advisory tier on stderr; stack (-qq) to drop it whole (errors and results still print)
 --schema <name> registered schema <name> (resolves via the chain when omitted)
 -v, --verbose reveal info-tier advisories on stderr

Docs: https://docs.retrofit.sh/current/commands/retrofit-op-remove/

retrofit op remove --help-all adds:

retrofit op revise

Mon, 01 Jan 0001 00:00:00 +0000

`retrofit op revise`

Patch bound parameters on an unsealed op

Usage:
 retrofit op revise <opid> [<key>=<value>...] [flags]

Flags:
 --batch read newline-separated revise commands from stdin (transactional)
 --dry-run preview the proposed tail without writing
 -h, --help help for revise
 --help-all show extended help (vocabulary, semantics, caveats)
 -i, --interactive open an editor on the selector's ops

Global Flags:
 --as string output mode: text | json (default "text")
 -C, --chdir string treat <dir> as the working directory for the entire run
 --config string retrofit.toml path (overrides discovery; also accepts $RETROFIT_CONFIG)
 -f, --file string oplog file path; selects a registered [[schema]] path (overrides discovery)
 --no-consolidate render every advisory occurrence instead of collapsing repeats
 -q, --quiet count suppress the advisory tier on stderr; stack (-qq) to drop it whole (errors and results still print)
 --schema <name> registered schema <name> (resolves via the chain when omitted)
 -v, --verbose reveal info-tier advisories on stderr

Docs: https://docs.retrofit.sh/current/commands/retrofit-op-revise/

retrofit op revise --help-all adds:

retrofit op seal

Mon, 01 Jan 0001 00:00:00 +0000

`retrofit op seal`

Seal the unsealed tail of the oplog. The Seal covers every op from
the first unsealed op through the current tail; subsequent edits to
those ops are detected by `retrofit validate`.

Tail-append only: sealing a sub-range of the unsealed tail is out
of scope.

A range that declares reference data seals only when every reference
record it covers is witnessed, and only when every ExtractTable
child or CopyTable clone of a declared table born in it has a record
of its own (reference-rows-uncaptured): the op moves the source's
rows into the product in every migrated database, so a fresh build
needs them captured.

Run with --help-all for recovery guidance (e.g. removing a Seal
authored on the wrong branch).

Usage:
 retrofit op seal [flags]

Flags:
 --compact string compact the tail to this frontier file, then seal it, in one write
 -h, --help help for seal
 --help-all show extended help (vocabulary, semantics, caveats)
 --reason string optional reason text recorded on the Seal

Global Flags:
 --as string output mode: text | json (default "text")
 -C, --chdir string treat <dir> as the working directory for the entire run
 --config string retrofit.toml path (overrides discovery; also accepts $RETROFIT_CONFIG)
 -f, --file string oplog file path; selects a registered [[schema]] path (overrides discovery)
 --no-consolidate render every advisory occurrence instead of collapsing repeats
 -q, --quiet count suppress the advisory tier on stderr; stack (-qq) to drop it whole (errors and results still print)
 --schema <name> registered schema <name> (resolves via the chain when omitted)
 -v, --verbose reveal info-tier advisories on stderr

Docs: https://docs.retrofit.sh/current/commands/retrofit-op-seal/

retrofit op seal --help-all adds:

retrofit op show

Mon, 01 Jan 0001 00:00:00 +0000

`retrofit op show`

Render ops from the oplog

Usage:
 retrofit op show [<selector>] [flags]

Flags:
 --annotate annotate every param with kind/enum metadata
 --filter key=value scalar equality predicate key=value; repeat for AND
 --findings after each op, print body-bearing Findings
 --framing string grammar shape in text mode: log | add | revise (default log: on-disk record) (default "log")
 --head int keep the first N ops after filtering (N > 0)
 -h, --help help for show
 --help-all show extended help (vocabulary, semantics, caveats)
 --include-sealed widen scope to include sealed ops
 -k, --keys strings project only these editable keys (comma-separated; repeatable)
 --long one param per line with shell line-continuation
 --raw print one fixed-shape key=value record per AddColumn op (op, name, typ, typeRef); ignores --keys/--framing/--filter/--touching/--tail/--head
 --tail int keep the last N ops after filtering (N > 0)
 --touching stringArray match ops referencing this element; repeat for OR

Global Flags:
 --as string output mode: text | json (default "text")
 -C, --chdir string treat <dir> as the working directory for the entire run
 --config string retrofit.toml path (overrides discovery; also accepts $RETROFIT_CONFIG)
 -f, --file string oplog file path; selects a registered [[schema]] path (overrides discovery)
 --no-consolidate render every advisory occurrence instead of collapsing repeats
 -q, --quiet count suppress the advisory tier on stderr; stack (-qq) to drop it whole (errors and results still print)
 --schema <name> registered schema <name> (resolves via the chain when omitted)
 -v, --verbose reveal info-tier advisories on stderr

Docs: https://docs.retrofit.sh/current/commands/retrofit-op-show/

retrofit op show --help-all adds:

retrofit op truncate

Mon, 01 Jan 0001 00:00:00 +0000

`retrofit op truncate`

Rewind the oplog to a checkpoint by removing a suffix of ops

Usage:
 retrofit op truncate [flags]

Flags:
 --drop-seals int also peel back this many Seal records (and everything each covers); the flag is the attestation, and each Seal removed is reported
 --dry-run preview the opids that would be removed without writing
 -h, --help help for truncate
 --help-all show extended help (vocabulary, semantics, caveats)

Global Flags:
 --as string output mode: text | json (default "text")
 -C, --chdir string treat <dir> as the working directory for the entire run
 --config string retrofit.toml path (overrides discovery; also accepts $RETROFIT_CONFIG)
 -f, --file string oplog file path; selects a registered [[schema]] path (overrides discovery)
 --no-consolidate render every advisory occurrence instead of collapsing repeats
 -q, --quiet count suppress the advisory tier on stderr; stack (-qq) to drop it whole (errors and results still print)
 --schema <name> registered schema <name> (resolves via the chain when omitted)
 -v, --verbose reveal info-tier advisories on stderr

Docs: https://docs.retrofit.sh/current/commands/retrofit-op-truncate/

retrofit op truncate --help-all adds:

retrofit op unseal

Mon, 01 Jan 0001 00:00:00 +0000

`retrofit op unseal`

Demote the most-recent N Seal record(s), keeping their ops as unsealed tail

Usage:
 retrofit op unseal [N] [flags]

Flags:
 --dry-run preview the Seal opids that would be removed without writing
 -h, --help help for unseal
 --help-all show extended help (vocabulary, semantics, caveats)

Global Flags:
 --as string output mode: text | json (default "text")
 -C, --chdir string treat <dir> as the working directory for the entire run
 --config string retrofit.toml path (overrides discovery; also accepts $RETROFIT_CONFIG)
 -f, --file string oplog file path; selects a registered [[schema]] path (overrides discovery)
 --no-consolidate render every advisory occurrence instead of collapsing repeats
 -q, --quiet count suppress the advisory tier on stderr; stack (-qq) to drop it whole (errors and results still print)
 --schema <name> registered schema <name> (resolves via the chain when omitted)
 -v, --verbose reveal info-tier advisories on stderr

Docs: https://docs.retrofit.sh/current/commands/retrofit-op-unseal/

retrofit op unseal --help-all adds:

retrofit ops

Mon, 01 Jan 0001 00:00:00 +0000

`retrofit ops`

Run bulk maintenance over the oplog

Usage:
 retrofit ops
 retrofit ops [command]

Available Commands:
 upgrade-sql-bodies Upgrade LANGUAGE sql opaque function bodies to BEGIN ATOMIC

Flags:
 -h, --help help for ops
 --help-all show extended help (vocabulary, semantics, caveats)

Global Flags:
 --as string output mode: text | json (default "text")
 -C, --chdir string treat <dir> as the working directory for the entire run
 --config string retrofit.toml path (overrides discovery; also accepts $RETROFIT_CONFIG)
 -f, --file string oplog file path; selects a registered [[schema]] path (overrides discovery)
 --no-consolidate render every advisory occurrence instead of collapsing repeats
 -q, --quiet count suppress the advisory tier on stderr; stack (-qq) to drop it whole (errors and results still print)
 -v, --verbose reveal info-tier advisories on stderr

Use "retrofit ops [command] --help" for more information about a command.

Docs: https://docs.retrofit.sh/current/commands/retrofit-ops/

retrofit ops upgrade-sql-bodies

Mon, 01 Jan 0001 00:00:00 +0000

`retrofit ops upgrade-sql-bodies`

Upgrade LANGUAGE sql opaque function bodies to BEGIN ATOMIC

Usage:
 retrofit ops upgrade-sql-bodies [flags]

Flags:
 --dry-run preview without writing
 -h, --help help for upgrade-sql-bodies
 --help-all show extended help (vocabulary, semantics, caveats)
 --schema <name> registered schema <name> (resolves via the chain when omitted)

Global Flags:
 --as string output mode: text | json (default "text")
 -C, --chdir string treat <dir> as the working directory for the entire run
 --config string retrofit.toml path (overrides discovery; also accepts $RETROFIT_CONFIG)
 -f, --file string oplog file path; selects a registered [[schema]] path (overrides discovery)
 --no-consolidate render every advisory occurrence instead of collapsing repeats
 -q, --quiet count suppress the advisory tier on stderr; stack (-qq) to drop it whole (errors and results still print)
 -v, --verbose reveal info-tier advisories on stderr

Docs: https://docs.retrofit.sh/current/commands/retrofit-ops-upgrade-sql-bodies/

retrofit reconcile

Mon, 01 Jan 0001 00:00:00 +0000

`retrofit reconcile`

Close concurrent forks in the oplog by rebasing onto a linear tail

Usage:
 retrofit reconcile [<fork-selector>] [flags]

Flags:
 --accept-dirty write the requested order even when no clean order exists (dirty tail; resolve with op revise)
 --all reconcile every leaf fork in line order (per-leaf atomic write); with --clean, refuses fork-nested (exit 1) on oplogs containing multiple truly-independent forks; run reconcile <fork-selector> --clean per fork in that case
 --allow-sealed-rewrite opid [sealed history] attest each Seal this run would demote or replace, by its full opid (repeatable, comma-separated); a value attests the Seal it names and selects nothing, and a Seal left unnamed refuses seal-removal-refused
 --clean write only if a clean order exists; refuse otherwise
 -h, --help help for reconcile
 --help-all show extended help (vocabulary, semantics, caveats)
 --keep bias: prefer the first-seen block order (default when bias is meaningful)
 --schema <name> registered schema <name> (resolves via the chain when omitted)
 --swap bias: prefer the second-seen block order

Global Flags:
 --as string output mode: text | json (default "text")
 -C, --chdir string treat <dir> as the working directory for the entire run
 --config string retrofit.toml path (overrides discovery; also accepts $RETROFIT_CONFIG)
 -f, --file string oplog file path; selects a registered [[schema]] path (overrides discovery)
 --no-consolidate render every advisory occurrence instead of collapsing repeats
 -q, --quiet count suppress the advisory tier on stderr; stack (-qq) to drop it whole (errors and results still print)
 -v, --verbose reveal info-tier advisories on stderr

Docs: https://docs.retrofit.sh/current/commands/retrofit-reconcile/

retrofit reconcile --help-all adds:

retrofit schema

Mon, 01 Jan 0001 00:00:00 +0000

`retrofit schema`

Manage registered schemas

Usage:
 retrofit schema
 retrofit schema [command]

Available Commands:
 create Create a new oplog and register the schema
 engine Read or set a schema's engine version (production pin + emit target)
 form Print or switch the oplog's form line (merge or compact)
 list List registered schemas (name, path, engine version, default marker)
 move Move a schema's oplog to another directory
 ref-tables Read or edit a schema's reference-data capture policy
 remove Remove a registered schema (deletes the oplog file by default)
 scope Manage [directory_scope] entries
 set-default Set or clear default_schema in retrofit.toml

Flags:
 -h, --help help for schema
 --help-all show extended help (vocabulary, semantics, caveats)

Global Flags:
 --as string output mode: text | json (default "text")
 -C, --chdir string treat <dir> as the working directory for the entire run
 --config string retrofit.toml path (overrides discovery; also accepts $RETROFIT_CONFIG)
 -f, --file string oplog file path; selects a registered [[schema]] path (overrides discovery)
 --no-consolidate render every advisory occurrence instead of collapsing repeats
 -q, --quiet count suppress the advisory tier on stderr; stack (-qq) to drop it whole (errors and results still print)
 -v, --verbose reveal info-tier advisories on stderr

Use "retrofit schema [command] --help" for more information about a command.

Docs: https://docs.retrofit.sh/current/commands/retrofit-schema/

retrofit schema create

Mon, 01 Jan 0001 00:00:00 +0000

`retrofit schema create`

Create a new oplog and register the schema in retrofit.toml.

<name> schema identifier (SQL-identifier shape).
<location> optional target DIRECTORY (an existing dir, or a
 trailing-/ path to be created); the oplog file is
 derived as <name>.oplog.

Run with --help-all for the name-charset rules.

Usage:
 retrofit schema create <name> [<location>] [flags]

Flags:
 --engine-version <15|16|17|18> supported major <15|16|17|18> for the new schema (default: project engine_version)
 --form merge the new oplog's form: merge or `compact` (default "merge")
 -h, --help help for create
 --help-all show extended help (vocabulary, semantics, caveats)
 --is-default pin this schema as default_schema
 --scope stringArray directory to scope to this schema (repeatable)

Global Flags:
 --as string output mode: text | json (default "text")
 -C, --chdir string treat <dir> as the working directory for the entire run
 --config string retrofit.toml path (overrides discovery; also accepts $RETROFIT_CONFIG)
 -f, --file string oplog file path; selects a registered [[schema]] path (overrides discovery)
 --no-consolidate render every advisory occurrence instead of collapsing repeats
 -q, --quiet count suppress the advisory tier on stderr; stack (-qq) to drop it whole (errors and results still print)
 -v, --verbose reveal info-tier advisories on stderr

Docs: https://docs.retrofit.sh/current/commands/retrofit-schema-create/

retrofit schema create --help-all adds:

retrofit schema engine

Mon, 01 Jan 0001 00:00:00 +0000

`retrofit schema engine`

Read (no <version>) or set (with <version>) a schema's two
engine-version axes: the production pin (oplog header) and
the emit target ([[schema]] engine_version). Default form
sets both axes. Selects schema via --schema or resolver chain.

Usage:
 retrofit schema engine [<version>] [flags]

Flags:
 --config-only set only the toml target axis (oplog header untouched)
 --dry-run report the would-action without writing
 -h, --help help for engine
 --help-all show extended help (vocabulary, semantics, caveats)
 --schema <name> registered schema <name> (resolves via the chain when omitted)

Global Flags:
 --as string output mode: text | json (default "text")
 -C, --chdir string treat <dir> as the working directory for the entire run
 --config string retrofit.toml path (overrides discovery; also accepts $RETROFIT_CONFIG)
 -f, --file string oplog file path; selects a registered [[schema]] path (overrides discovery)
 --no-consolidate render every advisory occurrence instead of collapsing repeats
 -q, --quiet count suppress the advisory tier on stderr; stack (-qq) to drop it whole (errors and results still print)
 -v, --verbose reveal info-tier advisories on stderr

Docs: https://docs.retrofit.sh/current/commands/retrofit-schema-engine/

retrofit schema engine --help-all adds:

retrofit schema form

Mon, 01 Jan 0001 00:00:00 +0000

`retrofit schema form`

Print (no argument) or switch a schema's oplog form. compact to merge
changes the form line; merge to compact compacts every range, sealed
ones included, the switch being the attestation. Naming the form the
file holds changes no line. Selects schema via --schema or resolver chain.

Usage:
 retrofit schema form [merge|compact] [flags]

Flags:
 -h, --help help for form
 --help-all show extended help (vocabulary, semantics, caveats)
 --schema <name> registered schema <name> (resolves via chain if omitted)

Global Flags:
 --as string output mode: text | json (default "text")
 -C, --chdir string treat <dir> as the working directory for the entire run
 --config string retrofit.toml path (overrides discovery; also accepts $RETROFIT_CONFIG)
 -f, --file string oplog file path; selects a registered [[schema]] path (overrides discovery)
 --no-consolidate render every advisory occurrence instead of collapsing repeats
 -q, --quiet count suppress the advisory tier on stderr; stack (-qq) to drop it whole (errors and results still print)
 -v, --verbose reveal info-tier advisories on stderr

Docs: https://docs.retrofit.sh/current/commands/retrofit-schema-form/

retrofit schema list

Mon, 01 Jan 0001 00:00:00 +0000

`retrofit schema list`

Enumerate the [[schema]] entries in retrofit.toml: name, oplog
path, resolved engine version, and which one is the default_schema
pin. An empty registry succeeds with zero rows.

Usage:
 retrofit schema list [flags]

Flags:
 -h, --help help for list
 --help-all show extended help (vocabulary, semantics, caveats)

Global Flags:
 --as string output mode: text | json (default "text")
 -C, --chdir string treat <dir> as the working directory for the entire run
 --config string retrofit.toml path (overrides discovery; also accepts $RETROFIT_CONFIG)
 -f, --file string oplog file path; selects a registered [[schema]] path (overrides discovery)
 --no-consolidate render every advisory occurrence instead of collapsing repeats
 -q, --quiet count suppress the advisory tier on stderr; stack (-qq) to drop it whole (errors and results still print)
 -v, --verbose reveal info-tier advisories on stderr

Docs: https://docs.retrofit.sh/current/commands/retrofit-schema-list/

retrofit schema move

Mon, 01 Jan 0001 00:00:00 +0000

`retrofit schema move`

Move a schema's oplog to another directory

Usage:
 retrofit schema move <directory> [--schema <name>] [flags]

Flags:
 -h, --help help for move
 --help-all show extended help (vocabulary, semantics, caveats)
 --schema <name> registered schema <name> (resolves via the chain when omitted)

Global Flags:
 --as string output mode: text | json (default "text")
 -C, --chdir string treat <dir> as the working directory for the entire run
 --config string retrofit.toml path (overrides discovery; also accepts $RETROFIT_CONFIG)
 -f, --file string oplog file path; selects a registered [[schema]] path (overrides discovery)
 --no-consolidate render every advisory occurrence instead of collapsing repeats
 -q, --quiet count suppress the advisory tier on stderr; stack (-qq) to drop it whole (errors and results still print)
 -v, --verbose reveal info-tier advisories on stderr

Docs: https://docs.retrofit.sh/current/commands/retrofit-schema-move/

retrofit schema ref-tables

Mon, 01 Jan 0001 00:00:00 +0000

`retrofit schema ref-tables`

Read or edit a schema's reference-data capture policy.

A table declared as reference data holds the rows the application reads but
never writes, such as currency codes, country lists and status enumerations.
Rows the application writes are seed or transition data and are not declared
here.

The declaration is an attribute of the table's element, carried in the oplog:
add and remove append one SetReferenceData op per resolved table. Nothing is
stored in retrofit.toml, and the declaration survives a rename because it
lives on the element rather than on its name.

The declared set is the reference capture scope of every producer run: import,
data capture, drift and data scaffold each read the set at their own minting
cut and capture a declared table's rows as reference data.

The bare parent reads and reports the declared set. add and remove edit it and
then report the whole result; there is deliberately no list subcommand.

Each argument is an exact relname or a filepath.Match glob, resolved against
the live tables of the read cut: HEAD unless --at <opid> names one. A name
that resolves to nothing is refused: a declaration names a live element, so
the table must exist before it can be declared. A glob is never stored; the
resolved table names are what the oplog carries.

Usage:
 retrofit schema ref-tables [flags]
 retrofit schema ref-tables [command]

Available Commands:
 add Declare one or more tables as the schema's reference data
 remove Undeclare one or more of the schema's reference-data tables

Flags:
 --at <opid> read cut <opid> (HEAD when omitted)
 --data-root data_root root that overrides the schema's data_root
 -h, --help help for ref-tables
 --help-all show extended help (vocabulary, semantics, caveats)
 --schema <name> registered schema <name> (resolves via the chain when omitted)

Global Flags:
 --as string output mode: text | json (default "text")
 -C, --chdir string treat <dir> as the working directory for the entire run
 --config string retrofit.toml path (overrides discovery; also accepts $RETROFIT_CONFIG)
 -f, --file string oplog file path; selects a registered [[schema]] path (overrides discovery)
 --no-consolidate render every advisory occurrence instead of collapsing repeats
 -q, --quiet count suppress the advisory tier on stderr; stack (-qq) to drop it whole (errors and results still print)
 -v, --verbose reveal info-tier advisories on stderr

Use "retrofit schema ref-tables [command] --help" for more information about a command.

Docs: https://docs.retrofit.sh/current/commands/retrofit-schema-ref-tables/

retrofit schema ref-tables add

Mon, 01 Jan 0001 00:00:00 +0000

`retrofit schema ref-tables add`

Declare one or more tables as the schema's reference data

Usage:
 retrofit schema ref-tables add <table>... [flags]

Flags:
 --dry-run report the would-be oplog entries without minting
 -h, --help help for add
 --help-all show extended help (vocabulary, semantics, caveats)

Global Flags:
 --as string output mode: text | json (default "text")
 --at <opid> read cut <opid> (HEAD when omitted)
 -C, --chdir string treat <dir> as the working directory for the entire run
 --config string retrofit.toml path (overrides discovery; also accepts $RETROFIT_CONFIG)
 --data-root data_root root that overrides the schema's data_root
 -f, --file string oplog file path; selects a registered [[schema]] path (overrides discovery)
 --no-consolidate render every advisory occurrence instead of collapsing repeats
 -q, --quiet count suppress the advisory tier on stderr; stack (-qq) to drop it whole (errors and results still print)
 --schema <name> registered schema <name> (resolves via the chain when omitted)
 -v, --verbose reveal info-tier advisories on stderr

Docs: https://docs.retrofit.sh/current/commands/retrofit-schema-ref-tables-add/

retrofit schema ref-tables remove

Mon, 01 Jan 0001 00:00:00 +0000

`retrofit schema ref-tables remove`

Undeclare one or more of the schema's reference-data tables

Usage:
 retrofit schema ref-tables remove <table>... [flags]

Flags:
 --dry-run report the would-be oplog entries without minting
 -h, --help help for remove
 --help-all show extended help (vocabulary, semantics, caveats)

Global Flags:
 --as string output mode: text | json (default "text")
 --at <opid> read cut <opid> (HEAD when omitted)
 -C, --chdir string treat <dir> as the working directory for the entire run
 --config string retrofit.toml path (overrides discovery; also accepts $RETROFIT_CONFIG)
 --data-root data_root root that overrides the schema's data_root
 -f, --file string oplog file path; selects a registered [[schema]] path (overrides discovery)
 --no-consolidate render every advisory occurrence instead of collapsing repeats
 -q, --quiet count suppress the advisory tier on stderr; stack (-qq) to drop it whole (errors and results still print)
 --schema <name> registered schema <name> (resolves via the chain when omitted)
 -v, --verbose reveal info-tier advisories on stderr

Docs: https://docs.retrofit.sh/current/commands/retrofit-schema-ref-tables-remove/

retrofit schema remove

Mon, 01 Jan 0001 00:00:00 +0000

`retrofit schema remove`

Remove a schema's [[schema]] entry from retrofit.toml and delete
its oplog file, whatever it holds, sealed ops included (pass
--keep-oplog to keep it). A committed oplog can be restored from git.

Usage:
 retrofit schema remove <name> [flags]

Flags:
 -h, --help help for remove
 --help-all show extended help (vocabulary, semantics, caveats)
 --keep-oplog unregister the schema but leave the oplog file on disk

Global Flags:
 --as string output mode: text | json (default "text")
 -C, --chdir string treat <dir> as the working directory for the entire run
 --config string retrofit.toml path (overrides discovery; also accepts $RETROFIT_CONFIG)
 -f, --file string oplog file path; selects a registered [[schema]] path (overrides discovery)
 --no-consolidate render every advisory occurrence instead of collapsing repeats
 -q, --quiet count suppress the advisory tier on stderr; stack (-qq) to drop it whole (errors and results still print)
 -v, --verbose reveal info-tier advisories on stderr

Docs: https://docs.retrofit.sh/current/commands/retrofit-schema-remove/

retrofit schema scope

Mon, 01 Jan 0001 00:00:00 +0000

`retrofit schema scope`

Manage [directory_scope] entries

Usage:
 retrofit schema scope
 retrofit schema scope [command]

Available Commands:
 add Add a [directory_scope] entry
 remove Remove a [directory_scope] entry

Flags:
 -h, --help help for scope
 --help-all show extended help (vocabulary, semantics, caveats)

Global Flags:
 --as string output mode: text | json (default "text")
 -C, --chdir string treat <dir> as the working directory for the entire run
 --config string retrofit.toml path (overrides discovery; also accepts $RETROFIT_CONFIG)
 -f, --file string oplog file path; selects a registered [[schema]] path (overrides discovery)
 --no-consolidate render every advisory occurrence instead of collapsing repeats
 -q, --quiet count suppress the advisory tier on stderr; stack (-qq) to drop it whole (errors and results still print)
 -v, --verbose reveal info-tier advisories on stderr

Use "retrofit schema scope [command] --help" for more information about a command.

Docs: https://docs.retrofit.sh/current/commands/retrofit-schema-scope/

retrofit schema scope add

Mon, 01 Jan 0001 00:00:00 +0000

`retrofit schema scope add`

Add a [directory_scope] entry

Usage:
 retrofit schema scope add <dir> [--schema <name>] [flags]

Flags:
 -h, --help help for add
 --help-all show extended help (vocabulary, semantics, caveats)
 --schema <name> registered schema <name> (resolves via the chain when omitted)

Global Flags:
 --as string output mode: text | json (default "text")
 -C, --chdir string treat <dir> as the working directory for the entire run
 --config string retrofit.toml path (overrides discovery; also accepts $RETROFIT_CONFIG)
 -f, --file string oplog file path; selects a registered [[schema]] path (overrides discovery)
 --no-consolidate render every advisory occurrence instead of collapsing repeats
 -q, --quiet count suppress the advisory tier on stderr; stack (-qq) to drop it whole (errors and results still print)
 -v, --verbose reveal info-tier advisories on stderr

Docs: https://docs.retrofit.sh/current/commands/retrofit-schema-scope-add/

retrofit schema scope remove

Mon, 01 Jan 0001 00:00:00 +0000

`retrofit schema scope remove`

Remove a [directory_scope] entry

Usage:
 retrofit schema scope remove <dir> [flags]

Flags:
 -h, --help help for remove
 --help-all show extended help (vocabulary, semantics, caveats)

Global Flags:
 --as string output mode: text | json (default "text")
 -C, --chdir string treat <dir> as the working directory for the entire run
 --config string retrofit.toml path (overrides discovery; also accepts $RETROFIT_CONFIG)
 -f, --file string oplog file path; selects a registered [[schema]] path (overrides discovery)
 --no-consolidate render every advisory occurrence instead of collapsing repeats
 -q, --quiet count suppress the advisory tier on stderr; stack (-qq) to drop it whole (errors and results still print)
 -v, --verbose reveal info-tier advisories on stderr

Docs: https://docs.retrofit.sh/current/commands/retrofit-schema-scope-remove/

retrofit schema set-default

Mon, 01 Jan 0001 00:00:00 +0000

`retrofit schema set-default`

Set or clear default_schema in retrofit.toml

Usage:
 retrofit schema set-default <name> | --unset [flags]

Flags:
 -h, --help help for set-default
 --help-all show extended help (vocabulary, semantics, caveats)
 --unset remove default_schema from retrofit.toml

Global Flags:
 --as string output mode: text | json (default "text")
 -C, --chdir string treat <dir> as the working directory for the entire run
 --config string retrofit.toml path (overrides discovery; also accepts $RETROFIT_CONFIG)
 -f, --file string oplog file path; selects a registered [[schema]] path (overrides discovery)
 --no-consolidate render every advisory occurrence instead of collapsing repeats
 -q, --quiet count suppress the advisory tier on stderr; stack (-qq) to drop it whole (errors and results still print)
 -v, --verbose reveal info-tier advisories on stderr

Docs: https://docs.retrofit.sh/current/commands/retrofit-schema-set-default/

retrofit snapshot

Mon, 01 Jan 0001 00:00:00 +0000

`retrofit snapshot`

Emit canonical DDL for the materialized schema, shaped like
`pg_dump --schema-only` (docs/pg_dump-parity.md lists the differences).

Run with --help-all for the full --include-drop / --using semantics.

Usage:
 retrofit snapshot [flags]

Flags:
 --allow-reading-replace-body downgrade the replace-body-reads-relation refusal to a warning; emit the body verbatim under a WARNING comment, and render its table's prologue as a whole-table clear
 --allow-stale-dml downgrade every stale-DML-reference refusal to a warning; emit the body under a stale-reference WARNING comment. It does NOT cover chain-collision, which is not attestable: two live chains for one element is a fork to resolve by retiring one, and exit 2 stands
 --allow-unnamed-label stringArray attest that the dataset carrying this exact label is deliberately left unnamed in this run (repeatable; byte-exact, never trimmed); every other unnamed dataset still warns
 --at root emit DDL for the cut at <opid> prefix or anchor (root/`last`/`seal`, optional `^`/`~N`) (default: last)
 --data-only emit the data band only: the banner (unless --no-header), then the band as snapshot emits it; no DDL
 --data-root data_root root that overrides the schema's data_root
 --exclude-schema strings drop schemas matching <name> from emission (repeatable; pg_dump -N)
 --exclude-table strings drop tables matching <name> or <schema>.<name> from emission (repeatable; pg_dump -T)
 --extra-seed-path seed_paths root that appends to the declared seed_paths
 -h, --help help for snapshot
 --help-all show extended help (vocabulary, semantics, caveats)
 --include-drop string[="scoped"] DROP prologue before the CREATEs: none | scoped | schema (default "none")
 --label stringArray apply the dataset carrying this exact label (repeatable; argv order is layer order; byte-exact, never trimmed; never cuts ref data)
 --no-comments suppress every COMMENT ON statement (pg_dump --no-comments)
 --no-header suppress the canonical banner line
 --over string with --data-only: emit only the tables the LAST-named --label's layer contributed to (a projection, never a diff)
 --schema <name> registered schema <name> (resolves via the chain when omitted)
 --seed-path seed_paths root that replaces the declared seed_paths
 --skip-manifest string write skipped view-render records (JSONL) to <path>
 --table strings restrict emission to tables matching <name> or <schema>.<name> (repeatable; pg_dump -t)
 --using string one-shot emit target override (format: <engine>:<major>; read-only)

Global Flags:
 --as string output mode: text | json (default "text")
 -C, --chdir string treat <dir> as the working directory for the entire run
 --config string retrofit.toml path (overrides discovery; also accepts $RETROFIT_CONFIG)
 -f, --file string oplog file path; selects a registered [[schema]] path (overrides discovery)
 --no-consolidate render every advisory occurrence instead of collapsing repeats
 -q, --quiet count suppress the advisory tier on stderr; stack (-qq) to drop it whole (errors and results still print)
 -v, --verbose reveal info-tier advisories on stderr

Docs: https://docs.retrofit.sh/current/commands/retrofit-snapshot/

retrofit snapshot --help-all adds:

retrofit validate

Mon, 01 Jan 0001 00:00:00 +0000

`retrofit validate`

Validate retrofit.toml, project layout, and the oplog

Usage:
 retrofit validate [flags]

Flags:
 --allow-unmerged-fork report an unmerged fork as an advisory and exit 0; apply-risk hazards, seal-integrity refusals and standing violations still fail the run
 --every-commit with --history, validate every commit of the PR in the bundle, not only the candidate
 --fail-on-apply-risk fail (exit 2) on the apply-risk hazards in the migration window since the latest Seal: validating-fk, validating-check and add-not-null on a table that may hold rows; add-unique stays advisory
 -h, --help help for validate
 --help-all show extended help (vocabulary, semantics, caveats)
 --history string check the history bundle at <dir> (written by the CI snippet; retrofit runs no git)

Global Flags:
 --as string output mode: text | json (default "text")
 -C, --chdir string treat <dir> as the working directory for the entire run
 --config string retrofit.toml path (overrides discovery; also accepts $RETROFIT_CONFIG)
 -f, --file string oplog file path; selects a registered [[schema]] path (overrides discovery)
 --no-consolidate render every advisory occurrence instead of collapsing repeats
 -q, --quiet count suppress the advisory tier on stderr; stack (-qq) to drop it whole (errors and results still print)
 -v, --verbose reveal info-tier advisories on stderr

Docs: https://docs.retrofit.sh/current/commands/retrofit-validate/

retrofit validate --help-all adds:

Operators

Mon, 01 Jan 0001 00:00:00 +0000

SMO Catalog and Status

Every Schema Modification Operator (SMO) against PostgreSQL’s DDL surface, and whether its descriptor is registered in internal/oplog/catalog/operators.go, the source of truth. op info <Op> prints an operator’s catalog entry: its inverse, its tier and what it preserves. Which verbs author, recognize, render or refuse each SMO is in the per-verb references: import.md, drift.md, snapshot.md, migrate.md.

Status

Code	Meaning
✓	Implemented in `internal/oplog/catalog/operators.go`.
not registered	No descriptor in `operators.go`. The Notes column says what is not available and why.
N/A:reason	Out of scope by construction (`:no-pg-primitive`; `:no-relational-analog` for NoSQL/JSONB; `:physical-surface` for cluster/storage). The `reason` token is bare; any qualifying prose belongs in the Notes column.

In the Local name column, “none” means no registered operator carries the SMO.

Output contract

Mon, 01 Jan 0001 00:00:00 +0000

CLI output contract

This document is the canonical reference for what the retrofit CLI prints, where, and in what shape. It is the contract you script against.

The persistent root flag --as=text|json selects the output mode. Stdout carries the disposition (a terminal envelope under JSON mode); stderr carries advisories. Errors normally land on stdout under JSON so a single jq filter handles both ok and error paths. Channel exceptions lists the records that depart from this rule.

Advisory codes

Mon, 01 Jan 0001 00:00:00 +0000

Advisory codes

Every advisory retrofit prints, by code. The register is the word a text line opens with and the JSON level: warning or note. A braced name such as {table} is a value the printed line fills in. A message that varies with a field shows each form on its own line, led by the field’s value. Where the message is only such a value, its detail and hint lines follow it.

pg_dump parity

Mon, 01 Jan 0001 00:00:00 +0000

pg_dump `--schema-only` parity

snapshot emits DDL shaped like pg_dump --schema-only. This page audits that claim option by option: for each pg_dump option that affects a schema-only dump, what snapshot does, whether the name is discoverable from pg_dump, and whether import accepts the option’s effect on output.

Options are from the PostgreSQL 18 pg_dump reference: https://www.postgresql.org/docs/18/app-pgdump.html.

Status legend

covered: retrofit has an explicit flag or a fixed behavior matching pg_dump’s contract.
implicit: retrofit never emits the relevant DDL, so the pg_dump flag’s “do not emit X” semantics hold trivially.
gap: pg_dump has it and snapshot has no counterpart.
out-of-scope: the option does not fit an oplog-in, one-stream-out emitter.

Snapshot side (`retrofit snapshot` vs `pg_dump --schema-only`)

`pg_dump`	`snapshot` today	status	round-trip via `import`
`-s, --schema-only`	always (no data)	covered	n/a (input shape)
`-c, --clean`	`--include-drop=scoped\|schema`	covered (no alias)	DROP statements skipped (gap below)
`--if-exists`	folded into `--include-drop=scoped\|schema`	covered (contract)	n/a (DROPs skipped)
`-C, --create`	none (schema-scoped, never `CREATE DATABASE`)	out-of-scope	n/a
`-O, --no-owner`	implicit (no owner concept in vocab)	implicit	n/a (OWNER TO is skipped)
`-x, --no-privileges` / `--no-acl`	implicit (no GRANT/REVOKE)	implicit	n/a (GRANT/REVOKE is skipped)
`--no-comments`	`--no-comments` suppresses `COMMENT ON`	covered	tolerant (in vocab)
`--no-tablespaces`	implicit (no `TABLESPACE …`)	implicit	n/a
`--no-table-access-method`	implicit (no `USING <method>` on CREATE TABLE)	implicit	n/a
`--quote-all-identifiers`	always quotes (`quoteIdent` in `internal/ddl/postgres/helpers.go`)	covered (contract)	tolerant (parser is quote-agnostic)
`-n, --schema=<pattern>`	`--schema <registered-name>` (single, not pattern)	covered (different shape)	n/a
`-N, --exclude-schema`	`--exclude-schema=<name>` (repeatable, exact-match)	covered (exact-match)	n/a
`-t, --table` / `-T, --exclude-table`	`--table=<name>` / `--exclude-table=<name>` (repeatable, exact-match)	covered (exact-match)	tolerant (output is a strict subset)
`--section=pre-data\|post-data`	none (single-stream emit)	gap	tolerant either way
`--no-statistics`	implicit (no `ANALYZE` or stats emission)	implicit	n/a
`-f, --file=<path>`	none (stdout only)	out-of-scope (pipe-only)	n/a
`--no-policies`	none (`CREATE POLICY` is emitted; no suppression flag)	gap	tolerant (in vocab)
`--no-publications`	implicit (no `CREATE PUBLICATION`)	implicit	n/a
`--no-subscriptions`	implicit (no `CREATE SUBSCRIPTION`)	implicit	n/a
`--no-security-labels`	implicit (no `SECURITY LABEL`)	implicit	n/a
`--use-set-session-authorization`	implicit (no owner concept)	implicit	n/a
`-e, --extension` / `--exclude-extension`	none (`CREATE EXTENSION` is emitted; no include/exclude filter)	gap	extensions in vocab on import
`--strict-names`	n/a (single-name lookup, no pattern matching)	out-of-scope	n/a
`--filter=<file>`, `--table-and-children`, `--exclude-table-and-children`	none (filtering machinery)	out-of-scope	n/a
`-F, --format`, `-Z, --compress`, `--no-sync`, `--sync-method`	plain stream only	out-of-scope	n/a
`--binary-upgrade`, `--snapshot`, `--serializable-deferrable`, `--lock-wait-timeout`	live-DB-only knobs	out-of-scope (retrofit emits from the oplog, not a live DB)	n/a

Notes on individual rows

-c, --clean (no alias). The --include-drop=none|scoped|schema flag encodes a blast-radius choice that pg_dump’s single --clean switch does not. Aliasing --clean to one of the three modes (most naturally scoped) would let a user paste muscle memory from pg_dump and silently pick the wrong radius. --include-drop=scoped is the nearest match for pg_dump --clean --if-exists; there is no --clean alias.

PostgreSQL versions

Mon, 01 Jan 0001 00:00:00 +0000

PostgreSQL versions

This page says which PostgreSQL majors this build accepts, what each verb does at each one, and what the engine version governs. Only the major is modeled. Each guide states its own verb’s row and links here.

Levels

Major	Level	What it means
17	Default, supported	The value `init` writes to `[project] engine_version`, and the one a schema resolves to when nothing names another.
15, 16	Supported	Every verb works at the pin, and `snapshot` and `migrate` emit the same SQL as at 17. The known gaps apply.
18	Accepted, not supported	Taken only as an explicit pin. `op add`, `validate`, `snapshot` and `migrate` honor it; `import` and `drift` read PostgreSQL 17 syntax only, and several PostgreSQL 18 surfaces refuse or do not render.
Any other value	Refused	`unknown-engine-version`. The value is a bare major: `14`, `19`, `18.1`, `018`, `v18` and `18` all refuse.

An explicit pin is any of:

Release notes

Mon, 01 Jan 0001 00:00:00 +0000

Changelog

All notable changes to retrofit are recorded here, newest first, in the categories of Keep a Changelog. Before 1.0 retrofit promises no compatibility: a change is disclosed here, not prevented.

[Unreleased] records what the builds since the last release changed; a release renames it to its version. Its fixed Log format heading records every change to the oplog’s vocabulary, parameters, headers or seal bytes: what changed and what a user does, usually regenerating the log. CI fails a commit that changes internal/oplog/catalog/*.golden.json, internal/oplog/serialize/ outside its tests, or internal/seal/testdata/leafbytes_*.golden but adds no item under that heading itself (make logformat-check); with make hooks, the commit-msg hook refuses it at git commit. A commit whose serializer edit changes none of the vocabulary, parameters, headers or seal bytes may instead end its message with a Log-format: unchanged trailer; a reader refusing a log it used to accept is a format change. A change to either set of goldens always needs the item.

retrofit

Getting started

Getting started

Concepts

Concepts

The premise

Principles

Principles

1. Rows in the target database are the asset

import

import

Usage

drift

drift

snapshot

snapshot

What snapshot sees

migrate

migrate

data

retrofit data: the data corpus

retrofit data list

retrofit

retrofit

retrofit data

retrofit data

retrofit data capture

retrofit data capture

retrofit data check

retrofit data check

retrofit data list

retrofit data list

retrofit data repin

retrofit data repin

retrofit data retire

retrofit data retire

retrofit data scaffold

retrofit data scaffold

retrofit data witness

retrofit data witness

retrofit drift

retrofit drift

retrofit identify

retrofit identify

retrofit import

retrofit import

retrofit init

retrofit init

retrofit migrate

retrofit migrate

retrofit op

retrofit op

retrofit op add

retrofit op add

retrofit op compact

retrofit op compact

retrofit op info

retrofit op info

retrofit op remove

retrofit op remove

retrofit op revise

retrofit op revise

retrofit op seal

retrofit op seal

retrofit op show

retrofit op show

retrofit op truncate

retrofit op truncate

retrofit op unseal

retrofit op unseal

retrofit ops

retrofit ops

retrofit ops upgrade-sql-bodies

retrofit ops upgrade-sql-bodies

retrofit reconcile

retrofit reconcile

retrofit schema

retrofit schema

retrofit schema create

retrofit schema create

`retrofit data`: the data corpus

`retrofit data list`

`retrofit`

`retrofit data`

`retrofit data capture`

`retrofit data check`

`retrofit data list`

`retrofit data repin`

`retrofit data retire`

`retrofit data scaffold`

`retrofit data witness`

`retrofit drift`

`retrofit identify`

`retrofit import`

`retrofit init`

`retrofit migrate`

`retrofit op`

`retrofit op add`

`retrofit op compact`

`retrofit op info`

`retrofit op remove`

`retrofit op revise`

`retrofit op seal`

`retrofit op show`

`retrofit op truncate`

`retrofit op unseal`

`retrofit ops`

`retrofit ops upgrade-sql-bodies`

`retrofit reconcile`

`retrofit schema`

`retrofit schema create`

`retrofit schema engine`

`retrofit schema form`

`retrofit schema list`

`retrofit schema move`

`retrofit schema ref-tables`

`retrofit schema ref-tables add`

`retrofit schema ref-tables remove`

`retrofit schema remove`

`retrofit schema scope`

`retrofit schema scope add`

`retrofit schema scope remove`

`retrofit schema set-default`

`retrofit snapshot`

`retrofit validate`

pg_dump `--schema-only` parity

Snapshot side (`retrofit snapshot` vs `pg_dump --schema-only`)