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_positionFROM ptah_schema_apply_logORDER BY logged_at, run_id, seq;What a row means
Section titled “What a row means”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.
Naming the run
Section titled “Naming the run”--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.
When an entry cannot be written
Section titled “When an entry cannot be written”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.
Where Ptah keeps no such table
Section titled “Where Ptah keeps no such table”schema_apply.log: falseinptah.yamlturns it off for the project.- The Atlas-compatible
schema applykeeps 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.
What this is not
Section titled “What this is not”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.