db-state-qa

What problem does it solve?

This Skill verifies that an action’s intended database side effects actually occurred by snapshotting committed DB state before and after, then producing a structural diff that matches (or contradicts) the spec.

Core Features & Use Cases

• Commit-level state verification: Snapshots live, committed rows without wrapping the test in a rollback transaction, so false approvals are avoided when changes are real but asserted incorrectly.
• Deterministic structural diffs: Captures row sets and schema-relevant information using stable ordering, normalizes volatile fields (like ids and timestamps), and diffs structurally to reduce noise.
• Async-aware validation: Supports waiting for quiescence so after-snapshots don’t race queued jobs, after-commit callbacks, or replication lag.
• Engine-appropriate introspection: Uses engine-specific catalogue queries (SQLite/PG/MySQL) and Rails ActiveRecord guidance to avoid stale schema caches and WAL/MVCC snapshot pitfalls.

Use it when you need to assert behaviors such as “a row was persisted,” “a table was not modified,” “a cached counter updated,” or “a migration added an index/constraint,” especially in scenarios driven by http-qa, cli-qa, or library-qa oracles.

Quick Start

Use db-state-qa to snapshot the database state before an action, re-run the action through the appropriate oracle surface, then snapshot again and diff the normalized results against the spec’s asserted side effects.