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, theretrofit.tomlit 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.
Related
- Schema identity and the resolver: how a command picks its schema, step by step.
- Create a project: a project with one schema, from the start.
- Exclude objects the project does not own: keep a provider’s schemas and tables out of the oplog.