Safely Inspect and Change PostgreSQL Settings with pg_conftool

pg_conftool gives you a repeatable way to inspect a PostgreSQL setting, change it, and comment it back out. The examples use pg_conftool from postgresql-common version 257build1.1 on a Debian-family system, and cover checking what the file actually contains at each step.

Allow about 15 minutes. You need a shell and access to the cluster configuration. Reading a system configuration is usually unprivileged; changing a file under /etc/postgresql normally needs sudo. This command edits files only: it does not reload PostgreSQL or restart a service for you.

1. Identify the cluster and read one setting

The installed machine has PostgreSQL 16 cluster main. Put the version and cluster name before the command:

$ pg_conftool 16 main show listen_addresses
listen_addresses = 'localhost,172.17.0.1'

The two positional arguments select the cluster. If you omit them, pg_conftool falls back to the system's default cluster. That default is convenient, but it is also an easy way to inspect the wrong cluster on a host running several versions or names.

$ pg_lsclusters
Ver Cluster Port Status Owner    Data directory              Log file
16  main    5432 online postgres /var/lib/postgresql/16/main  /var/log/postgresql/postgresql-16-main.log

Your status, port and paths may differ. If the command is unavailable, install the distribution package that provides pg_conftool; do not substitute a similarly named PostgreSQL utility.

2. Choose concise or script-friendly output

By default, show prints the parameter name and an equals sign. Add --short when another command needs only the value:

$ pg_conftool --short 16 main show listen_addresses
localhost,172.17.0.1

For a boolean parameter, --boolean formats the result as on or off:

$ pg_conftool --boolean 16 main show shared_buffers
shared_buffers = off

The boolean option is not for show all. Use show all when you need every parameter present in the selected file, but expect a long result and avoid treating its order as a stable interface for scripts.

3. Inspect a file by explicit path

You can name a configuration file directly. When the argument is a path, the version and cluster arguments are ignored. This is useful for a carefully chosen file, and for testing a change without touching the live cluster:

$ pg_conftool /etc/postgresql/16/main/postgresql.conf show listen_addresses
listen_addresses = 'localhost,172.17.0.1'

The usual file for the cluster shown above is /etc/postgresql/16/main/postgresql.conf. Do not assume that path for every installation: verify it with the cluster tooling and check the file belongs to the cluster you intend to administer.

4. Make a small setting change

Changing a system file is an administrative action. Save a backup first, then set one parameter with sudo:

$ sudo cp --preserve=mode,ownership,timestamps \
    /etc/postgresql/16/main/postgresql.conf \
    /etc/postgresql/16/main/postgresql.conf.before-pg-conftool
$ sudo pg_conftool 16 main set listen_addresses 127.0.0.1
$ pg_conftool 16 main show listen_addresses
listen_addresses = 127.0.0.1

set updates an existing setting or adds it when absent. Its value is one shell argument, so quote anything containing spaces or shell metacharacters. The command does not decide whether PostgreSQL needs a reload or a full restart; check the parameter's own documentation and apply the right service operation separately.

5. Undo a setting without deleting the line

remove comments out the matching parameter rather than deleting it, which preserves the old value as a record and lets PostgreSQL fall back to its default or another active definition:

$ sudo pg_conftool 16 main remove listen_addresses
$ grep -n 'listen_addresses' /etc/postgresql/16/main/postgresql.conf
60:#listen_addresses = 127.0.0.1		# what IP address(es) to listen on;

If you need an exact rollback of a larger edit, restore the backup only after checking that no other administrator has changed the file:

$ sudo diff -u \
    /etc/postgresql/16/main/postgresql.conf.before-pg-conftool \
    /etc/postgresql/16/main/postgresql.conf
$ sudo cp --preserve=mode,ownership,timestamps \
    /etc/postgresql/16/main/postgresql.conf.before-pg-conftool \
    /etc/postgresql/16/main/postgresql.conf

Restoring a file is a state-changing action. Afterward, verify the file and perform any required PostgreSQL reload or restart deliberately. Do not restore an old copy over a file that holds somebody else's newer changes.

6. Use a temporary file before touching production

A copy in a temporary directory lets you verify the command syntax and the resulting text without administrative access:

tmpdir=$(mktemp -d /tmp/pg-conftool-test.XXXXXX)
cp /etc/postgresql/16/main/postgresql.conf "$tmpdir/postgresql.conf"
pg_conftool "$tmpdir/postgresql.conf" set log_connections on
pg_conftool --boolean "$tmpdir/postgresql.conf" show log_connections
pg_conftool "$tmpdir/postgresql.conf" remove log_connections
grep -n 'log_connections' "$tmpdir/postgresql.conf"
printf 'Test file: %s\n' "$tmpdir"

Expect log_connections = on, followed by a line starting #log_connections after the remove. The temporary directory is not a PostgreSQL configuration directory, so this test does not touch a running server.

7. Edit interactively only when needed

The edit command opens the selected configuration file in $EDITOR; if that variable is unset, it uses vi:

$ sudo env EDITOR=vi pg_conftool 16 main edit

Prefer set or remove for one-parameter changes: they leave a narrow, inspectable diff. If you use edit, save the file, exit the editor, then run pg_conftool ... show parameter and inspect the diff before any service operation.

Common traps

• Hitting the default cluster by accident. Pass version cluster explicitly when the host has more than one.
• Confusing the file with live server state. pg_conftool changes text on disk, not the running PostgreSQL process.
• Expecting --short to change show all. It is for a single value, and --boolean is explicitly not for show all.
• Passing a path and cluster selectors together. A path makes the selectors irrelevant, so make the target obvious in the command.
• Assuming the old value survives a remove. remove comments the setting, so PostgreSQL may fall back to a different value.