Diagnose PostgreSQL connection, authentication and HBA rules

Understand the likely causes

• Transport can fail before PostgreSQL authentication is reached. Once reached, the first HBA rule matching connection type, client address, database and role selects authentication, with no fallback after failure. A socket connection using peer can differ from TCP using SCRAM. Later permission errors concern database or object authorization, not necessarily a bad password.

Confirm the intended transport and target

Record where the client runs, the explicit host or socket path, port, database, role and TLS requirement. With libpq on Unix, an omitted host commonly selects a Unix socket, whereas host=localhost requests TCP; do not copy MySQL’s localhost assumptions. Containers may not share socket directories or network namespaces. Compare the failing application configuration with approved deployment evidence rather than trying arbitrary endpoints or restarting services. No new connection is established by this editorial guide.

Inspect a known authorized session

An existing authorized training session can reveal server and identity context. inet_client_addr() may be NULL for a Unix-domain socket, which is expected rather than a missing client error. These values do not expose the password or prove the separate application connection follows the same route. Record the result privately and compare it with the intended deployment contract. The examples are non-runnable and were not executed against a configured server during authoring.

SELECT version(), current_database(), session_user, current_user,
 inet_client_addr(), inet_server_addr(), inet_server_port();

Read the selected HBA rule and file errors

An authorized administrator can inspect pg_hba_file_rules to review parsed file records and syntax errors. This view reflects the current file contents, which may differ from the rules last loaded by the server; a clean view alone does not prove a reviewed edit is active. Follow include order and first matching rule semantics. If that rule’s authentication fails, PostgreSQL does not try a later permissive rule. Keep operating-system-specific reload behavior in the separate administration procedure.

SELECT rule_number, line_number, type, database, user_name,
 address, auth_method, error
FROM pg_hba_file_rules ORDER BY rule_number;

Repair the failing layer narrowly

Correct the client endpoint if it targets the wrong listener or namespace. For an HBA mismatch, have the authorized owner review the exact client range, role, database, ordering and required TLS method through the normal change process. For a SCRAM failure, verify credential provisioning and connector capability without adding trust or all-address access. PostgreSQL 18 deprecates MD5 password support, so consult its migration guidance. After login succeeds, inspect CONNECT, schema USAGE and table grants separately if access is still denied.

Keep it from recurring

• Keep host, database, role, TLS and authentication requirements explicit. Test supported SCRAM-capable clients, manage secrets outside source text and review HBA order after changes. Separate runtime and administrator identities, and document container socket boundaries and the exact server version.