Versions and compatibility
This page says how a build is numbered, what may change between two
releases, and which lines of the oplog and
retrofit.toml decide whether a build reads a project.
Version numbers
| Version | Build |
|---|---|
X.Y.Z | a release, such as 0.10.0 |
X.Y.Z-wip.N | a WIP build toward the release X.Y.Z, such as 0.11.0-wip.33 |
Before 1.0 each release raises the minor and sets the patch to 0: the
release after 0.10.0 is 0.11.0, and the WIP builds toward it are
0.11.0-wip.N. N counts WIP builds across every release and is never
reset: 0.10.0-wip.31 was followed by 0.11.0-wip.32.
Releases and WIP builds
A release is published on GitHub as a release, and a WIP build as a pre-release.
- The install script installs the latest release. Its
--versionflag installs a named release and--wipthe newest WIP build; see Install script. - On Homebrew, the
MonotonicHQ/tap/retrofitcask installs the latest release and theMonotonicHQ/tap/retrofit@wipcask the newest WIP build. The two casks conflict, so one is installed at a time; see Try a WIP.
Before 1.0
Before 1.0 no release promises compatibility with an earlier one. A release may change any command, flag, output shape, exit code, error or advisory code, or the oplog format.
The release notes list every such change. A change to the oplog’s operators, parameters, headers or seal bytes is listed under the release’s Log format heading, with what it means for an existing log: usually that the log is regenerated.
One build writes the same bytes for the same oplog on every machine and
every run (Principles § 5). Two
releases need not: the SQL snapshot and migrate emit for one oplog can
differ between them.
What decides whether a build reads a project
The version number does not decide it. Four header lines open every
oplog, and retrofit.toml names a schema_version:
# retrofit-oplog-format: 1
# retrofit-model-version: 1
# engine-version: 17
# retrofit-oplog-form: merge
| Line | What it names | This build reads |
|---|---|---|
# retrofit-oplog-format: | the version of the oplog’s wire format | 1 |
# retrofit-model-version: | the version of the operator catalog | 1 |
# engine-version: | the PostgreSQL major the schema is pinned to | a major PostgreSQL versions lists |
# retrofit-oplog-form: | the oplog’s form, merge or compact | merge or compact |
schema_version in retrofit.toml | the version of the config’s layout | "1" |
Before 1.0 a change to the log leaves both version numbers at 1 and is
listed under Log format instead. A log an earlier build wrote can hold
1 and still fail: 0.10.0 added the # retrofit-oplog-form: line, and a
log without it fails with oplog-form-header-missing.
When this build cannot read a line:
- A newer oplog format. Every command that reads a log whose
# retrofit-oplog-format:is above1fails withoplog-format-too-new.snapshot,migrate,identifyanddata listexit 2 withio-error, andimportexits 1 withparse-error, each namingoplog-format-too-newin its message. - An older oplog format. A value below
1fails withoplog-format-too-old, through the same codes. No command converts a log from one format to another. The Log format entry of the release that changed the format says what to do, usually regenerating the log. - A newer model version. A log whose
# retrofit-model-version:is above1still parses, andop showprints it, but it cannot be written or rendered.op add,op revise,op sealandreconcilefail withmodel-version-too-new;snapshot,migrateandelement listfail withrender-blocked-on-unknowns;validateendsunverifiable(exit 2). - An unknown engine version. A major this build does not know fails
with
unknown-engine-version; see PostgreSQL versions. - A missing or unknown form. A log without a
# retrofit-oplog-form:line fails withoplog-form-header-missing, and a value other thanmergeorcompactwithunknown-oplog-form. - A newer config. Every command that reads a
retrofit.tomlwhoseschema_versionis above"1"fails withconfig-schema-too-new(exit 2). Any other value, or none, fails withconfig-invalid(exit 1).
Under the same numbers, a log a newer build wrote can hold an operator or
a retrofit-* header key this build does not know. An unknown operator
fails with unknown-operator, which snapshot, migrate, identify
and data list name inside io-error. An unknown header key fails
writes with writes-blocked-on-unknowns and renders with
render-blocked-on-unknowns, and validate ends unverifiable. The
output contract gives the exit
status of each code.
What retrofit --version prints
retrofit --version
retrofit version 0.10.0 (65304cfdee81c33b78f400be435721c8bde3d9de, 2026-10-31T02:18:54Z)
The line names the build’s version, the full commit it was built from,
and that commit’s date in UTC. A WIP build prints the same line with its
X.Y.Z-wip.N version.