Technology · Discipline

Schema and migration discipline

Forward-only migrations, schema contracts and a baseline frozen as immutable. Schema is a contract, and I treat it that way.

PostgreSQL work graphAgentOS governanceA compiler for workflow changes
The schema and the views drawn from it
generated views;
an edited one (orange)
is thrown away
  • 79forward-only migrations
  • 88tables in the work graph
  • 33schema contracts

Forward-only, never edited

AgentOS keeps the state of every work order in its database, so the schema is the law of the system, and I put it under strict discipline. The PostgreSQL work graph is built by forward-only migrations, immutable once applied, so the schema history is also the history of the system's rules.

baseline · frozen
applied
applied
edited in place · never
applied
the correction, appended

The Markdown and YAML files agents read are generated from the database and edits to them are discarded, so the schema is the one place the truth can change and drift has no second source of truth to hide in.

Workflow law through a compiler

I gave workflow law the same treatment. A change to the workflow is a declarative specification handed to a transition compiler, never hand-written SQL, and every compiled change is qualified on an isolated database first. After a frozen baseline the compiler also assigns migration ordinals, so ordering comes from the tool.

1
declarative specification
2
complete, deterministic bundle
3
isolated PostgreSQL · qualified
4
the real database

New workflow law enters only through the compiler, and that keeps the transition runtime deterministic as it grows.

A backup before every step

No migration runs without a backup, and neither does any other invasive operation. Schema changes are checked against a canonical snapshot of the current schema. Why long agent runs fail explains why the state lives in the database at all.

One migration, start to finish
backup
apply
probe against the snapshot
The probes confirm the change left no residue. Segment lengths are illustrative.

I run schema change on a governance system the way I would on a regulated database: immutable history, compiled changes, isolated qualification and a backup before every step.