Skip to content
PtahDocs
latest

Graphic preview

100%
Page type: reference

The schema apply log

What ptah schema apply records in the target database, how a caller names a run in it, and what the record cannot be used for.

A schema apply leaves the changed tables behind and nothing that says how they got that way. ptah schema apply therefore keeps ptah_schema_apply_log in the target database, as ptah migrations up keeps the migration log: when an apply started, which plan it ran, who the caller said ran it, how it ended, and the statement it stopped at.

No command reads it. It is a table, and SQL reads it:

SELECT logged_at, run_id, state, actor, actor_origin, run_reference,
plan_name, statement_count, error_position
FROM ptah_schema_apply_log
ORDER BY logged_at, run_id, seq;

Each run writes two entries under one run_id: started before the first statement leaves, and the outcome once the apply has returned.

Column Meaning
run_id, seq The run Ptah named, and the entry’s place in it
run_reference The caller’s identifier for the run, from --run-reference
state started, then applied, failed or unknown
actor, actor_source, actor_origin The name the run was given, where Ptah got it, and the caller’s word for where the caller got it
plan_name, plan_digest A saved plan’s name, and the sha256: digest of the file the run read. Both are empty for a plan computed in the run
statement_count How many statements the plan holds
error_position, error_stmt The 1-based position and the whole text of the statement the run stopped at
error The error the run reported, as error.message of the --json document says it
logged_at When the entry was written, in UTC

The outcome is the one the apply document reports. applied and failed mean what they mean there. Every other ending of a run that sent a statement is unknown: a failure after a statement the engine could not take back, such as a schema statement on MySQL or one run with --tx-mode none, or a run whose end could not be confirmed. failed says the engine took the run’s statements back; unknown says that nothing after the first statement is confirmed.

A run that sent nothing writes nothing, and does not create the table: a dry run, a declined prompt, a refused stale plan, a view owner the server would refuse, a plan with no changes, or a failure before the first statement. The record is of statements that reached the database.

The started entry is written over the session the plan runs on. The outcome is written after the apply has returned and released its lock, over the connection pool rather than that session, so a run whose session was lost still records how it ended. Neither entry is part of the plan’s transaction: a plan that rolled back still leaves the record that it ran.

--actor names the run, as it does for ptah migrations up. It is unverified: actor_source is provided for a name the caller gave and process-user for the user the process runs as when nobody gave one.

--actor-origin is the caller’s word for where the name came from, such as admission for a name an admission controller stamped. It is one lowercase word of up to 64 characters, letters, digits, ., _, : and -, and it needs --actor: beside the process user it would describe a name the caller did not give. Ptah checks its shape and nothing else.

--run-reference is the caller’s identifier for the run, stored on both entries. Ptah Operator passes its operation ID, sha256: and 64 hex digits, so a row can be joined to the operator’s record of the change. Any string of up to 255 visible ASCII characters is accepted. A reference the column would shorten, or a character a server’s charset could replace, would name another run, so both are refused before the command connects.

ptah migrations up and ptah migrations down take the same three flags, and the migration log stores them the same way.

A failed write never fails the apply, and it changes neither the outcome nor the exit status. --json reports what the writes came to under apply_log:

apply_log Meaning
absent The run wrote no entry and tried to write none: it sent no statement, the project turned the log off, or the target is served by an executable provider
{ "written": 2, "run_reference": "sha256:…" } Both entries reached the table, carrying that reference
{ "written": 1, "lost": [ … ] } The server accepted one entry, and lost names the other

Each lost entry names its state, the server’s sqlstate or error_number where it gave one, and a message for a person. run_reference is the reference the written entries carry, and it is absent when the run was given none or nothing was written.

  • schema_apply.log: false in ptah.yaml turns it off for the project.
  • The Atlas-compatible schema apply keeps none: an Atlas user reads a database only Atlas writes, for the reason the Atlas revision format keeps no migration log.
  • A target an executable provider serves keeps none. The provider contract has no store for it yet.

It is not an audit trail. The account that applies a plan can rewrite every row of the record that it did. Tamper evidence is the database’s own audit.

It is not part of the schema. Every reader leaves the table out, together with its owner and what a default privilege grants on it. ptah schema inspect does not show it, ptah schema drift and ptah schema security do not report it, and the next plan does not drop it. A plan saved before a run created the table still applies after that run, a run that failed included. ptah db drop-all names it beside the revision tables and drops it with them.

It keeps everything. Nothing prunes it. A deployment that needs a retention rule applies its own DELETE.