0then0
EN

Databases and data files

DBReduce

From a production-sized dump to a bug report you can attach. Shrink a PostgreSQL database to the few rows and tables that still reproduce a failing test.

Release
v0.5.1, Oct 31, 2026
Runs on
Python 3.10–3.15; PostgreSQL 13–18 with matching pg_dump, pg_restore and psql
License
Apache-2.0
Get startedView source
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
Example invocation from the project README: a pytest oracle, matched by its assertion message and confirmed three times. It writes dbreduce.min.sql and dbreduce-report.json and never overwrites existing files.
Wagtail #9208
Rows:             150,706 -> 3
Tables:           48 -> 1
Failure identity: preserved
Fresh SQL restore: PASS
A result reported in the project’s real-world validation report: a Wagtail bug reproducer reduced with an application oracle on PostgreSQL 17, using the optional schema reduction.

What it does

Give DBReduce a PostgreSQL database and a command that fails because of a bug. It removes rows, following foreign keys and the relationships you declare, and keeps only candidates where the same failure still happens. Optionally it also removes whole tables. The result is a small SQL file that reproduces the bug.

Who it is for

  • Developers who need a minimal reproducer for a data-dependent bug.
  • Maintainers who receive bug reports that only fail on someone’s database.

Limitations

  • The oracle runs against a disposable copy, but SQL functions, triggers and external services can still have side effects. Use trusted commands and dumps.
  • Needs a database role with CREATEDB.
  • DBReduce does not promise a global minimum; reports state when local irreducibility cannot be claimed.

Typical uses

Reduce a failing test case

Point DBReduce at a copy of the database and your test command, and match the failure by its output or a JSON verdict so an unrelated error does not count.

Share a safe reproducer

The output is dbreduce.min.sql plus a report with row counts and timings, without raw test output.

Install

Latest stable release v0.5.1, published Oct 31, 2026. Release notes. Release data checked Oct 31, 2026 from GitHub Releases.

Install from PyPI

uv tool install dbreduce

Package page: pypi.org/project/dbreduce/

First run

  1. Install the CLI as a standalone tool:

    uv tool install dbreduce
dbreduce --help

  2. Make sure your test reads the database URL from DATABASE_URL or DBREDUCE_DATABASE_URL.

  3. Run dbreduce reduce with a matcher that identifies the bug, then attach dbreduce.min.sql to the bug report.

Platforms and how they were checked

  • PostgreSQL 13–18Builds and passes automated checks in CI

    Snapshot isolation by default; the clone backend is experimental and needs PostgreSQL 15+.

  • Python 3.10–3.15Builds and passes automated checks in CI

    Installed as a standalone tool; your application can be in any language.

Questions and bug reports go to the project’s issue tracker. Report security problems as described in its security policy.