---
title: "Deploy PostgreSQL HA Failover"
description: "PostgreSQL 18 HA: automated failover, read replica, zero configuration"
category: "Storage"
url: https://railway.com/deploy/postgresql-ha-failover
---

# Deploy PostgreSQL HA Failover

PostgreSQL 18 HA: automated failover, read replica, zero configuration

**[Deploy PostgreSQL HA Failover on Railway](https://railway.com/template/postgresql-ha-failover)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/postgresql-ha-failover/manifest.json

- **Creator:** wotonews
- **Category:** Storage

## Template content

### pgaf-monitor

- **Image:** wotonews/postgres-ha:v0.3.0

### pgaf-primary

- **Image:** wotonews/postgres-ha:v0.3.0

### pgaf-replica

- **Image:** wotonews/postgres-ha:v0.3.0

## Documentation

🟢 **Actively maintained** — last updated Oct '26.

# 🐘 Postgres HA Read Replica - Premium Railway Template

A highly available PostgreSQL cluster with automated failover and a streaming
read replica, powered by [pg_auto_failover](https://github.com/hapostgres/pg_auto_failover)
and deployed as a single Docker image across three Railway services. One
custom image, three services: monitor, primary, replica. The monitor watches
the primary; if it dies, the replica is promoted automatically and the old
primary rejoins as a standby when it comes back. Database traffic stays on
Railway's private network.

&gt; 💡 Need a web UI? Deploy the standalone **pgAdmin** template next to this
&gt; cluster and register both nodes — one card, one service, no overlap.

&gt; 🔄 **Actively maintained** — latest update **2026-10-28**: PostgreSQL 18 + pg_auto_failover 2.2; private-network app connections fixed. History: `CHANGELOG.md`.

---

# Deploy and Host Postgres HA Read Replica

Deploying this template provisions a three-service PostgreSQL high-availability
formation in your Railway project:

| Component | Type | Source / Image | Persistent Volume | Public URL | Description |
| :--- | :--- | :--- | :---: | :---: | :--- |
| **`pgaf-monitor`** | Service | `wotonews/postgres-ha:v0.3.0` | Yes (`/data`) | No | pg_auto_failover monitor — the witness that arbitrates failover. |
| **`pgaf-primary`** | Service | `wotonews/postgres-ha:v0.3.0` | Yes (`/data`) | No | The primary Postgres node — accepts all writes and reads. |
| **`pgaf-replica`** | Service | `wotonews/postgres-ha:v0.3.0` | Yes (`/data`) | No | The standby node — hot streaming replica, promoted on failover. |

## Accessing the cluster

**The database nodes** have no login screen and no password by design:
`pgaf-primary` / `pgaf-replica` / `pgaf-monitor` are private-network only
(trust authentication inside Railway's private network — nothing is exposed
to the internet). Connect your app services with
`postgresql://pgaf-primary.railway.internal:5432/postgres` (writes) or
`postgresql://pgaf-replica.railway.internal:5432/postgres` (reads).

## About Hosting Postgres HA Read Replica on Railway

The three cluster services run the same image and self-organize: roles derive
from Railway-injected env (`RAILWAY_SERVICE_NAME` → monitor vs node,
`RAILWAY_PRIVATE_DOMAIN` → node identity). The first node to join becomes
primary; the second clones it via `pg_basebackup` and streams WAL.

- **Automated failover:** the monitor health-checks the primary every second;
  on failure it promotes the standby — no human intervention, no DNS tricks.
- **Automatic rejoin:** when the old primary returns (e.g. after a Railway
  redeploy), it is demoted and re-cloned as a standby. No split-brain, no
  manual `pg_rewind`.
- **Private networking:** nodes talk to each other over
  `.railway.internal` hostnames on Railway's private network. Nothing
  is exposed to the public internet by default.

## Why Deploy Postgres HA Read Replica?

- **Sleep-at-night durability:** a dead primary costs you seconds of
  availability, not your database.
- **Read scaling:** point reporting/analytics traffic at
  `pgaf-replica.railway.internal` to keep the primary free for writes.
- **Railway-native:** one image, three services, standard volumes — scale the
  replica tier by duplicating the `pgaf-replica` service.
- **No lock-in:** plain PostgreSQL 18 — `pg_dump` and walk away.

## Common Use Cases

- Production Postgres for APIs and web apps that cannot tolerate database downtime.
- Offloading heavy read/reporting queries to a hot standby.
- Zero-downtime maintenance windows (fail over, patch, fail back).
- A resilient Postgres backend for queues, analytics, or stateful workers.

## Dependencies for Deploying Postgres HA Read Replica

### Deployment Dependencies

- A Railway account (the template deploys three services + three volumes).
- Your application services must live in the **same Railway project and
  environment** to reach the cluster over the private network.
- No public port is exposed. To connect from inside Railway:
  - Writes: `postgresql://postgres@pgaf-primary.railway.internal:5432/postgres`
  - Reads: `postgresql://postgres@pgaf-replica.railway.internal:5432/postgres`

---

## 📐 Architecture &amp; Components

```mermaid
graph TD
    App[Your App Services<br>same Railway project] --&gt;|writes| Primary[pgaf-primary]
    App --&gt;|reads| Replica[pgaf-replica]
    Monitor[pgaf-monitor] &lt;--&gt;|health checks + failover arbitration| Primary
    Monitor &lt;--&gt;|health checks + promotion| Replica
    Primary --&gt;|WAL streaming| Replica
    Primary --- V1[(volume /data)]
    Replica --- V2[(volume /data)]
    Monitor --- V3[(volume /data)]
```

### How failover works

1. Monitor misses health checks from the primary (default: ~10s of failures).
2. Monitor promotes the standby — it becomes the new primary.
3. Clients reading `pgaf-primary.railway.internal` should reconnect to
   `pgaf-replica.railway.internal`. The recommended app pattern is the
   multi-host connection string (transparent failover):

   ```
   postgresql://postgres@pgaf-primary.railway.internal:5432,postgres@pgaf-replica.railway.internal:5432/postgres?target_session_attrs=read-write
   ```

4. Old primary comes back → demoted and re-cloned as the new standby. Roles
   converge without manual action.

### Scaling out

Duplicate the `pgaf-replica` service (same image, same variables) to add more
standbys. Each new node clones the current primary and joins the formation.

---

## ⚙️ Configuration

**Zero-configuration cluster.** The pg_auto_failover services ship no
variables at all — everything self-wires from Railway-injected environment
variables. Nothing to fill in:

| Service | Variables |
| :--- | :--- |
| `pgaf-monitor` / `pgaf-primary` / `pgaf-replica` | *none — roles self-derive from Railway-injected env at boot* |

&gt; Want the web UI too? Deploy the standalone **pgAdmin** template into the same
&gt; project and it picks up both nodes.

Cluster derivation (injected, not configurable through the card):

| Derived from | Used for |
| :--- | :--- |
| `RAILWAY_SERVICE_NAME` | Role: the `pgaf-monitor` service runs the monitor; every other service joins as a Postgres node. |
| `RAILWAY_PRIVATE_DOMAIN` | This node's private DNS name (`NODE_HOST`). |

Optional overrides (for renamed services or local Docker runs):

| Variable | Default | Description |
| :--- | :--- | :--- |
| **`NODE_ROLE`** | derived | Force the role: `monitor`, `primary`, or `secondary` (primary/secondary behave identically — the formation assigns real roles). |
| **`NODE_HOST`** | derived | Override this node's DNS name. |
| **`MONITOR_SERVICE`** | `pgaf-monitor` | Which service name runs the monitor (also derives `MONITOR_HOST`). |
| **`MONITOR_HOST`** | `pgaf-monitor.railway.internal` | Override the monitor's DNS name. |
| **`PGDATA`** | `/data/pgdata` | Postgres data directory (on the volume). |
| **`PGPORT`** | `5432` | Postgres port. |
| **`WAIT_TIMEOUT`** | `300` | Seconds a node waits for the monitor before exiting (restart policy retries). |

&gt; Renaming services? Set `NODE_ROLE=monitor` on the monitor and
&gt; `MONITOR_HOST=` on the nodes — otherwise keep names as-is.

### 🔒 Security model

- Inter-node auth is pg_auto_failover `trust` mode, scoped to Railway's
  **private network** — unreachable from the public internet.
- **Do not** attach a public TCP domain to these services: that would bypass
  network isolation.
- To add password auth, fork the image and manage `PGUSER`/passwords via
  pg_autoctl configuration (`--auth scram-sha-256`).

---

## 🚀 Setup &amp; Deployment Guide

1. Click **Deploy** on the template card — Railway provisions the services
   with their volumes and variables.
2. Wait for all deployments to report success (~1–2 minutes; the replica
   clones the primary on first boot).
3. Connect apps to `pgaf-primary.railway.internal:5432` (writes) and
   `pgaf-replica.railway.internal:5432` (reads).
4. Optional — verify the formation (`railway ssh -s pgaf-monitor`):
   `pg_autoctl show state` should list one node `primary` and one `secondary`.

Local development: `git clone  &amp;&amp; cd postgres-ha &amp;&amp; cp .env.example .env`.

---

## 🧪 End-to-End (E2E) Testing

```bash
bash e2e/run-tests.sh
```

Validates structure, marketplace limits, the manifest, volume wiring, and
Dockerfile/entrypoint contracts; with a Docker daemon it also builds the
cluster image and proves a three-node formation converges, streams, and
promotes the replica after a hard primary kill. CI runs the suite on every push.

---

## 📝 Operational notes

- **Cost:** three always-on services + volumes; the monitor fits a small plan.
- **Backups still matter:** HA is not backup. `pg_dump` against the replica
  avoids load on the primary.
- **Upgrades:** bump the image tag in `railway.json`, redeploy services one at
  a time — pg_auto_failover fails over during primary redeploys automatically.


## Similar templates

- [RustFS | (Just Updated) S3 Object Store, Public URL and Keys Set](https://railway.com/deploy/rustfs-or-just-updated-s3-object-store-p) — S3-compatible object store, keys and public URL preset, volume kept
- [TimescaleDB](https://railway.com/deploy/timescaledb-railway-template) — A PostgreSQL-based time-series database for analytics on Railway.
- [Neo4j 2026.10 Community](https://railway.com/deploy/neo4j-202610-community) — Neo4j graph database with APOC, Browser, Bolt TCP proxy and a volume

Open this page in a browser: https://railway.com/deploy/postgresql-ha-failover
