pgwrh

pgwrh scales PostgreSQL read queries by distributing shards—the leaf partitions of a table—across replicas. Each replica stores an assigned subset of the data and can query other replicas for the remaining shards, so it can serve queries over the complete table without storing a full copy.

Applications write to the controller, the PostgreSQL database that holds the source data and manages shard placement. Replicas receive their assigned shards through asynchronous logical replication. For reads that must observe a known committed write, pgwrh_wait can wait until the relevant subscription has applied changes through a specified log sequence number (LSN) before the read takes its snapshot.

Start with the local quickstart, then read cluster concepts and rollouts.

1.0.0-alpha1 is a testing prerelease. Try it with disposable or recoverable data and share feedback before 1.0.0. APIs and configuration may change, and an in-place upgrade to later releases is not promised. See the alpha release notes for limitations and useful test scenarios.

The development branch also prepares PostgreSQL 19 Beta 3 support. See the version and preview guide; published alpha1 artifacts remain PostgreSQL 18 builds.

Components

The development bundle contains five extensions for PostgreSQL 18 and the PostgreSQL 19 preview:

Extension	Purpose	Where to enable it
pgwrh	Manages shard placement, replication and configuration rollouts	Controller and replicas
pgwrh_fdw	Foreign data wrapper (FDW) for queries and connections between databases	Enabled automatically by CREATE EXTENSION pgwrh CASCADE
pgwrh_wait	Issues session commit tokens and waits for replicated writes	Optional, on the controller issuing tokens and subscribers serving guarded reads
pgwrh_ui	Browser console for monitoring and managing the cluster	Optional, controller only
pgwrh_gist_extra	Additional GiST operators for text-array searches	Optional, on databases using these indexes or shipping these operators

The development bundle uses pg_background 2.0.3 to run background tasks on both PostgreSQL majors. Packages install it as a dependency; the container and Nix bundle include it. The console uses PostgREST, a separate web service that connects to the controller database. See console setup.

pgwrh_fdw, pgwrh_wait and pgwrh_gist_extra can also be used independently of the core. PostgreSQL's stock postgres_fdw extension is not required. The GiST extension requires PostgreSQL's btree_gist; see its installation and operator guide. Published alpha1 packages contain the original four extensions and predate pgwrh_gist_extra.

Quickstart

Install Docker with Compose and curl. From an unpacked source archive or repository checkout, run:

bash examples/compose/quickstart.sh

The script starts a controller, two replicas and a read-only console, distributes four example shards, and verifies that both replicas return the same 100 rows. When it prints Quickstart verified, open the console.

The default image is ghcr.io/mkleczek/pgwrh:1.0.0-alpha1-pg18. If it has not yet been published, build and select a local image first:

docker build -f packaging/container/Dockerfile -t pgwrh:1.0.0-alpha1-local .
PGWRH_IMAGE=pgwrh:1.0.0-alpha1-local bash examples/compose/quickstart.sh

The demo uses fixed local credentials and loopback ports. See the container guide for querying replicas, choosing ports, and stopping or removing the demo.

Placement and read scaling

• Partitioning: use PostgreSQL partitioning to define shards. Different parts of a partition hierarchy can have different replication policies, allowing more copies of frequently read data.
• Redundancy: specify the percentage of replicas that should store each shard and a minimum copy count. For example, keep a shard on 20% of replicas, with at least two copies.
• Availability zones: spread copies across zones, prefer selected zones, and require a minimum number of copies to survive a single-zone failure. See AZ affinity.
• Placement changes: preview a configuration, prepare its replicas, and commit it after readiness checks pass. Existing copies remain available during preparation. See rollouts.
• Remote reads: queries can combine local and remote shards. When a remote replica holds an entire partition subtree, pgwrh can query it as a unit. See remote shard aggregation.

Adding replicas can move shard copies. Placement favors retaining existing copies, but changes to copy counts, zone preferences or available hosts can require additional copying. Replication redundancy does not replace controller backups or a PostgreSQL high-availability plan. See controller HA and failover for standby configuration and promotion checks.

Installation

The 1.0.0-alpha1 bundle targets PostgreSQL 18. All four extensions share version 1.0.0-alpha1. This release supports fresh installation only; it includes no upgrade scripts for earlier installations.

Environment	Guide
Linux, macOS or Windows with Docker	Compose cluster and container
RHEL/Rocky/AlmaLinux 9	RPM packages
Debian 13, Ubuntu 24.04/26.04	DEB packages
Nix or NixOS	PostgreSQL bundle and NixOS module
Source build	Build requirements and installation

Release downloads, image tags and signed repositories are available after the release workflow publishes them. The guides also describe local builds. Installing extension files and enabling extensions in a database are separate steps; follow your guide's server settings and database activation instructions.

From a source checkout, check an installation with:

psql -X -d your_database -f docs/check-installation.sql

This checks the full bundle, including the optional wait API, without changing configuration. It does not verify cluster membership or shard placement.

Operations and limitations

Remote reads use per-source SCRAM credentials, with credential rotation managed independently of placement rollouts.

Writes go to the controller. Use replication visibility barriers when a read must observe a known write. Queries spanning replicas do not have a single cluster-wide snapshot.

Schema changes require operator coordination; version 1.0.0-alpha1 has no coordinated schema-change rollout facility. Placement rollouts do not make schema changes atomic across the cluster. Read the recovery guide before deploying and the release notes for supported targets and limits.

For source layout, tests and implementation details, see the contributor documentation.