retrofit
0.14.0
retrofit.sh

retrofit element history

retrofit element history <operand> prints the history of one element: one record per op of the selected oplog that created, changed, renamed, moved or ended it, named it from another element, or belongs to the elements it was derived from. 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 history --help:

Usage:
  retrofit element history <operand> [flags]

Description

element history binds its operand to one element of one schema’s oplog, by a live name, an earlier name or an ElementID prefix, and prints every op in that element’s history in log order. retrofit element list prints the ids this verb takes.

The operand

The operand names one element, and the verb refuses to pick between two.

  1. A live element by name binds first, by the name path op add resolves (customer, orders.amount, public.orders.amount, a function’s name(args)), under each kind or the one --kind names.
  2. Otherwise the element that held the name at some cut binds, its last name before it ended included. A table renamed customer to client answers to customer; a dropped orders answers to orders. Each qualifier matches in the same cut as the name it qualifies, so customer.ident binds nothing when the column was only ever ident after its table was renamed.
  3. Otherwise the elements whose ElementID starts with the token bind (1 to 12 hex, or <container>.<hex>). One live candidate binds over ended ones.

Two or more candidates refuse with ambiguous-element and every candidate: its id, name, container, kind and, for one that is not live, ended, the opid that ended it. A ref that two kinds share (a constraint and the index named after it) is two candidates. A token no element held, and any token on an oplog with no op, refuses with no-match.

--schema <name> or the root -f <path> selects one schema’s oplog, as op show does; with neither, the schema is the one the resolver chain selects.

Which ops belong

An op is in an element’s history when, at that op, the element or a child of it appears, ends, moves to another parent or changes; a hyperedge of the op mentions it or a child; an element-ID parameter of the op holds it or a child; or an element whose body references it or a child appears, ends or changes. Sealed and unsealed ops alike belong.

The history also continues into the elements the element was derived or folded from, before the op that did so: CopyTable, MergeTable into a kept table, InlineTable, PartitionTable, SplitTable, JoinTable, ExtractTable, UnjoinTable, a ChangePrimaryKey replaced key, a DetachPartition column, and the copy a detached partition keeps of its parent’s primary key, unique or exclusion constraint, outbound foreign key or index. Those records are lineage. The walk never goes forward: the op that derived new elements from this one lists them as derived_to, and the walk does not enter their histories.

A family column’s history folds every attached partition’s pre-ATTACH column: each AttachPartition record on it is a reference record that lists the absorbed columns as derived_from, and the partitions’ own earlier records follow as lineage.

A born partition’s column does not exist apart from the family column, so its <partition>.<column> token refuses with no-match; an absorbed partition’s <partition>.<column> binds the column the partition held before the ATTACH.

Output

Under --as=json each op is one item record, in log order, and a terminal ok follows.

membermeaning
opid, opthe op’s full opid and operator
sealedthe op is at or before the oplog’s last Seal, the range op revise refuses
viaself (the element or a child changed, or the op names it in a parameter of role in, on, source, sources, id or ids), reference (the op only names it from another element’s parameter or body, or links it by a hyperedge), lineage (an origin’s op)
origin_viaon a lineage record, the self or reference the origin’s own history gives the op
id, kind, name, parentthe element, as of the op (a lineage record names the origin)
renamed_fromthe name before, when the op renamed it
childrenthe children that put the op in the history, each {id, kind, name}
derived_from, derived_tothe elements the op derived or folded this one from; the ones it derived from this one or consumed it into

A field that does not apply is absent. Every list sorts by ElementID. The terminal ok holds schema (absent on a registry-less -f run), the record count, the sealed record count and the element: id, kind, name (its last name once ended), ended when it is not live and also_named, the other elements the name match takes for the operand.

Text mode prints opid<TAB>op<TAB>via<TAB>id<TAB>qualified-name<TAB>sealed|- per record, with no header, and one courtesy note on stderr (-q drops it). kind, parent, renamed_from, children, derived_from and derived_to are JSON-only. A run over the same log prints the same bytes.

Load, resolution and the walk finish before the first record, so a refusal leaves stdout holding only its failed envelope under --as=json, and empty in text.

Options

From retrofit element history --help:

Flags:
  -h, --help            help for history
      --help-all        show extended help (vocabulary, semantics, caveats)
      --kind <kind>     bind only an element of this <kind>: schema, table, column, constraint, index, view, matview, type, extension, policy, function, trigger
      --schema <name>   registered schema <name> (default: the project's one 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 history refuses with. An unreconciled fork anywhere in the oplog refuses with fork-in-range, whatever op the operand binds.

Advisory codes lists every code with its class.

See also

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

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

Published .