pg_hba.conf: first match wins

pg_hba.conf is not a policy engine. It is an ordered list, and the server stops reading at the first line that matches the connection in front of it. That line decides the authentication method, and if that method fails or the line says reject, the connection is refused. No later line is consulted.

Almost every surprising access outcome in PostgreSQL follows from that single sentence.

The columns

# TYPE   DATABASE   USER         ADDRESS          METHOD    [OPTIONS]
host     all        demo_scram   127.0.0.1/32     scram-sha-256

All four of the first columns must match for the line to apply. +groupname is worth noting: it matches any role that is a member of that role, which is how you write rules against a group rather than enumerating individuals.

First match wins, demonstrated

Two experiments on the same live cluster, differing only in the order of two lines.

Order A — the broad rule above the specific one:

local   all   all                       trust
host    all   all         127.0.0.1/32  reject
host    all   demo_scram  127.0.0.1/32  scram-sha-256

$ PGPASSWORD=... psql -h 127.0.0.1 -U demo_scram -d postgres -c 'SELECT 1'

psql: error: connection to server at "127.0.0.1", port 5432 failed:
FATAL:  pg_hba.conf rejects connection for host "127.0.0.1", user "demo_scram",
      database "postgres", no encryption

Order B — the same three rules, specific one first:

local   all   all                       trust
host    all   demo_scram  127.0.0.1/32  scram-sha-256
host    all   all         127.0.0.1/32  reject

$ PGPASSWORD=... psql -h 127.0.0.1 -U demo_scram -d postgres -tAc 'SELECT current_user'

demo_scram

Same rules, same connection, opposite outcomes. That is the whole lesson, and it is why reasoning about this file by eye is unreliable once it exceeds a handful of lines.

Making the evaluation observable

Two mechanisms remove the guesswork.

The connection log names the matching line. With log_connections enabled, PostgreSQL records the file and line number of the rule that authenticated the connection:

$ docker logs rbpg-auth | grep 'connection authenticated'

LOG:  connection authenticated: user="postgres" method=trust (/var/lib/postgresql/18/docker/pg_hba.conf:2)
LOG:  connection authenticated: identity="demo_scram" method=scram-sha-256 (/var/lib/postgresql/18/docker/pg_hba.conf:2)

pg_hba_file_rules shows the parsed rule set, in order, with any parse errors, without reloading:

psql -U postgres -c \
  "SELECT rule_number, line_number, type, database, user_name,
          address, auth_method, error
     FROM pg_hba_file_rules ORDER BY rule_number"

The error column is the important one. It reports a line the server could not parse before you reload, which turns a potential lockout into a query result. Checking it is the single most valuable habit in this lesson.

Here it is catching a real mistake — a peer method on a host line, which cannot work because a TCP connection carries no operating-system identity:

$ psql -U postgres -c 'SELECT line_number, type, auth_method, error FROM pg_hba_file_rules WHERE error IS NOT NULL'

 line_number | type | auth_method |                         error
-------------+------+-------------+--------------------------------------------------------
         4 |      |             | peer authentication is only supported on local sockets
(1 row)

Note that type and auth_method are empty for a line that failed to parse: the server could not interpret it, so it has nothing to report about it beyond the error and the line number. An empty result from this query is the pass condition.

Changing the rules safely

pg_hba.conf is re-read on reload, so changes are cheap to apply and cheap to get wrong.

# 1. Keep a copy you can restore in one step
cp "$(psql -U postgres -tAc 'SHOW hba_file')" /var/backups/pg_hba.conf.$(date -u +%Y%m%dT%H%M%SZ)

# 2. Edit, then check the parse BEFORE reloading
psql -U postgres -c \
  "SELECT line_number, type, database, user_name, address, auth_method, error
     FROM pg_hba_file_rules WHERE error IS NOT NULL"

# 3. Reload
psql -U postgres -c 'SELECT pg_reload_conf()'

# 4. Confirm the server accepted it
psql -U postgres -c \
  "SELECT count(*) AS rules_with_errors FROM pg_hba_file_rules WHERE error IS NOT NULL"

# 5. Test the connection you changed, from where it actually comes from

Step 2 is what prevents a lockout: pg_hba_file_rules reads the file from disk and reports parse errors while the server is still running the previous, working rule set.

What the official container image ships

Worth knowing, because it is what most people meet first:

$ grep -vE '^#|^$' $PGDATA/pg_hba.conf

local   all             all                                     trust
host    all             all             127.0.0.1/32            trust
host    all             all             ::1/128                 trust
local   replication     all                                     trust
host    replication     all             127.0.0.1/32            trust
host    replication     all             ::1/128                 trust
host    all             all             all                     scram-sha-256

Anything arriving over the loopback interface or the Unix socket is trusted without a password. Connections from elsewhere need SCRAM.

For a disposable lab container that is a sensible default. It becomes a problem when the same image is used for something long-lived and another process on the same host — or another container sharing the network namespace — can reach the loopback address.

Production discipline

1. Order the file from most specific to most general. A broad rule above a specific one makes the specific one dead code.
2. Check pg_hba_file_rules for errors before every reload. It reads the file while the server still runs the working rule set.
3. Enable log_connections so the matching rule is recorded. The file and line number settle disputes that otherwise become arguments.
4. Keep a local peer rule as the safety rope, so a mistake in the network rules does not lock you out of the host.
5. Never widen the method to diagnose. Widen the address on a rule that still authenticates, and only temporarily.
6. Copy the file before editing it. Restoring is then one cp and a reload.

Cross-course references

• Secrets, PKI & Certificate Management — Part VII (TLS for operators) covers what hostssl actually requires of the client, and Part XI (SSH) covers the analogous ordered-rule reasoning in sshd_config.
• Linux for Production Sysadmins — Part XXV (Firewall) covers the same first-match-wins semantics in nftables, and Part XXVI (SSH) covers keeping an out-of-band route in before changing access rules.
• Ansible for Production Sysadmins — Part XVII (Templates) covers generating this file from a source of truth, which is how the ordering stops being accidental.

Quiz