primary_conninfo

Definition PG 18 manual

Specifies a connection string to be used for the standby server to connect with a sending server. This string is in the format described in Section 32.1.1. If any option is unspecified in this string, then the corresponding environment variable (see Section 32.15) is checked. If the environment variable is not set either, then defaults are used.

The connection string should specify the host name (or address) of the sending server, as well as the port number if it is not the same as the standby server's default. Also specify a user name corresponding to a suitably-privileged role on the sending server (see Section 26.2.5.1). A password needs to be provided too, if the sender demands password authentication. It can be provided in the primary_conninfo string, or in a separate ~/.pgpass file on the standby server (use replication as the database name).

For replication slot synchronization (see Section 47.2.3), it is also necessary to specify a valid dbname in the primary_conninfo string. This will only be used for slot synchronization. It is ignored for streaming.

This parameter can only be set in the postgresql.conf file or on the server command line. If this parameter is changed while the WAL receiver process is running, that process is signaled to shut down and expected to restart with the new setting (except if primary_conninfo is an empty string). This setting has no effect if the server is not in standby mode.

How it works

Sets the connection string to be used to connect to the sending server. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

The WAL receiver uses this libpq connection string to reach an upstream sender. Reloading a changed nonempty value restarts the receiver; credentials should come from a protected passfile where possible, and slot synchronization additionally requires dbname.

Monitor and change primary_conninfo together with max_wal_senders, max_replication_slots, wal_level. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Operational considerations

Embedding a plaintext password in broadly readable configuration or process diagnostics.

Omitting dbname when slot synchronization needs it.

Changing upstream identity without coordinating timeline and slot state.

Changing it on the wrong primary, standby, sender, or subscriber role.

Watching only configured bytes/time instead of actual lag, slot position, and worker state.

Workload guidance

OLAP: Read standbys and logical subscribers often see long queries or large transactions. Put explicit bounds on replay/apply and monitor lag, worker saturation, slot restart_lsn, and conflict cancellations.

OLTP: Size primary_conninfo from topology, failover roles, slot/subscription count, and reconnect headroom. Test worst-case primary latency, standby replay, and disk retention before production.

SMALL: Configure only replication capacity that is actually used. Even a small topology needs bounded timeouts and slot lifecycle; unlimited retention is not reliability.