Skip to content
PtahDocs
latest

Graphic preview

100%
Page type: reference

The migration log

What ptah migrations log records, what it cannot be used for, and why a rollback no longer erases the fact that a version was applied.

The revision table answers what is applied. It cannot answer what happened: a completed rollback deletes the row, so a database that was on version 43 yesterday and is on 42 today reads exactly like one that never reached 43.

The migration log answers the second question. It is an append-only table beside the revision table, written by ptah migrations up and ptah migrations down, and read by ptah migrations log. ptah schema apply keeps a log of its own, the schema apply log.

The log records every attempt of a versioned or a repeatable migration. An entry about a repeatable migration carries its identity in the repeatable column and version 0, and ptah migrations log prints it as R__<identity>. The record table of repeatable migrations keeps only the last attempt of each, which is what ptah migrations status reads.

Terminal window
ptah migrations log --db-url "$DATABASE_URL"
stdout
STARTED VERSION OPERATION OUTCOME ACTOR SOURCE
2026-09-21T06:11:04Z 43 down rolled_back release-bot provided
2026-09-21T05:58:12Z 43 up applied release-bot provided
2026-09-21T05:57:40Z 43 up failed release-bot provided

Each attempt writes two entries: one when it starts and one when it ends. The reader pairs them, so an attempt that never gained an outcome is reported as undetermined — a run whose process was killed, lost its connection or had its container stopped says nothing about whether its work landed, and inferring success from a missing failure would be a claim nobody can support.

A write to the log can fail on its own, so an attempt can keep its outcome and lose its start. The reader keeps that attempt, because the outcome is the only record it has. The STARTED column prints -, and --json sets start_lost and leaves out started_at. The other fields come from the outcome, which names the same run, version, actor and checksum.

The entries are written on the pool connection rather than inside the migration’s transaction, which is the point: a migration that failed and rolled back still leaves the record that it was attempted. A log written inside the transaction would describe only the runs that succeeded.

--json prints the same attempts with the start and finish timestamps, the run identifier, the checksum of the migration that ran, and the error. An attempt of a repeatable migration also carries repeatable, its identity. Start and finish timestamps are recorded in UTC, including when the applying process uses another time zone.

A MySQL or MariaDB URL does not need parseTime=true. Without it the driver hands back a time as the server’s text, which carries no zone, and Ptah reads that text the way the driver does with the parameter: in the zone the URL’s loc parameter names, or UTC without one. ptah migrations log, ptah migrations status and ptah migrations tag print the same values with or without the parameter. Measured on MySQL 8.4 and 26.10 and on MariaDB 10.11 and 12.3.

ClickHouse keeps tag changes in a ReplacingMergeTree table. Tag reads use FINAL, so a move or removal is visible before background merges finish. Oracle stores tag versions as NUMBER(19) and moves a tag with MERGE.

Under tx-mode all the whole batch is one transaction, so every migration in it gets an entry opened before the transaction starts and they all settle with the same outcome. Recording one of them applied when a later one rolls the batch back would describe a database that never existed.

ptah migrations down --plan derives its rollback from the schema difference instead of running the authored down bodies. It deletes the same revision rows, so it records the same attempts.

--actor names the run. It is unverified by construction — a name on a command line is what somebody wrote — so the log stores where the name came from beside it:

Source Meaning
provided the caller supplied the name, through --actor or PTAH_ACTOR
process-user nobody supplied one, so the user the process runs as was recorded
unknown neither was available

Storing an unverified name and an observed one the same way is how a log becomes evidence for something it cannot support.

--actor-origin is the caller’s word for where the name came from, such as admission for a name an admission controller stamped, so a stamped name reads differently from a typed one. It is stored in actor_origin, only beside a name the caller supplied, and it needs --actor. Ptah checks its shape and nothing else: one lowercase word of up to 64 characters, letters, digits, ., _, : and -.

run_id is Ptah’s own name for a run, such as 28-dmth8umhdwq7, and a caller has no way to know it in advance. --run-reference stores the caller’s identifier for the run on every entry the run writes, beside run_id. Ptah Operator passes its operation ID, sha256: and 64 hex digits, so a row joins the operator’s record of the change instead of being matched by version, actor and time.

Any string of up to 255 visible ASCII characters is accepted. A longer one, or one holding a space or a character outside ASCII, is refused before the command connects: a reference the column shortened, or a charset replaced, would name another run.

The run document reports the reference the written entries carry as migration_log.run_reference, and ptah migrations log --json reports run_reference and actor_origin on each attempt. A run given no reference stores none, and neither document names one.

A migration log kept by an executable provider has no column for either value. The entries are written without them, the run warns once, and the run document leaves migration_log.run_reference out rather than report a reference the log does not hold.

Ptah v0.26.0 and earlier created the log without run_reference and actor_origin, and an older log also lacks repeatable. The first run that writes an entry adds the columns the table lacks, as nullable columns, before the entry. The rows already there keep their values and read back with none of them. Reading never alters the table, so an account that may only read runs ptah migrations log against an old table as it stands. An account that may not alter the table loses the run’s entries, and the run reports them as it reports any lost entry. Measured on PostgreSQL 18, MySQL 26.10, MariaDB 12.3, ClickHouse 26.10, CockroachDB 26.3, YugabyteDB 2026.1 and Oracle Free 23.

A write to the log can fail: the server refuses the value, the account may not create the table, or the connection is gone. The migration goes on, because stopping a migration over its note would turn an investigation aid into an outage. Nothing in the table can record that it was not written to, so the run reports it:

  • ptah migrations up --json and ptah migrations down --json name each lost entry under migration_log in the run document, against the migration it belongs to. A table with no rows then has two different readings, and the document says which one applies.
  • Without --json, both commands close with a notice that names the migrations, after the line that says the run succeeded.
  • A program using the library asks Migrator.MigrationLogReport.

The exit status does not change. A lost entry says nothing about the migration: the revision table says what is applied, and a run that exits 0 applied what it selected. A nonzero status would send a caller to retry, the retry would find nothing left to do, and the entry would stay lost. A caller that treats a lost record as a problem reads migration_log.lost.

An entry is sent as the run holds it. Ptah does not shorten an actor to fit the 256 characters of its column, or replace a character the database’s charset cannot hold, because a record that names somebody else is worse than no record. The server refuses such an entry, and it is lost and reported like any other. The measured answers are 22001 on PostgreSQL for a name that is too long, 1406 on MySQL and MariaDB, 3988 on MySQL and 1366 on MariaDB for a character the charset cannot hold.

MySQL and MariaDB log inserts use strict mode for that statement, even when the connection’s sql_mode is not strict. The server then refuses a name it would shorten or change, and migration_log.lost reports the entry. Migration SQL still runs with the connection’s chosen mode.

It is not an audit trail. The table lives in the database it describes and is writable by the account that runs migrations: whoever can apply a migration can edit the record of having done so. Tamper evidence is a different design.

It is not a second source of truth. ptah migrations status remains the answer to where the database stands, and nothing reads the log to decide the current version. A reader that had to reconcile two tables to learn that would be worse off than with no log at all.

It keeps everything. Rows are small and nothing prunes them. A deployment that needs a retention rule applies its own DELETE.

A destructive clean destroys it. ptah db drop-all names the log table in the plan it asks you to confirm, beside the revision table, and drops it with the rest.

migration.log: false in the project config keeps the table out of a database entirely: nothing creates it, and ptah migrations log says logging is off for the run rather than printing an empty table. The Atlas-compatible revision format keeps no log whatever the setting says: that contract defines one table, and a second one Ptah added would appear in a database an Atlas user believes only Atlas writes. The two are different settings, so the command names the one that applies.

The table is created by the first entry written, not by the initialization that creates the revision table. An account that may read and not create can run ptah migrations log against a database that has no log yet.