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>.oplogfile. It is[[schema]].oplog_rootinretrofit.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_schemainretrofit.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:
--schema <name>flag.-f <path>(mutex with--schema). With a registry, looks up[[schema]]by path; without a registry, opens the file directly.[directory_scope]longest-prefix match against cwd.- Implicit oplog-dir longest-prefix match (the oplog root).
default_schemafallback.- 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-contextadvisory renders as anote: 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-pinsdefault_schemaon 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.