Repolode
Submit
pg-sharding

pg-sharding/spqr

A stateless query router that horizontally shards PostgreSQL, letting one logical database span multiple backend instances.

View on GitHubWebsite
Stars
1,481
Forks
100
Open issues
102
Last commit
3 hours ago

What is it?

SPQR is a stateless query router that sits between applications and PostgreSQL and distributes data across multiple database shards. It is aimed at single databases that have grown to terabytes of data and very high query rates, where a single PostgreSQL instance becomes hard to manage.

The project is written in Go and is built around a router process started with spqr-router, configured through a YAML file. Its stated goal is to offer a smoother path from a monolithic database to a sharded setup than many existing sharding solutions, which mainly target analytical and hybrid workloads.

Documentation, the feature list, and a Docker-based quick example are available on the project site. Unit, regression, and end-to-end tests run through Docker Compose and make targets.

Key features

  • 01Routes client queries across multiple PostgreSQL shards behind one endpoint.
  • 02Runs as a stateless router process configured with a YAML file.
  • 03Provides a Docker-based quick start via make run.
  • 04Includes unit, regression, and end-to-end test suites.

Use cases

  • Scaling a single PostgreSQL database that has grown to terabytes and high query volume.
  • Migrating a monolithic PostgreSQL deployment toward a sharded architecture.
  • Running OLTP-style workloads that need horizontal partitioning across instances.

Quick start

  1. 1

    Run a quick example using Docker

    make run
  2. 2

    Build the project from source

    make build
  3. 3

    Run the router with your config file

    spqr-router run --config path-to-router-config.yaml

Things to know

  • Automatic license detection failed, so the license must be checked in the repository; the README names the PostgreSQL Global Development Group License.
  • Local development requires the latest version of Go.

In collections

Databases & SQL tools

Topics

#postgres#postgresql#sharding#database-proxy#query-router#connection-pooler#go#pooler#proxy

FAQ

What is spqr?
A stateless query router that horizontally shards PostgreSQL, letting one logical database span multiple backend instances. SPQR is a stateless query router that sits between applications and PostgreSQL and distributes data across multiple database shards. It is aimed at single databases that have grown to terabytes of data and very high query rates, where a single PostgreSQL instance becomes hard to manage.
Is spqr free to use? What license does it have?
spqr is open source under the Other license. Check the license terms before using it in commercial products.
Is spqr still maintained?
Actively maintained. The last commit to spqr was on Oct 22, 2026.
What can I use spqr for?
Scaling a single PostgreSQL database that has grown to terabytes and high query volume. Migrating a monolithic PostgreSQL deployment toward a sharded architecture. Running OLTP-style workloads that need horizontal partitioning across instances.
How do I install spqr?
Run a quick example using Docker: make run Build the project from source: make build Run the router with your config file: spqr-router run --config path-to-router-config.yaml
Where can I get spqr?
The source code and installation instructions are on GitHub: https://github.com/pg-sharding/spqr

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects