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.

Work with row data

Row data (the rows of reference tables, test fixtures, migration backfills) is kept in data files beside the oplog, the log of operators your schema is recorded in. snapshot and migrate add those rows to the SQL they emit. A label names a dataset, such as env:dev, and its rows apply only when you name it.

retrofit data is the reference: every data command, each field it prints, the data file’s format and each refusal.

See which rows the emit commands apply

data list shows, table by table, what snapshot and migrate would apply. It emits no SQL and writes nothing. Run it with no flags first:

$ retrofit data list
public.accounts  unspoken  floor=none  appends=0  excluded=3(not-selected:3)  s3=0
public.currencies  occupied  floor=ref/replace/data@op9  witness=witnessed op10  appends=0  excluded=0  s3=0
public.regions  unspoken  floor=none  appends=0  excluded=2(not-selected:2)  s3=0
public.sessions  unspoken  floor=none  appends=0  excluded=1(not-selected:1)  s3=0
label base  files=2
label env:ci  files=2
label env:dev  files=2

A run with no --label applies only the reference tables’ rows, which need no flag, so those tables list as they would emit. The rows of every labeled dataset are left out and counted under not-selected. The label lines at the end are the datasets the project holds, with the number of files in each.

Apply a dataset

Name the datasets you want with --label, in the order they stack, the lowest first. Where a later dataset replaces a table’s rows, the datasets below it no longer apply to that table:

$ retrofit data list --label base --label env:dev
public.accounts  occupied  floor=env:dev/replace/data@op40  witness=unwitnessed  appends=1  excluded=1(superseded:1)  s3=0
public.currencies  occupied  floor=ref/replace/data@op9  witness=witnessed op10  appends=0  excluded=0  s3=0
public.regions  occupied  floor=base/replace/data@op12  witness=unwitnessed  appends=0  excluded=1(not-selected:1)  s3=0
public.sessions  unspoken  floor=none  appends=0  excluded=1(not-selected:1)  s3=0

Here env:dev replaces base’s rows for public.accounts, and public.regions takes base’s rows. Pass the same --label flags, in the same order, to snapshot or migrate to emit those rows. The fields on a line says what each token means.

--at <opid> lists the rows as they stood at an earlier point in the log, and --schema <name> reads another registered schema’s data files.

Write rows by hand

data scaffold writes a data file for one table, holding one record to fill. Replace each <column> placeholder with a value, then check the file:

retrofit data scaffold --table app.loan_periods --purpose transition --disposition append
$EDITOR data/app.loan_periods.202609281743.data.sql   # the path `dml-preserved:` names
retrofit data check
retrofit data list

data check names every placeholder still in the file and exits non-zero until each is filled, and snapshot and migrate exit non-zero on an unfilled file too. --purpose transition is experimental, so the first command works only in a project whose retrofit.toml opts into it (Experimental purposes). Pass --label <label> in place of --purpose to write rows into a dataset. retrofit data scaffold lists the choices for --purpose and --disposition.

Put several rows in one record

A record is a frame, not a row. The marker pair around it may hold one statement, several statements, or one multi-row INSERT. The compact form is the usual one:

-- retrofit:dml-section
-- retrofit:dml seq=1 src=hand kind=InsertStmt
INSERT INTO loan_periods (id, name) VALUES
  (1, 'weekly'),
  (2, 'monthly'),
  (3, 'quarterly'),
  (4, 'annual');
-- retrofit:dml-end
-- retrofit:dml-section-end

One marker pair per row is also valid and applies the same rows, as four records instead of one.

seq orders the records, ascending. No two records at the same point in the log may share a seq, across every data file, so start from the number the scaffold’s comments print rather than from 1. src=hand marks the record as written by hand rather than captured from a dump.

A marker line that is missing or malformed fails data check, which names the fault and the line; Framing classes lists each fault and its fix.

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

Published .