Safely Inspect and Change PostgreSQL Settings with pg_conftool

You will finish with a repeatable way to inspect a PostgreSQL cluster setting, change it, comment it out again, and confirm what the file contains. The examples use pg_conftool from postgresql-common version 257build1.1 on a Debian-family system.

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. Use 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 uses the system's default cluster, as determined by the PostgreSQL common configuration. That default is convenient, but it is also an easy way to inspect the wrong cluster on a host with several versions or names.

Checkpoint: confirm the target before changing anything:

$ 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 an 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 guess this path for every installation. Verify it with the cluster tooling and check that the file belongs to the cluster you intend to administer.

4. Make a small setting change

Changing a system file is an administrative action. First save a backup, 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 it is absent. Its value is one shell argument, so quote values containing spaces or shell metacharacters. The command does not decide whether PostgreSQL needs a reload or a full restart. Check the parameter's PostgreSQL documentation and apply the appropriate service operation separately.

Warning: changing listen_addresses can stop clients connecting on addresses that are no longer listed. A setting such as password_encryption affects future password changes, while authentication rules live in another file. Change only the parameter you have reviewed, and keep the backup until the service and its clients have been checked.

5. Undo a setting without deleting the line

remove comments out the matching parameter rather than deleting it. That preserves the old value as a useful 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;

Checkpoint: use show after a remove, and read the result in context. A commented line is not an active setting. 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 containing 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"

Expected output includes log_connections = on, followed by a line beginning with #log_connections after the remove. The temporary directory is not a PostgreSQL configuration directory, so this test does not alter 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 because 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 applying any service operation.

Common traps

• Using the default cluster accidentally: pass version cluster explicitly when the host has more than one cluster.
• 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 intended 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.
• Removing the only active definition and assuming the old value remains: remove comments the setting, so PostgreSQL may fall back to a different value.