Why this matters more than its roadmap position suggests
discover and audit are things you run twice against a database and then stop running. That is fine, and it is what the tool was built for — but it means the tool leaves.
check --baseline is what makes it stay. Record the accepted state once, then fail the build when a migration introduces a relationship nobody declared, or when one that was confirmed becomes broken. That turns a one-off diagnosis into a guard that runs on every pull request.
Shape
pgfathom check --baseline .pgfathom/baseline.json compares the current schema against a recorded state and exits non-zero on regression.- The baseline is the existing versioned JSON contract, so nothing new has to be specified for it.
- The exit codes have to distinguish "found a regression" from "could not run", because CI treats those the same otherwise and a broken connection would read as a clean build. The exit code table already exists in
cli-foundation and this extends it.
Open questions
What counts as a regression. A new undeclared relationship is arguably a finding, not a failure — legacy schemas grow. The interesting default is probably: a confirmed relationship becoming broken always fails; a new candidate is reported and configurable.
Sampled runs cannot confirm. A baseline recorded under --full and checked under sampling would report false regressions. The check should refuse to compare across validation modes rather than compare them badly.
Cost in CI. Full validation on a large schema is minutes and load on somebody's database. There is probably a mode that checks only the relationships already in the baseline, which is a much smaller query set than discovery.
Why this matters more than its roadmap position suggests
discoverandauditare things you run twice against a database and then stop running. That is fine, and it is what the tool was built for — but it means the tool leaves.check --baselineis what makes it stay. Record the accepted state once, then fail the build when a migration introduces a relationship nobody declared, or when one that was confirmed becomes broken. That turns a one-off diagnosis into a guard that runs on every pull request.Shape
pgfathom check --baseline .pgfathom/baseline.jsoncompares the current schema against a recorded state and exits non-zero on regression.cli-foundationand this extends it.Open questions
What counts as a regression. A new undeclared relationship is arguably a finding, not a failure — legacy schemas grow. The interesting default is probably: a confirmed relationship becoming broken always fails; a new candidate is reported and configurable.
Sampled runs cannot confirm. A baseline recorded under
--fulland checked under sampling would report false regressions. The check should refuse to compare across validation modes rather than compare them badly.Cost in CI. Full validation on a large schema is minutes and load on somebody's database. There is probably a mode that checks only the relationships already in the baseline, which is a much smaller query set than discovery.