pg_hba.conf generator

These connection type keywords control which TCP/IP connections a rule matches based on encryption status. host matches any TCP/IP connection, whether encrypted or not — it is the broadest and least secure option for remote access. hostssl matches only connections made over SSL/TLS, rejecting unencrypted attempts; this is the recommended default for production because it ensures data in transit is encrypted. hostnossl matches only unencrypted connections — it exists mainly to apply different auth methods to encrypted vs. unencrypted connections, but in practice you should rarely need it. hostgssenc (PostgreSQL 12+) matches connections encrypted with GSSAPI encryption, which is used in Kerberos environments. There is also local, which matches Unix domain socket connections only — these never traverse the network and are inherently safe from eavesdropping, making peer authentication a natural fit. For any rule that handles connections over a network (even a private one), prefer hostssl over host. If your PostgreSQL server has SSL configured (which it should for any production deployment), switching from host to hostssl costs nothing in performance and eliminates the possibility of an unencrypted connection slipping through.

PostgreSQL evaluates pg_hba.conf rules strictly from top to bottom and uses the first rule that matches the connection's type, database, user, and address. There is no "best match" algorithm, no weighting, and no fallthrough — the first match is the only match. This first-match-wins behavior means rule ordering is critical for security. A common mistake is placing a broad rule like host all all 0.0.0.0/0 scram-sha-256 above a narrow reject rule like host all all 10.0.99.0/24 reject — the broad rule matches first, and the reject rule is never reached. The correct pattern is: place reject rules first, then the most specific allow rules (individual IPs with /32), then progressively broader subnet rules, and finally a catch-all reject at the bottom. Another ordering mistake involves the local keyword: local rules only match Unix socket connections and do not overlap with host rules at all, so their ordering relative to host lines does not matter — but ordering among multiple local rules still matters. When in doubt, test your configuration with select * from pg_hba_file_rules() (PostgreSQL 10+), which shows the parsed rules in evaluation order and flags any syntax errors without needing a reload.

scram-sha-256 is the recommended password-based method for PostgreSQL 10+ and the default since PostgreSQL 14. It uses a salted challenge-response protocol that never sends the password over the wire (even without SSL) and stores only a cryptographic verifier in pg_authid, not a reversible hash. Use it for any connection that authenticates with a password. md5 is the legacy password method — it is weaker because the md5 hash stored in the catalog can be brute-forced offline, and the over-the-wire challenge can be replayed under certain conditions. Migrate away from md5 unless you have clients that do not support SCRAM. cert (client certificate authentication) is the strongest option for service-to-service connections: the client presents a TLS certificate signed by your CA, and PostgreSQL verifies it and extracts the common name (CN) as the user name. It eliminates passwords entirely and works well in automated deployments. peer is for local Unix socket connections only — it asks the OS kernel for the connecting process's user ID and matches it to a PostgreSQL role name (with optional mapping via pg_ident.conf). It is the natural choice for DBA access from the database server itself. Other methods: gss for Kerberos/Active Directory environments, ident for TCP connections where an ident server is running (rare today), reject to explicitly deny matching connections, and trust which should never appear in production — it grants access with no authentication whatsoever.

Changes to pg_hba.conf take effect after a configuration reload — you do not need a full server restart. The safest approach is: first, edit the file and save it. Second, verify the syntax before reloading by running select * from pg_hba_file_rules() (PostgreSQL 10+), which parses the file and shows any errors in the error column without applying the changes. Third, reload the configuration using one of these methods: from a SQL session run select pg_reload_conf(), from the command line run pg_ctl reload -D /path/to/data, or send a SIGHUP signal to the postmaster process. The reload is non-disruptive — existing connections are not dropped and continue using the authentication rule they originally matched. Only new connections will be evaluated against the updated rules. There is one exception: if you change SSL-related parameters in postgresql.conf (like ssl_cert_file or ssl_key_file), those also take effect on reload for new connections since PostgreSQL 9.1+, but changing the ssl parameter itself from off to on requires a restart. Always keep a backup of the working pg_hba.conf before editing, and test the reload from a separate session so you can revert if you accidentally lock yourself out.