retrofit
0.13.0
retrofit.sh

Work with several schemas

A project can hold any number of schemas. Each is a [[schema]] row in retrofit.toml with its own oplog, the log of operators the schema is recorded in, in a file named <name>.oplog. A command that works on one schema picks it the way every command does (The resolver chain), and in the common layouts you type nothing to choose it.

Add a schema

schema create registers a schema and writes its oplog. Pass an optional directory (an existing one, or a path ending in / to create) and any project-setup flags:

retrofit schema create billing                                      # → ./billing.oplog
retrofit schema create sales ./services/sales/                      # → ./services/sales/sales.oplog
retrofit schema create audit ./audit/ --engine-version 17           # → ./audit/audit.oplog

The directory that holds a schema’s oplog is already that schema’s scope. In a monorepo where each schema’s source code sits beside its oplog, running any command from inside services/sales/ picks sales with no further configuration.

retrofit import --schema <name> and retrofit op add CreateSchema <name> register a schema the project does not hold yet as well (Three lazy-create doors).

Scope a schema to other directories

When source directories and oplog directories do not line up, scope the schema to the directories you work in, with --scope on schema create:

retrofit schema create sales ./services/sales/ \
    --scope ./services/sales \
    --scope ./src/sales \
    --is-default

This writes a top-level [directory_scope] table:

[directory_scope]
"services/sales/" = "sales"
"src/sales/" = "sales"

Now retrofit op add ... run from src/sales/ picks sales without --schema. Add or remove entries later:

retrofit schema scope add ./tests/sales --schema sales
retrofit schema scope remove ./src/sales

Run from inside a directory already scoped to the schema, schema scope add needs no --schema. schema scope remove takes only the directory.

Change the default schema

The first schema a project registers becomes its default_schema, the one a command picks when nothing else names a schema. Pin another, or remove the key, without editing retrofit.toml by hand:

retrofit schema set-default sales
retrofit schema set-default --unset      # remove the key entirely

With no default, a command run where no scope matches needs --schema <name> or -f <path>, and exits non-zero without one.

Move a schema’s oplog

When a project’s layout changes, schema move renames the oplog file and rewrites the schema’s oplog_root in one step:

retrofit schema move ./different/ --schema sales

The oplog is now ./different/sales.oplog: the file name is always <name>.oplog in its directory. The file is renamed, not rewritten, so every byte of it is unchanged. [directory_scope] entries name schemas, not paths, so they stay as they were.

Retire a schema

When a schema’s database is gone, unregister the schema and keep its oplog. Remove each directory scoped to it (retrofit validate lists them), then the schema, and commit:

retrofit schema scope remove ./services/sales
retrofit schema scope remove ./src/sales
retrofit schema remove sales --keep-oplog
git commit -am "Retire the sales schema"

schema remove drops the schema’s [[schema]] row from retrofit.toml, and default_schema with it when the schema held the pin. schema list no longer shows it, -f with its oplog’s path exits non-zero, and so does --schema sales on a command that does not register a schema. The oplog file stays where it was, and the repository’s history keeps every committed revision of it. A directory left scoped to the removed schema makes retrofit validate exit non-zero. Without --keep-oplog, schema remove deletes the oplog file, whatever it holds.

Nothing in the oplog records that the schema ended. Opened outside the project (Read an oplog file outside the project), the file reads as a live history, and migrate emits SQL from it as from any other. Inside the project, retrofit validate warns about the file on every run, since no [[schema]] row names it. The name is free again: each of the lazy-create doors, retrofit import --schema sales among them, registers a new sales schema with an oplog of its own, except schema create sales in the directory that holds the kept file, which exits non-zero while the file is there.

Choose the schema for one command

  • --schema <name> on any command that works on one schema picks that schema. Pass it or -f, not both.
  • -f <path> picks the registered schema whose oplog is at that path. A path no [[schema]] row names exits non-zero.
  • --chdir, -C <path> runs the whole command as if from that directory: the schema it picks, the retrofit.toml it finds and any relative path you pass.

In CI, set RETROFIT_REQUIRE_EXPLICIT_SCHEMA=1 so a command that is given neither --schema nor -f exits non-zero rather than falling through to default_schema.

Read an oplog file outside the project

Run outside a project (no retrofit.toml in the directory or above it), -f opens the file directly. To read an oplog the project does not register, say a previous revision extracted with git show HEAD~1:sales.oplog > /tmp/old.oplog to reverse changes the current log no longer holds, combine -C with -f:

retrofit migrate -C /tmp -f /tmp/old.oplog --from seal --to last --down

-C decides whether the run is outside the project, not the file’s path, so -C names a directory with no retrofit.toml above it (a sibling temporary directory works; a subdirectory of the project does not). The file itself may be anywhere, inside the project included. Without -f, a run inside the project reads the registered oplog, which is a different file.

See which schema each directory picks

retrofit validate lists the directory scopes the project resolves:

retrofit validate
resolved scope:
  services/sales/ → sales (directory_scope)
  src/sales/ → sales (directory_scope)
  services/billing/ → billing (implicit-oplog-dir)
  audit/ → audit (implicit-oplog-dir)

A directory can appear twice, once from [directory_scope] and once as an oplog’s directory; on two matches of the same length, the [directory_scope] entry wins.