Quick Start

PgVisor delivers production-ready PostgreSQL 18 High Availability (HA) without the operational complexity of Patroni, PgBouncer, Consul, and pgBackRest.

In this quick start guide, you will bootstrap a complete local 3-node HA cluster with automatic Raft consensus failover, continuous S3/MinIO backup archiving, and an embedded web dashboard.

Prerequisites

Before starting, ensure your system has:

• Docker Engine (v24.0 or newer)
• Docker Compose (v2.0 or newer)
• (Optional) psql command-line client for direct database interaction

One-Command Cluster Bootstrap

PgVisor includes a bootstrap script that orchestrates the entire cluster setup:

git clone https://github.com/dreamoutbox/pgvisor.git
cd pgvisor/examples

./setup.sh

Connecting to the Cluster

Applications and database clients connect directly to the PgVisor L7 Proxy on port 5432.

Using psql CLI

psql -h localhost -p 5432 -U postgres -d postgres

When prompted for password, enter postgres (default password configured in .env).

Application Connection String

Configure your application database pool or ORM with the standard PostgreSQL connection URI:

postgresql://postgres:postgres@localhost:5432/postgres

Transparent Read/Write Splitting

PgVisor’s L7 proxy inspects PostgreSQL 3.0 wire protocol messages in real time to provide automatic read/write splitting without application code changes:

• Mutating Queries & DDL: Any INSERT, UPDATE, DELETE, CREATE, DROP, ALTER, or explicit transaction block (BEGIN ... COMMIT) is forwarded strictly to the active Raft leader (pgvisor-node1).
• Read Queries: Standalone SELECT, SHOW, and EXPLAIN statements are load-balanced across healthy standby replicas (pgvisor-node2, pgvisor-node3).

Try It Out

Connect with psql and execute a write followed by reads:

-- Creates table on the Raft leader
CREATE TABLE users (id serial PRIMARY KEY, username text);

-- Inserts record on the Raft leader
INSERT INTO users (username) VALUES ('alice'), ('bob');

-- Routed to a standby replica with connection pooling
SELECT * FROM users;

Testing Zero-Downtime Failover Buffering

PgVisor includes transparent failover query buffering. If the leader fails mid-flight, client connections do not crash; the proxy buffers requests in memory while OpenRaft elects and promotes a new leader.

docker compose -f examples/docker-compose.yml stop pgvisor-node1

INSERT INTO users (username) VALUES ('charlie');
SELECT * FROM users;

Management Commands

The setup.sh script provides lifecycle helpers:

# View all cluster logs
./setup.sh logs

# View logs for a specific container
./setup.sh logs pgvisor-proxy
./setup.sh logs pgvisor-node1

# Check health and container states
./setup.sh status

# Restart all containers
./setup.sh restart

# Stop cluster (volumes preserved)
./setup.sh down

# Wipe volumes and start clean
./setup.sh clean

Next Steps