Skip to main content

Revisions — the migration journal

Every database carries its own migration journal: which script of which revision was applied, by whom, and whether it was later rolled back. Migration tools normally track this in an ordinary user table; owning the engine buys a guarded record instead — the journal lives next to the catalog, outside the table namespace, and no SQL statement can erase or rewrite an entry.

SHOW REVISIONS;   -- revision, script, hash, direction, note, applied_at, applied_by

The full history, oldest first. A script's current state is its latest entry: up means applied, down means rolled back. As an admin, name the database instead (the journal is management metadata, like the catalog):

SHOW REVISIONS FROM acme;   -- admin-only

RECORD REVISION​

RECORD REVISION 2 SCRIPT '01-tables.sql' HASH 'a3f9…';        -- applied
RECORD REVISION 2 SCRIPT '01-tables.sql' HASH 'a3f9…' DOWN;   -- rolled back
RECORD REVISION 2 SCRIPT '01-tables.sql' HASH 'a3f9…' NOTE 'why';  -- with an audit note

Appends one entry — typically issued by a tool (the studio's publish) right after the script itself succeeded. The engine guards the state machine:

  • a script goes up only if it is not currently applied;
  • it comes down only if it is, and only with the applied hash;
  • a rollback is a new entry, never an erasure — the history stays honest, and the same script may go up again afterwards (with a fixed hash if the file changed).

Every RECORD lands in the node's event ring as an audit line stamped with the acting user. The journal file (revisions.json) sits in the database's directory: backups carry it, DROP DATABASE removes it with everything else.