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.
Related
retrofit data: everydatacommand, the data file’s format and each refusal.- Emit the schema as SQL: emit the schema with its reference rows and the datasets you name.
- Emit a migration script: emit a migration with seed rows.
- Import existing SQL: the rows import sets aside in data files.