{"id":4891,"date":"2026-10-01T09:02:05","date_gmt":"2026-10-01T03:32:05","guid":{"rendered":"https:\/\/cpanelfree.com\/blog\/how-to-setup-postgresql-primary-replica-replication-on-linux\/"},"modified":"2026-10-01T09:02:05","modified_gmt":"2026-10-01T03:32:05","slug":"how-to-setup-postgresql-primary-replica-replication-on-linux","status":"publish","type":"post","link":"https:\/\/cpanelfree.com\/blog\/how-to-setup-postgresql-primary-replica-replication-on-linux\/","title":{"rendered":"How to Setup PostgreSQL Primary-Replica Replication on Linux"},"content":{"rendered":"

Scaling database infrastructure beyond a single compute node is a milestone every systems engineer faces when read concurrency saturates system I\/O and CPU queues. In mission-critical Linux deployments, relying on a standalone database instance creates a critical single point of failure (SPOF) where unplanned hardware failure, kernel panics, or maintenance windows lead directly to catastrophic downtime. While staging environments on platforms like CpanelFree<\/a> allow developers to safely prototype distributed applications, setting up enterprise-grade PostgreSQL primary-replica streaming replication is the gold standard for high availability, zero-downtime read scaling, and disaster resilience.<\/p>\n

<\/p>\n

How PostgreSQL Streaming Replication Works<\/h2>\n
\n

Direct Answer:<\/strong> PostgreSQL primary-replica streaming replication functions by continuously streaming Write-Ahead Log (WAL) records from a primary read-write node to one or more read-only standby replicas over TCP port 5432. The replica’s WAL receiver process buffers these transactions and applies them immediately to disk, providing sub-millisecond replication lag, horizontal read scaling, and near-instant failover capability.<\/p>\n<\/div>\n

PostgreSQL streaming replication relies on physical block-level replication using the database engine’s Write-Ahead Log (WAL). Whenever a client executes an INSERT<\/code>, UPDATE<\/code>, or DELETE<\/code> transaction on the primary node, PostgreSQL writes the change to WAL buffers before committing the data to table heaps on disk. In streaming replication, a background process on the primary called the WAL Sender (walsender)<\/strong> transmits these WAL bytes over an authenticated TCP connection directly to the standby node’s WAL Receiver (walreceiver)<\/strong> process.<\/p>\n

Once received by the standby replica, the Startup process<\/strong> reads the incoming WAL stream and applies the exact disk page modifications in memory and to storage. Because physical streaming replication operates below the SQL parser and execution layer, it synchronizes the entire database cluster byte-for-byte, including system catalogs, indices, sequences, and table structures. When configured with Hot Standby<\/strong> mode enabled, the replica accepts concurrent read-only queries while continuously replaying changes streamed from the primary.<\/p>\n

\n

Architecture Note:<\/strong> Physical streaming replication synchronizes the entire PostgreSQL cluster (all databases within the instance). If your workload demands selective table filtering or bidirectional writes, logical replication is required instead. However, for high availability, disaster recovery, and generic read-replica pools, physical streaming replication provides superior raw throughput, minimal CPU overhead, and automated binary integrity.<\/p>\n<\/blockquote>\n

Architectural Matrix: Default vs. Tuned Production Replication<\/h2>\n

Default PostgreSQL installations out-of-the-box are deliberately tuned for minimal memory footprints and conservative system settings. Operating a high-throughput production replication cluster requires modifying Linux kernel limits, network socket buffers, and PostgreSQL concurrency handlers. The comparative matrix below outlines key differences between standard default parameters and enterprise-tuned replication architectures.<\/p>\n

\n\n\n\n\n\n\n\n\n\n\n\n
Feature \/ Metric<\/th>\nStandard \/ Default<\/th>\nTuned \/ Production<\/th>\n<\/tr>\n<\/thead>\n
Latency \/ Overhead<\/td>\nBaseline<\/td>\nOptimal<\/td>\n<\/tr>\n
Replication Mechanism<\/td>\nFile-based WAL Archiving (Delayed)<\/td>\nPhysical Streaming Replication + Slot<\/td>\n<\/tr>\n
Replication Lag (P99)<\/td>\n16MB file boundaries (seconds to minutes)<\/td>\n< 5 ms (continuous byte stream)<\/td>\n<\/tr>\n
WAL Retention Risk<\/td>\nWAL recycled if standby disconnects<\/td>\nGuaranteed retention via Replication Slots<\/td>\n<\/tr>\n
Read Query Conflict Handling<\/td>\nQueries canceled on WAL replay conflict<\/td>\nManaged via max_standby_streaming_delay<\/td>\n<\/tr>\n
Network TCP Keepalives<\/td>\nOS Default (7200s silent disconnect)<\/td>\nAggressive (idle=15s, cnt=5, intvl=5s)<\/td>\n<\/tr>\n
Failover RTO (Recovery Time Objective)<\/td>\n15\u201345 minutes (manual restore)<\/td>\n< 10 seconds (pg_ctl promote \/ automated)<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/figure>\n

Step 1: Linux Kernel and OS-Level Performance Tuning<\/h2>\n

Before launching database processes, the underlying Linux operating system must be tuned to prevent network buffer bottlenecks, out-of-memory kernel kills, and file descriptor starvation. On both the primary and replica servers (assumed Ubuntu 22.04\/24.04 or Debian 12 running PostgreSQL 16), create a dedicated kernel parameters file at \/etc\/sysctl.d\/99-postgresql.conf<\/code>.<\/p>\n

# \/etc\/sysctl.d\/99-postgresql.conf - Production Kernel Tuning for PostgreSQL\n# Virtual Memory & Memory Management\nvm.swappiness = 10\nvm.overcommit_memory = 2\nvm.overcommit_ratio = 80\nvm.dirty_background_ratio = 5\nvm.dirty_ratio = 10\n\n# Network TCP Socket Buffers for High-Throughput WAL Streaming\nnet.core.somaxconn = 4096\nnet.core.rmem_max = 16777216\nnet.core.wmem_max = 16777216\nnet.ipv4.tcp_rmem = 4096 87380 16777216\nnet.ipv4.tcp_wmem = 4096 65536 16777216\nnet.ipv4.tcp_max_syn_backlog = 8192\n\n# Fast TCP Connection Liveness & Dead Peer Detection\nnet.ipv4.tcp_keepalive_time = 60\nnet.ipv4.tcp_keepalive_intvl = 10\nnet.ipv4.tcp_keepalive_probes = 5\n\n# Shared Memory and IPC\nkernel.sched_migration_cost_ns = 5000000\nkernel.sched_autogroup_enabled = 0<\/code><\/pre>\n
Apply the kernel configuration immediately without rebooting by executing:<\/p>\n
sudo sysctl --system<\/code><\/pre>\n
Next, configure systemd resource limits to ensure PostgreSQL is never throttled by default system limits. Create a systemd drop-in override directory and configuration file at \/etc\/systemd\/system\/postgresql.service.d\/override.conf<\/code>:<\/p>\n
# \/etc\/systemd\/system\/postgresql.service.d\/override.conf\n[Service]\nLimitNOFILE=1048576\nLimitNPROC=524288\nLimitMEMLOCK=infinity\nTasksMax=infinity\nTimeoutSec=300<\/code><\/pre>\n
Reload the systemd daemon to register the unit changes:<\/p>\n
sudo systemctl daemon-reload<\/code><\/pre>\n
Step 2: Configuring the Primary PostgreSQL Node<\/h2>\n
Assume our production environment has two dedicated nodes on an isolated private VPC network:<\/p>\n