Skip to content
PtahDocs
latest

Graphic preview

100%
Page type: reference

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.

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.

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.

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.

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 url and url_env, and the variable is set;
  • config and expect_sequence name 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 as postgres:// and postgresql://, count as two;
  • a stage names only targets in the inventory, and names at least one;
  • every target belongs to exactly one stage;
  • depends_on names existing stages, never the stage itself, and forms no cycle; a cycle is reported with its path, such as x -> y -> x;
  • concurrency is at least one, on_failure is stop or continue, and a count in require is 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.

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.

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.
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.

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
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.

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.

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.