listen_addresses

Definition PG 18 manual

Specifies the TCP/IP address(es) on which the server is to listen for connections from client applications. The value takes the form of a comma-separated list of host names and/or numeric IP addresses. The special entry * corresponds to all available IP interfaces. The entry 0.0.0.0 allows listening for all IPv4 addresses and :: allows listening for all IPv6 addresses. If the list is empty, the server does not listen on any IP interface at all, in which case only Unix-domain sockets can be used to connect to it. If the list is not empty, the server will start if it can listen on at least one TCP/IP address. A warning will be emitted for any TCP/IP address which cannot be opened. The default value is localhost, which allows only local TCP/IP “loopback” connections to be made.

While client authentication (Chapter 20) allows fine-grained control over who can access the server, listen_addresses controls which interfaces accept connection attempts, which can help prevent repeated malicious connection requests on insecure network interfaces. This parameter can only be set at server start.

How it works

listen_addresses sets the host name or IP address(es) to listen to. The server binds the listed interfaces at startup; reachability still depends on port, pg_hba.conf, host firewalls, and network routing.

listen_addresses is a POSTMASTER-context setting: PostgreSQL reads it during server startup, and a configuration reload or session SET cannot activate a new value.

The listener endpoint combines listen_addresses and port at startup, while pg_hba.conf, TLS, firewalls, routing, and service discovery determine which clients can use it.

Operational considerations

Expecting a reload or SET to activate listen_addresses, although it requires a controlled server restart.

Assuming a bound address or port grants access; pg_hba.conf and operating-system or network controls still apply.

Changing a startup-only endpoint without updating discovery, health checks, firewalls, clients, and the administrative recovery path.

Changing listen_addresses globally without a rollback plan and a client or operational compatibility test.

Workload guidance

OLAP: Use an explicit analytical endpoint or network when isolation is required, but keep connection information consistent across failover targets.

OLTP: Set listen_addresses from the service topology and expose only required interfaces or ports. Validate poolers, health checks, pg_hba.conf, firewalls, failover, and restart sequencing together.

SMALL: Prefer local-only exposure unless remote access is required. Preserve a tested administrative route before changing listen_addresses and restarting.