PostgreSQL tuning is a resource-allocation problem, not a list of popular values copied from a blog. pg-configurator turns CPU, RAM, storage, workload duty, replication, and server version into a candidate whose assumptions and calculation rules can be reviewed.

The payoff

Teams get a repeatable starting point and a clear review diff: every setting records where it came from, why it has that value, and whether applying it requires a reload, reconnect, restart, or manual work.

Real tasks it helps with

Provision a new server

Produce a coherent first candidate for a 16-core, 64 GiB primary instead of tuning memory, workers, WAL, and connections independently.

Review a major upgrade

Select the target PostgreSQL major and inspect settings that appeared, disappeared, or changed defaults between versions.

Standardize a fleet

Generate the same schema-versioned JSON contract in CI for every hardware class, then review only intentional differences.

Plan replication and WAL

Make replica count, outage tolerance, peak WAL rate, disk budget, PITR, and synchronous commit intent explicit inputs.

From facts to a candidate

Calculation flow
CPU  RAM  storage  DB size  workload  PG major  topology
 |    |      |        |        |         |         |
 +----+------+--------+--------+---------+---------+
                         |
                         v
              normalize + validate inputs
                         |
       +-----------------+------------------+
       | memory | workers | WAL | locks | I/O |
       +-----------------+------------------+
                         |
                         v
            version rules + safety invariants
                         |
        +----------------+----------------+
        |                |                |
        v                v                v
 postgresql.conf   Patroni JSON   pg_configurator/v1 JSON

Output and inspection modes

Mode Use it when Result
conf A DBA wants a readable PostgreSQL configuration fragment Formatted name = value settings
json Automation needs typed inputs, rules, warnings, and apply modes pg_configurator/v1 artifact
patroni-json The settings will enter a Patroni configuration workflow Patroni-compatible parameter mapping
History An upgrade review needs version-to-version GUC evidence All-setting or single-setting history
Profiles A known workload needs ordered, validated overrides Candidate plus override provenance

Generate a candidate

pg-configurator \
  --db-cpu=16 \
  --db-ram=64Gi \
  --db-size=500Gi \
  --db-disk-type=SSD \
  --db-duty=mixed \
  --replication-mode=physical \
  --pg-version=18 \
  --available-extensions=pg_stat_statements,auto_explain \
  --output-format=json \
  --out candidate.json

Know the boundary

The output is an empirical candidate, not a benchmark-proven optimum and not an instruction to edit production immediately. Validate it on a representative stand, compare it with current effective settings, load-test the change, and review every restart-level parameter before rollout.

GitHub repository ↗ PyPI package ↗