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.

How a command picks its schema

A retrofit project can hold one schema or many. Every schema has four properties; the CLI’s job is to map a verb invocation to a single registered schema by reading those properties.

  • Name: the registry key. Case-insensitive (PostgreSQL unquoted-identifier rule).
  • Oplog root: the directory holding the schema’s <name>.oplog file. It is [[schema]].oplog_root in retrofit.toml, else [project].oplog_root, else the project root.
  • Scope: directories that resolve to this schema. Implicit from the oplog root, plus optional explicit overlays in the top-level [directory_scope] TOML table.
  • Default pin: default_schema in retrofit.toml. Last resort for schema-context verbs.

The resolver chain

Every schema-context verb (op*, snapshot, migrate, reconcile, drift, import, schema move, schema engine, schema scope add, schema set-default) runs the same six-step chain. The first step that returns a schema wins:

  1. --schema <name> flag.
  2. -f <path> (mutex with --schema). With a registry, looks up [[schema]] by path; without a registry, opens the file directly.
  3. [directory_scope] longest-prefix match against cwd.
  4. Implicit oplog-dir longest-prefix match (the oplog root).
  5. default_schema fallback.
  6. Refuse with default-schema-unset.

In a single-schema project, step 5 does the work and the user types nothing. In a monorepo where each schema’s oplog lives in its own subdir, step 4 does; again there is nothing to type. The [directory_scope] table at step 3 is the explicit overlay when your source dirs and oplog dirs don’t line up.

--chdir, -C <path> is the root-persistent flag that reroots cwd for the whole run. It affects steps 3 and 4, the retrofit.toml discovery walk, and any relative path passed to a verb.

Never silent at resolution

Every schema-context verb names its resolved schema:

  • Text mode: the registered schema-context advisory renders as a note: schema-context: <name> line on stderr before the verb’s main output.
  • JSON mode: a "schema":"<name>" field on the terminal {"type":"ok",...} envelope.

-f <path> is a path-as-identity selector: in a project it resolves the registered [[schema]] at that path (step 2) and the verb names it; only a registry-less -f run, which reads the file directly, names no schema. In CI, set RETROFIT_REQUIRE_EXPLICIT_SCHEMA=1 to refuse with explicit-schema-required when neither --schema nor -f is passed. The default is permissive so single-schema projects keep zero ceremony.

Three lazy-create doors

Scaffolding a new schema does not need a schema create first. Three authoring entry points lazy-create the schema when the explicitly named schema isn’t yet registered:

  • retrofit import --schema <new> <source>: mints the oplog, registers [[schema]], auto-pins default_schema on the first-ever schema, then imports the DDL.
  • retrofit op add CreateSchema <new>: the bare-form symmetry path.
  • retrofit schema create <new> [<location>] [--scope <dir>...] [--is-default] [--engine-version <X>]: the rich-form authoring path with project-setup flags.

Lazy-create fires only on an explicit name; a schema the resolver chain reaches is already registered. A typo on --schema mints a new schema; recovery is schema remove. See Work with several schemas for the typical flows. To unregister a schema whose database is gone and keep its oplog, see Retire a schema.

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

Published .