How to configure pg_hba.conf in PostgreSQL

A pg_hba.conf change controls which clients can start new PostgreSQL sessions. A broad match in the wrong position can expose a database to more users than intended, while a strict match can block the application or administrator that still needs access.

PostgreSQL checks host-based authentication records in order for each new connection. The active file can live outside the data directory, so get it from the running server with SHOW hba_file;, back it up, put specific matches above broader matches, and validate the saved file through pg_hba_file_rules before reload.

The HBA file does not make the server listen on remote interfaces or open firewalls; it only decides what authentication rule applies after a client reaches PostgreSQL. Prefer scram-sha-256 for password authentication, keep explicit loopback or trusted-subnet rules above any catch-all reject records, and test both an allowed and rejected new TCP connection after reload.

1. Print the active pg_hba.conf path from the running server.

   $ sudo -u postgres psql -Atc 'SHOW hba_file;'
   /etc/postgresql/18/main/pg_hba.conf

2. Create a backup copy of the active pg_hba.conf file before editing.

   $ sudo cp -a /etc/postgresql/18/main/pg_hba.conf /etc/postgresql/18/main/pg_hba.conf.bak

   Use the path printed by SHOW hba_file; on your server. Debian and Ubuntu package paths include the PostgreSQL major version, while source or container builds may place the file under the data directory.

3. Open the active pg_hba.conf file with sudo privileges.

   $ sudoedit /etc/postgresql/18/main/pg_hba.conf

4. Add a specific allow rule for the intended database, role, and client network near the top of the file.

   # TYPE  DATABASE  USER     ADDRESS           METHOD
   host    appdb     appuser   192.0.2.0/24      scram-sha-256

   Records are whitespace-separated fields. local records use TYPE, DATABASE, USER, and METHOD; TCP records add the ADDRESS field.

   Roles need SCRAM-stored passwords and SCRAM-capable clients before a scram-sha-256 HBA rule works.

5. Put single-host entries above broader subnet entries when both can match the same client.

   # A single host should appear above a broader subnet match.
   host    appdb     appuser   192.0.2.40/32     scram-sha-256
   host    appdb     appuser   192.0.2.0/24      scram-sha-256

   Use hostssl instead of host only when server-side SSL is enabled and the rule must require encrypted TCP connections.

6. Keep trusted loopback or subnet rules above catch-all rejects.

   # Allow the application subnet and local TCP clients first.
   host    appdb     appuser   192.0.2.0/24      scram-sha-256
   host    all       all       127.0.0.1/32      scram-sha-256
   host    all       all       ::1/128           scram-sha-256
   
   # Reject every other TCP client.
   host    all       all       0.0.0.0/0         reject
   host    all       all       ::/0              reject

   A broad allow rule above specific entries can silently widen access, and a catch-all reject blocks loopback TCP unless explicit 127.0.0.1/32 and ::1/128 rules appear above it.

7. Check the saved file for HBA parse errors before applying it.

   $ sudo -u postgres psql -c 'SELECT line_number, error FROM pg_hba_file_rules WHERE error IS NOT NULL;'
    line_number | error
   -------------+-------
   (0 rows)

8. Reload PostgreSQL to apply the updated pg_hba.conf rules without restarting the server.

   $ sudo -u postgres psql -c "SELECT pg_reload_conf();"
    pg_reload_conf
   ----------------
    t
   (1 row)

   Existing sessions remain connected. New connection attempts use the reloaded HBA rules.

   Related: How to manage the PostgreSQL service with systemctl on Linux

9. Test a TCP connection that should be allowed by the new rule from a host inside the permitted network.

   $ psql "host=database.example.net dbname=appdb user=appuser sslmode=require" -c 'SELECT current_user, inet_client_addr();'
    current_user | inet_client_addr
   --------------+------------------
    appuser      | 192.0.2.40
   (1 row)

10. Test a TCP connection that should be rejected from an untrusted client.

    $ psql "host=database.example.net dbname=appdb user=appuser sslmode=disable" -c 'SELECT 1;'
    psql: error: connection to server at "database.example.net" (192.0.2.10), port 5432 failed: FATAL:  pg_hba.conf rejects connection for host "203.0.113.55", user "appuser", database "appdb", no encryption

    If a client cannot reach the server at all, check listen_addresses, host firewall rules, network ACLs, and routing before changing pg_hba.conf again.