DBReduce

Give DBReduce a PostgreSQL database and a failing test.
It finds a smaller relational dataset that still reproduces the same bug.

DBReduce reduces PostgreSQL data while checking that each candidate preserves the original failure identity. It supports output matchers and structured JSON verdicts, keeps oracle writes out of accepted data, and follows both PostgreSQL foreign keys and explicitly configured application relationships.

Quick start

DBReduce requires Python 3.13 or newer, PostgreSQL, and client tools (pg_dump and pg_restore) compatible with your server. Install it with:

python -m pip install dbreduce

Then reduce a database with a test that identifies the bug:

dbreduce reduce \
  --database postgresql://localhost/app_bug \
  --oracle 'uv run pytest tests/test_checkout.py::test_negative_total' \
  --match-stdout 'AssertionError: negative total' \
  --confirm 3

The oracle must connect through DATABASE_URL or DBREDUCE_DATABASE_URL. DBReduce sets both variables to its disposable workspace for every run. Use a database role with CREATEDB permission. The source database is read only; reductions and oracle executions run against a generated copy. Use trusted commands and dumps: SQL functions, triggers, and external services can have effects outside that copy.

For an oracle that can report a stable signature directly, use --oracle-json and have it write {"reproduced": true, "signature": "checkout-negative-total"} to stdout. See the guide for the verdict protocol and safety details.

Version 0.3.0 adds --oracle-framed-json for applications that log to stdout, --restore-jobs N for parallel custom-archive restores, and an experimental, opt-in PostgreSQL 17/18 --candidate-backend clone. Snapshot isolation remains the default. Clone mode verifies a final logical restore before publishing SQL.

What it does

• Checks failure identity so an unrelated error does not count as reproducing the bug.
• Isolates each oracle run so its database writes do not affect later candidates.
• Reduces through real foreign keys and declared single or composite relationships.
• Reports the final identity, candidate outcomes, timings, and row counts without saving raw oracle output.

Without an identity matcher, legacy mode accepts any nonzero application exit status and prints a warning. The result is locally irreducible under attempted relationship-closed transformations; DBReduce does not promise a global minimum. By default, DBReduce writes dbreduce.min.sql and dbreduce-report.json and never overwrites existing files.

Real-world validation

DBReduce v0.2.0 and v0.3.0 were validated with real Wagtail and NetBox schemas and application oracles. Wagtail's surrounding data was generated application noise, not a production dump. The 1,335-row NetBox database was reconstructed; the issue author's exact dump is unavailable. A separate v0.3.0 run used the official NetBox 4.1 demo dump as a public alternative and passed a fresh restore check. NetBox validation exercised its form path, not a full HTTP flow:

Wagtail #9208
150,706 rows
    v
DBReduce
    v
3 rows

same failure preserved
fresh restore verified

NetBox #17498
1,335 rows
    v
DBReduce
    v
2 rows

same failure preserved
fresh restore verified

See the real-world validation report and case studies for commands, environment, performance numbers, and limitations.

See CHANGELOG.md for release history.

Documentation

• Usage, oracle identity, configuration, safety, and development
• Benchmark and demo
• Real-world validation report
• PostgreSQL isolation investigation

Project links

• Repository
• Issues
• PyPI

Licensed under Apache-2.0.