One-click install
npx skills add https://github.com/kylesnowschwartz/ralph-ban --skill db-state-qa
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: db-state-qa
Source: https://github.com/kylesnowschwartz/ralph-ban/tree/main/skills/db-state-qa
Command: npx skills add https://github.com/kylesnowschwartz/ralph-ban --skill db-state-qa

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

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.

Frequently Asked Questions about db-state-qa

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I verify database side effects in integration tests without rollback transactions giving false approvals?

Verify database side effects by snapshotting committed DB state before and after an action, then diffing the resulting rows and schema information. This avoids false approvals caused by rollback transactions by checking live, committed rows directly.

What is database state diffing and how does it handle volatile fields like timestamps?

Database state diffing captures row sets and schema information using stable ordering, then normalizes volatile fields like ids and timestamps to reduce noise. This deterministic structural diff reliably matches or contradicts your spec's asserted persistence behaviors.

How do I test Rails ActiveRecord schema changes and avoid stale schema caches in PostgreSQL or SQLite?

Test Rails ActiveRecord schema changes using engine-specific catalogue introspection for PostgreSQL, SQLite, and MySQL. This approach avoids stale schema caches and WAL/MVCC snapshot pitfalls by querying the database catalogue directly rather than relying on cached schema data.

Does database state verification support asynchronous callbacks and queued background jobs?

Database state verification supports waiting for quiescence so after-snapshots don't race queued jobs, after-commit callbacks, or replication lag. This async-aware validation ensures the snapshot captures all committed changes reliably before diffing.

Can I use database snapshot diffing to assert that a specific table was not modified during an action?

You can use database snapshot diffing to assert the absence of modification by comparing pre-action and post-action snapshots. If the structural diff shows no changes for the target table, the verification reliably approves the spec's assertion.

What are the limitations of snapshot-based database side effect testing?

Snapshot-based database side effect testing requires deterministic snapshots with stable ordering, volatile-field normalization, and quiescence-aware timing. Without proper engine-specific catalogue introspection and timing control, asynchronous jobs or MVCC snapshot pitfalls can cause unreliable verdicts.