Rollout definition and state
Every key of a ptah migrations rollout definition, the validation rules, the order targets run in, and the stage, target and run statuses the state file records.
A ptah migrations rollout definition names the target databases and the
stages that group them, and the state file records what happened to each. Look
up a definition key, a validation rule, the order targets run in, or what a
status means. Roll a release out in stages is
the workflow.
Definition file
Section titled “Definition file”A definition is one YAML document with two top-level keys, targets and
stages. Decoding is strict: an unknown key, a repeated key, a value of the
wrong type, an empty file and a second document are refused.
Target keys
Section titled “Target keys”| Key | Required | Meaning |
|---|---|---|
name |
yes | Identifies the target in every report. Letters, digits, ., _ and -, up to 64 characters, starting with a letter or digit. |
url |
one of url and url_env |
The database URL, in the form ptah migrations up --db-url takes. |
url_env |
one of url and url_env |
The environment variable holding the database URL. It must be set when the definition is read. |
config |
no | A project config file for this target’s run, passed as --config. Relative to the definition file. |
expect_sequence |
no | This target’s approved migration sequence, passed as --expect-sequence. Relative to the definition file. |
allow_destructive |
no | true passes --allow-destructive to this target’s run. Defaults to false. |
A target’s URL never reaches a report. Reports show it with its password and
secret parameters replaced, as ptah migrations up displays one, and take the
same secrets out of every line a target’s run writes.
Stage keys
Section titled “Stage keys”| Key | Required | Meaning |
|---|---|---|
name |
yes | Identifies the stage. The same characters as a target name. |
targets |
yes | The members, by target name, in the order they start. |
depends_on |
no | Stages that must succeed before this one starts. |
canary |
no | true marks the canary stage. |
concurrency |
no | How many members run at once. Defaults to 1. |
on_failure |
no | stop, the default, or continue. |
require |
no | How many members must succeed: all, the default, a count such as 2, or a percentage such as 50%, rounded up. |
Validation rules
Section titled “Validation rules”ptah migrations rollout plan and every run and resume check the whole
definition before anything runs, and report every broken rule in one error:
- target and stage names are words as described above, each declared once;
- a target sets exactly one of
urlandurl_env, and the variable is set; configandexpect_sequencename files that exist;- two targets do not address one database endpoint with the same connection
options and the same
config; credentials do not count, and two spellings of one endpoint, such aspostgres://andpostgresql://, count as two; - a stage names only targets in the inventory, and names at least one;
- every target belongs to exactly one stage;
depends_onnames existing stages, never the stage itself, and forms no cycle; a cycle is reported with its path, such asx -> y -> x;concurrencyis at least one,on_failureisstoporcontinue, and a count inrequireis no more than the stage’s members;- at most one stage is the canary, the canary depends on no stage, and every other stage depends on the canary directly or through another stage.
Stages run one at a time. A stage runs after every stage it depends on; between
stages ready at the same time, the one declared first runs first. Within a
stage, members start in the order targets lists them, at most concurrency
at once, each as soon as a slot frees.
A stage starts only when every stage in its depends_on succeeded. Otherwise
it is blocked, and so is every member that has not run. A stage outside the
dependency chain of a failed stage still runs.
Target statuses
Section titled “Target statuses”| Status | Meaning |
|---|---|
not-started |
The rollout has not started this target, or a resume will run it again. |
running |
Its run is in progress, or was when the rollout stopped. A resume reads its revision table. |
succeeded |
Its run applied every migration it selected, or a resume found every migration of the release applied. |
no-op |
Its run found nothing pending. |
failed |
Its run stopped before it sent a statement, or at a migration that committed nothing. |
partial |
Its failed migration committed some statements and not the rest. |
unknown |
Nothing says what happened: no run document, an unreadable revision table, or a dirty row without counts. |
skipped |
Not started because its stage stops after a failure. |
blocked |
Not started because a stage its stage depends on did not succeed. |
succeeded and no-op count toward a stage’s require. failed, partial
and unknown are failures, and a stage with on_failure: stop starts nothing
further after one. The status comes from the run document of
ptah migrations up --json, whose outcome reads the revision table after the
run; the process exit status is not consulted.
Stage statuses
Section titled “Stage statuses”| Status | Meaning |
|---|---|
not-started |
The rollout has not reached the stage. |
running |
Members are running, or an interrupt left members not started. |
succeeded |
Every member has an outcome, and the successes meet require. |
failed |
Every member has an outcome, and the successes do not meet require. |
blocked |
A stage it depends on did not succeed. blocked_by names it. |
Run statuses
Section titled “Run statuses”| Status | Meaning |
|---|---|
running |
The run is in progress, or its process ended without recording an outcome. |
succeeded |
Every stage succeeded. The command exits 0. |
failed |
Every stage the run could reach is decided, and one failed or was blocked. The command exits 1. |
interrupted |
A signal, or a state file that could not be written, stopped the run before every stage was decided. |
State file
Section titled “State file”The state file is one JSON document, written when run starts and replaced
after every change, so a process that dies leaves the last thing it recorded.
--json prints the same document on standard output. Its top-level fields:
| Field | Meaning |
|---|---|
contract_version |
1. A reader refuses a version it does not know. |
status |
The run status. |
definition |
The definition path the last invocation read. |
plan |
The plan digest: a SHA-256 over every stage and target setting, with each URL in its display form. |
release |
kind (directory or oci), source as named, digest, and for an artifact the digest-pinned reference. |
ptah_version |
The version of the ptah binary of the last invocation. Every target run of an invocation uses that binary. |
invocations |
How many times the run was started or resumed. |
stages |
Every stage in execution order, with its settings, status, succeeded, blocked_by and targets. |
Each target carries its settings, status, attempts, started_at and
finished_at, the version keys its last run planned and applied, the
version its revision table records, and the run’s error and failure
objects as ptah migrations up --json reports them. note says why a status
is what it is when the run’s own outcome does not: a skip, a block, or what a
resume read back.
Release identity
Section titled “Release identity”| Release | Identity |
|---|---|
| Local directory | The content digest of every file the run captured, by path and bytes. It is the digest Ptah Operator binds a plan to, so it allows at most 1000 files. |
oci:// reference |
The manifest digest the reference named when the run started. Each target pulls that digest, not the tag. |
resume binds again and refuses a release whose kind or digest differs from the
recorded one. Naming the same artifact by its digest where the run named a tag
is the same release.
Environment
Section titled “Environment”Each target’s run inherits the rollout’s environment and working directory. The
rollout refuses to start while any of these is set, whatever its value:
PTAH_ALLOW_DIRTY, PTAH_SKIP_CHECKS, PTAH_ALLOW_DESTRUCTIVE,
PTAH_EXPECT_SEQUENCE, PTAH_DRY_RUN, PTAH_LIMIT, PTAH_TO_VERSION and
PTAH_EXEC_ORDER. Each would waive a target’s guard or change what its run
does for every target at once.
A target’s run does not inherit the variables other targets’ url_env name,
nor PTAH_DB_URL. It receives its own URL as PTAH_DB_URL, and under its own
url_env name when it has one, so a hook or config program it starts holds no
other target’s credentials.
The rollout passes the database URL in the run’s environment rather than on its
command line, and passes --migrations-dir, --json, --log-format=text and
an empty --metrics-addr as flags, which outrank the corresponding variables.
Exit codes
Section titled “Exit codes”| Code | Meaning |
|---|---|
0 |
Every stage succeeded. |
1 |
The rollout ran, and a stage failed or was blocked. The state file says which target did what. |
2 |
Refused before any target ran: an invalid definition, a refused variable, a state file that exists for run or is missing for resume, a held lock, or a plan or release that does not match the state. |
128+N |
Interrupted by a signal. The state file says interrupted. |