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/