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, a
ChangePrimaryKey the ids of its dependent foreign keys, and op revise
of a DetachPartition the detach.col ids replay assigned it.
The cpk.fk ids replay assigns a ChangePrimaryKey’s foreign keys
follow its id=, so op revise of it keeps them. The cpk.fk and
detach.col 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 root 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.