Postgres image

The autopg image wraps the official PostgreSQL image with a small Python tool that configures the server to the machine it runs on. It is a drop-in replacement: same Postgres, same data directory, same entrypoint behaviour. The only thing that changes is the postgresql.conf you would otherwise write by hand.

What it is

The stock postgres image ships conservative defaults that assume almost nothing about the host. On a real server that means shared_buffers left tiny, parallelism switched off, and planner costs tuned for spinning disks. autopg removes that step. It detects the hardware, picks values appropriate for your workload, and writes the config before Postgres starts.

The tuning logic is a direct port of pgtune, the well-known Postgres configuration calculator. If a value differs from what pgtune would produce for the same inputs, that is treated as a bug.

What happens on startup

When the container boots, autopg runs build-config before handing off to Postgres:

  1. Detect the host. CPU count and total memory come from the container's view of the machine. Disk type is read from /sys/block/*/queue/rotational on Linux, falling back to SSD assumptions when it cannot be determined.
  2. Read your overrides. Any AUTOPG_* environment variables you set take precedence over what was detected.
  3. Calculate the config. Memory settings, connection limits, parallelism, WAL sizing, and planner costs are computed for the workload type.
  4. Write postgresql.conf. The previous config is preserved as postgresql.conf.base so nothing is lost.
  5. Start Postgres with the tuned configuration.

Because the config is written at boot, moving the same image to a bigger box and restarting is all it takes to re-tune. There is nothing to copy between machines.

Image tags

Images are published to the GitHub Container Registry, tagged by Postgres major version:

ghcr.io/piercefreeman/autopg:pg18-latest
ghcr.io/piercefreeman/autopg:pg17-latest
ghcr.io/piercefreeman/autopg:pg16-latest
ghcr.io/piercefreeman/autopg:pg15-latest
ghcr.io/piercefreeman/autopg:pg14-latest

The tuning is version-aware. Settings that changed across Postgres releases are emitted correctly for the version in the tag.

Compatibility

Everything you know about the official image still works:

  • POSTGRES_USER, POSTGRES_PASSWORD, and POSTGRES_DB behave identically.
  • The data directory lives at /var/lib/postgresql/data. Mount a volume there to persist it.
  • You can mount your own postgresql.conf to /etc/postgresql/postgresql.conf to extend or override the generated one. Your values win.

pg_stat_statements

autopg enables the pg_stat_statements extension by default. It is added to shared_preload_libraries, created on first boot, and configured to track all statements. This captures per-query execution stats with no application changes and is what the diagnostics dashboard reads from. Set AUTOPG_ENABLE_PG_STAT_STATEMENTS=false to turn it off.