How PostgreSQL matches pg_hba.conf
PostgreSQL reads pg_hba.conf from the top and uses the first line whose connection type, database, user and client address all match. The method on that line decides the outcome: reject refuses, trust admits without a password, and every other method challenges the client. A failed challenge is final—later lines are never tried—and a connection that matches no line is refused with “no pg_hba.conf entry”.
What the matcher understands
Connection types local, host, hostssl, hostnossl, hostgssenc and hostnogssenc; comma lists and quoted names; the keywords all, sameuser, samerole, replication and +role group membership; PostgreSQL 16 /regex patterns; IPv4 and IPv6 CIDRs or address/mask pairs; samehost, samenet and host names when you supply the server addresses or client host name; line continuations; and per-method options. @file lists and include directives are reported as unresolved instead of guessed.
Shadowed rules and overlaps
A line is shadowed when an earlier line covers every connection it could match—same or broader connection type, a database and user list that includes it, and an address range that contains it. Such lines are dead configuration and often hide a security assumption, such as a trust rule that never applies or a cert requirement silently bypassed by an earlier password rule. Overlaps are partial: some connections reach the later line and some are decided earlier with a different method.
Validation boundary
This is an analysis aid, not PostgreSQL. It does not read pg_ident.conf, included files, @file lists, actual role membership, DNS or server interfaces, and it does not check certificates, LDAP, RADIUS or Kerberos settings. Behaviour can change between major versions. Confirm with SELECT * FROM pg_hba_file_rules; after a reload and test real logins before relying on a change.
Frequently asked questions
How does PostgreSQL choose a pg_hba.conf line?
Lines are read top to bottom and the first line whose connection type, database, user and client address all match is used. Its method is applied; if authentication fails, PostgreSQL does not try later lines.
Why is my pg_hba.conf rule never used?
An earlier, broader line already matches every connection it could match. The detector reports such shadowed lines and the line that shadows them.
Does “all” match replication connections?
No. Physical replication connections only match lines whose database field contains the replication keyword.
Why does 192.168.1.10/24 match the whole subnet?
PostgreSQL masks host bits, so the rule matches 192.168.1.0/24. The matcher warns about this because it usually signals a typo for /32.
Authoritative references
The PostgreSQL documentation for the pg_hba.conf file, authentication methods and the pg_hba_file_rules view defines the syntax and matching rules modeled here.
Browse systems tools · Test sudoers permissions · Simulate SSH client settings