pg_disorder

Overview

Headless loadable module with no control file and no CREATE EXTENSION step; intended only for test databases; load per session with session_preload_libraries and never enable globally in production.

Version

Build

You can build the RPM / DEB packages for pg_disorder using pig build:

pig build pkg pg_disorder         # build RPM / DEB packages

Install

You can install pg_disorder directly. First, make sure the PGDG and PIGSTY repositories are added and enabled:

pig repo add pgsql -u          # Add repo and update cache

Install the extension using pig or apt/yum/dnf:

pig install pg_disorder;          # Install for current active PG version

pig ext install -y pg_disorder -v 18  # PG 18
pig ext install -y pg_disorder -v 17  # PG 17
pig ext install -y pg_disorder -v 16  # PG 16
pig ext install -y pg_disorder -v 15  # PG 15
pig ext install -y pg_disorder -v 14  # PG 14

dnf install -y pg_disorder_18       # PG 18
dnf install -y pg_disorder_17       # PG 17
dnf install -y pg_disorder_16       # PG 16
dnf install -y pg_disorder_15       # PG 15
dnf install -y pg_disorder_14       # PG 14

apt install -y postgresql-18-pg-disorder   # PG 18
apt install -y postgresql-17-pg-disorder   # PG 17
apt install -y postgresql-16-pg-disorder   # PG 16
apt install -y postgresql-15-pg-disorder   # PG 15
apt install -y postgresql-14-pg-disorder   # PG 14

Preload:

shared_preload_libraries = 'pg_disorder';

Usage

Sources:

• pg_disorder 0.1.0 README
• pg_disorder 0.1.0 metadata
• pg_disorder 0.1.0 Makefile

pg_disorder is a test-only PostgreSQL loadable module that deliberately changes the output order of eligible SELECT queries. It helps find applications and tests that accidentally depend on unspecified row order. It is a headless module: there is no control file, SQL install script, or CREATE EXTENSION pg_disorder step.

Enable It for a Test Database

Load the module at session start so its planner hook is available:

ALTER DATABASE regression_db
  SET session_preload_libraries = 'pg_disorder';

ALTER DATABASE regression_db
  SET pg_disorder.mode = 'reverse';

Reconnect after changing session_preload_libraries. Do not add this module to a production-wide shared_preload_libraries setting.

Modes

SET pg_disorder.mode = 'off';
SET pg_disorder.mode = 'reverse';
SET pg_disorder.mode = 'shuffle';
SET pg_disorder.seed = 42;
SET pg_disorder.force_serial = on;

• off leaves plans unchanged.
• reverse deterministically reverses eligible output.
• shuffle produces a deterministic permutation for a fixed session seed, submitted query text, and plan. With the default seed of zero, each session first chooses and logs a random seed.
• force_serial suppresses parallel plans to make disorder tests reproducible.

Always fix a failing query by adding a semantically correct ORDER BY; do not encode the accidental order observed under off.

Eligibility and Caveats

The hook targets top-level SELECT statements without ORDER BY. It deliberately skips query shapes where reordering is unsafe or changes SQL semantics, including aggregates, grouping, DISTINCT, set operations, window functions, recursive queries, row locks, and queries without a FROM relation.

• pg_disorder is fault-injection tooling, not a production query feature.
• Passing a disorder run does not prove every unordered query is safe; excluded query shapes and planner paths are not rewritten.
• The package installs a server module only. Verify enablement with the GUCs or module load state, not pg_extension.