retrofit
0.15.0-wip.89
retrofit.sh

These docs are for 0.15.0-wip.89, a WIP, and may describe what no release does yet. The newest release is 0.14.0: this page for 0.14.0.

retrofit element list

retrofit element list prints one record per live element at a cut: its kind, schema, name, ElementID, the ref that op add accepts for it, its containing element and, for a partition, its partitioned parent. It reads the configuration and the oplog, reads no data corpus and writes nothing. Find an element’s ID and history is the task guide.

Synopsis

From retrofit element list --help:

Usage:
  retrofit element list [flags]

Description

element list replays each covered schema’s oplog up to one cut and prints the elements the replay holds there: the live set that retrofit snapshot renders at the same cut.

What it lists

By default the run covers every registered schema; --schema <name> or the root -f <path> covers one. --at takes the cut grammar of retrofit snapshot: an opid prefix, or root, last or seal with an optional ^ or ~N decrement. An anchor resolves in each covered schema. An opid belongs to one oplog, so a hex --at on a run that covers more than one schema refuses with at-requires-schema. --at root is the empty cut and lists nothing. A run that lists nothing is a success.

--kind takes one kind per occurrence, spelled as op add --help spells it, and repeats; --kind table,view is an unknown kind. A table includes partitioned parents and partitions, and a partition’s record names its parent in partition_of. Views and materialized views are never table. View columns, the columns a born partition inherits, and NOT NULL are not elements and never appear. An unnamed constraint appears, without a name.

Naming an element

ref is the first spelling that op add’s own binder resolves to exactly this element, under every op add parameter that takes its kind: the qualified name, else the id. The qualified name is a schema’s or an extension’s own name, <schema>.<name>, or <schema>.<table>.<name> for a child. Its schema is the oplog’s CreateSchema name, which need not equal the registered name in schema. A name that holds a control byte, or begins with -, is skipped. A ref holds at the head the run listed: a later op can change what a name spells. At a cut before the head, ref is the id.

When no spelling binds, the record has no ref, and one element-ref-absent warning names the element, its schema and the operators whose parameter binds its id.

Output

Text mode prints only kind<TAB>schema<TAB>ref<TAB>id per line, with an empty field where a value is absent, and a count note on stderr. A name may hold any byte; --as=json prints every field, the name included.

Under --as=json each element is an item record with kind, schema, name, id, ref, parent and partition_of; a field that does not apply is absent. The terminal ok holds data.count and, per covered schema in schema order, its schema, its cut (root for the empty cut), whether that cut is its head, and its count. A run that covers one schema also names it in the envelope’s schema.

Records sort bytewise on (schema, kind, qualified name, id), and both output modes print the same order. The whole set is computed before the first record prints, so a refusal leaves stdout holding only its failed envelope under --as=json, and empty in text.

Identity

id is the ElementID (see The oplog). An id holds until an op replaces it: import --force replaces every id, and a ChangePrimaryKey the ids of its dependent foreign keys. The cpk.fk ids replay assigns a ChangePrimaryKey’s foreign keys follow its id=, so op revise of it keeps them. op revise of a DetachPartition keeps the ids it records. The cpk.fk ids hold within one oplog and differ between two independent imports.

Load and replay

Every covered schema loads before any is cut, and the first refusal in schema order ends the run. An unreconciled fork between the first op and the cut refuses with fork-in-range; a cut at or before the fork lists normally.

An oplog whose Seal digest does not match still lists. RETROFIT_REQUIRE_EXPLICIT_SCHEMA does not refuse a run that covers every registered schema.

Options

From retrofit element list --help:

Flags:
      --at <opid>       list the cut at <opid> prefix or anchor (`root`/`last`/`seal`, optional `^`/`~N`) (default: the head)
  -h, --help            help for list
      --help-all        show extended help (vocabulary, semantics, caveats)
      --kind <kind>     list only this <kind> (repeatable; one kind per occurrence): schema, table, column, constraint, index, view, matview, type, extension, policy, function, trigger
      --schema <name>   registered schema <name> (default: every registered schema)

The global flags (--as, -C, --config, -f, -q, -v, --no-consolidate) are in the output contract.

Diagnostics

A refusal prints no record, and Refusal codes gives the exit status of every code element list refuses with. element-ref-absent is a warning and does not fail the run (see Naming an element).

Advisory codes lists every code with its class.

See also

Find an element’s ID and history, retrofit element history, retrofit snapshot, Operators, Output contract, The oplog.

Before 1.0, any release may change behavior; the release notes list what changed.

Published .