Skip to the content
Know your tech before you buy it. Makers: get listed from $49/mo

SPQR

docs.pg-sharding.tech

  • Free plan
  • Linux
  • API
  • Self-hosted

What SPQR is

SPQR is a self-hosted, open-source query router for horizontally scaling PostgreSQL through sharding. Applications connect using the PostgreSQL protocol, while SPQR routes queries to key ranges and shards when it can identify a sharding key. Keys can be based on one column or several, and SQL comments can specify a key or name a shard directly. The router and coordinator also provide administrative consoles accessible through psql. SPQR supports one-phase and two-phase commit; the latter provides atomicity across shards and requires max_prepared_transactions to be greater than zero on every shard. It can move data between shards to balance workloads, with smaller transfer ranges intended to limit locking impact. The project says it has handled terabytes of data and 100K+ queries per second. It can use managed PostgreSQL services, and pgx and JDBC are listed as compatible driver examples. SPQR is free and distributed under the PostgreSQL Global Development Group License, with Docker and configuration-file deployment instructions. Its FAQ cautions against complex cross-shard queries, multi-shard modifying transactions, and OLAP workloads.

Who it suits

SPQR suits PostgreSQL developers who want sharding without implementing that logic in their application, particularly for single-shard OLTP workloads. It is not positioned for OLAP or complex cross-shard work.

Good to know, and what to watch

  • Routes queries using single- or multi-column keys
  • SQL comments can direct queries to a shard
  • Supports one-phase and two-phase commit
  • Can use managed PostgreSQL services
  • Free and self-hosted
  • Not suitable for complex cross-shard queries
  • Not suited to multi-shard modifying transactions
  • Not intended for OLAP workloads
  • FAQ reports a 10–30% performance drop versus vanilla PostgreSQL

SPQR

Free

Open source

Getting started

  1. Open the SPQR documentation website
  2. Use the provided Docker image or deployment instructions
  3. Create a router configuration file
  4. Deploy SPQR in a self-hosted environment
  5. Connect applications through the PostgreSQL protocol
  6. Use psql for router and coordinator administration

Limits to check

SPQR's documented limits include workload constraints: complex cross-shard queries, transactions modifying multiple shards, and OLAP workloads are unsuitable. Two-phase commit requires max_prepared_transactions greater than zero on every shard, and the FAQ reports a roughly 10–30% performance drop versus vanilla PostgreSQL depending on workload.

The Club's review

SPQR is a self-hosted PostgreSQL sharding system for teams that need to scale a PostgreSQL application horizontally. It is strongest for single-shard OLTP workloads where developers want routing handled outside application code. Cross-shard and analytical work are poor fits.

Overview

SPQR is a stateless query router that directs PostgreSQL traffic across shards. Applications connect over the PostgreSQL protocol, while the router and coordinator expose administrative consoles through psql. It can use managed PostgreSQL services such as AWS RDS, Google Cloud SQL and Azure Database as shard backends, so adopting SPQR does not require replacing those services.

The project says it has handled terabytes of data and more than 100K queries per second. Those figures indicate the scale it targets, not a promise for every workload. SPQR was designed by Yandex.Cloud’s Data Platform team and is distributed under the PostgreSQL Global Development Group License.

Key features

Routing and shard keys

SPQR extracts a sharding key from a query and selects the matching key range and shard when possible. Single-column and composite multi-column keys are supported. A query can also provide a sharding key or explicitly select a shard in a SQL comment. This removes much of the routing code from an application, although queries still need to expose usable keys for predictable single-shard execution.

Balancing and transactions

Data migration between shards helps redistribute workload. SPQR describes moving smaller ranges to reduce the locking impact of transfers, a practical advantage when balancing a busy database. For writes spanning shards, one-phase and two-phase commit strategies are available. Two-phase commit supplies atomicity across shards, but every shard must set max_prepared_transactions above zero, adding an operational prerequisite.

Deployment and connectivity

A Docker image and configuration-file instructions cover router deployment. Connection pooling and query routing are included, and applications can continue using PostgreSQL-compatible drivers such as pgx and JDBC. PostgreSQL SSL modes, including require and verify-full, are supported for secured connections. The self-hosted model leaves infrastructure, upgrades and availability operations to your team.

Pricing

SPQR is open-source software with a free plan priced at free. The SPQR plan includes the PostgreSQL sharding software itself, with no seat or usage charge stated. Its PostgreSQL Global Development Group License suits organizations that can operate and support their own deployment; budget for your infrastructure and engineering time rather than a subscription.

Platforms

SPQR is available as an API-oriented, Linux, self-hosted deployment. PostgreSQL is the supported database, and the router can sit in front of managed PostgreSQL instances as well as self-managed shards. Docker instructions make containerized installation a straightforward starting point, but production responsibility remains with the operator.

Who it's for

Choose SPQR when your PostgreSQL application has a natural shard key and most transactions stay on one shard. It is particularly suited to developers who want horizontal scale without implementing sharding logic in every service, and to teams comfortable running a stateless router and managing PostgreSQL infrastructure.

Do not make it the default for complex cross-shard queries, transactions that routinely modify multiple shards, or OLAP workloads. The project reports a roughly 10–30% performance reduction versus vanilla PostgreSQL depending on workload, so the routing and scaling benefits must outweigh that cost for your traffic pattern.

Pros and cons

Pros

  • Application-transparent protocol: PostgreSQL clients and drivers can connect without adopting a proprietary database protocol.
  • Flexible keying: Single-column and composite keys, plus per-query routing controls, cover common partitioning designs.
  • Operational balancing: Range migration is designed to limit locking impact while redistributing data.
  • Backend choice: Managed PostgreSQL services including AWS RDS, Google Cloud SQL and Azure Database can serve as shards.
  • No license fee: The open-source, self-hosted plan avoids software charges.

Cons

  • Workload boundaries: Cross-shard queries, multi-shard write transactions and OLAP are explicitly unsuitable.
  • Performance overhead: Reported throughput is about 10–30% below vanilla PostgreSQL, depending on workload.
  • Operational burden: Self-hosting means your team handles deployment, scaling, upgrades and incident response.
  • Two-phase setup: Atomic cross-shard commits require max_prepared_transactions enabled on every shard.

Alternatives

For a broader comparison of routing products, see Database Proxy Software.

  • MySQL is a freemium, multi-platform database with replication, high availability components and connectors; choose it when you are willing to use MySQL rather than PostgreSQL.
  • Amazon RDS is a paid managed service with a free tier and trial; pick it when provider-managed operations matter more than self-hosted sharding.
  • OceanBase Database offers open-source and enterprise editions; consider it when you want a distributed database with broader kernel capabilities.
  • PgDog provides open-source and enterprise database-proxy options; choose it when its production control-plane features better match your operating model.
  • TurbineProxy is an Apache-2.0 open-source proxy with no per-query fees; consider it for a lightweight proxy alternative.
  • DBLE is an open-source Linux self-hosted option with enterprise support plans; pick it when DBLE’s ecosystem is a better fit.
  • Google Cloud SQL is a paid managed service with a free trial; choose it when you want Google-operated PostgreSQL rather than running a router yourself.
  • Heimdall Database Proxy offers freemium proxy editions; consider it when caching, read/write splitting and a managed enterprise tier are priorities.

Verdict

SPQR is a strong choice for PostgreSQL teams with a clear shard key, predominantly single-shard OLTP traffic and the skills to run self-hosted infrastructure. Its PostgreSQL protocol compatibility, routing controls and balancing support make horizontal scale possible without embedding sharding throughout application code. Look elsewhere if your workload is analytical or cross-shard by nature, or if the reported performance overhead and operational responsibility outweigh the value of keeping PostgreSQL.

The verdict

SPQR provides PostgreSQL sharding with routing, data balancing, and transaction options while keeping application connections on the PostgreSQL protocol. Check its stated workload limits and reported performance drop against your use case before adopting it.

Questions people ask

Is SPQR free?

Yes. SPQR is open source and its listed SPQR plan costs nothing.

Which platforms does SPQR support?

SPQR is available as an API for Linux and is self-hosted.

Which database does SPQR scale?

SPQR scales PostgreSQL through sharding and supports PostgreSQL-compatible connections.

Can SPQR use managed PostgreSQL?

Yes. Named services include Yandex Managed PostgreSQL, AWS RDS, Google Cloud SQL, and Azure Database.

Which drivers can connect to SPQR?

The FAQ names pgx and JDBC as compatible driver examples, while applications communicate through the PostgreSQL protocol.

Who made SPQR and where is support available?

SPQR was designed by the Data Platform team of Yandex.Cloud. Users can discuss it in Telegram and report bugs or feature requests through GitHub Issues.

What the maker publishes

Automatic routing
The router extracts a sharding key from a query and uses it to select the key range and shard when possible. source
Data balancing
SPQR migrates data between shards to balance workload and describes reducing the size of transferred ranges to minimize locking impact. source
Deployment
The documentation provides a Docker image and instructions for running the router with a configuration file. source
Deployment
The getting-started guide provides a Docker image and lists router, admin console, and gRPC API ports as 6432, 7432, and 7000. source
Distributed transactions
SPQR offers one-phase and two-phase commit strategies; two-phase commit provides atomicity across shards and requires max_prepared_transactions greater than zero on every shard. source
Integrations
The FAQ says SPQR works with managed PostgreSQL databases including Yandex Managed PostgreSQL and AWS RDS, and names pgx and JDBC as compatible driver examples. source
Intended users
SPQR is presented as a fit for PostgreSQL developers who want to avoid application-level sharding logic and workloads suited to single-shard OLTP queries. source
License
SPQR is distributed under the PostgreSQL Global Development Group License. source
License
The source is distributed under the PostgreSQL Global Development Group License. source
Limits
The FAQ says SPQR is not suitable for complex cross-shard queries, transactions that modify multiple shards, or OLAP workloads. source
Maker
The documentation says SPQR was designed by the Data Platform team of Yandex.Cloud. source
Managed PostgreSQL
The product site says SPQR can use managed PostgreSQL services including AWS RDS, Google Cloud SQL, and Azure Database for its shards. source
Performance
The FAQ reports a roughly 10–30% performance drop versus vanilla PostgreSQL depending on workload. source
PostgreSQL protocol
Applications communicate with SPQR using the PostgreSQL protocol, and the router and coordinator have an administrative console accessible through psql. source
Product
SPQR is a production-ready system for horizontally scaling PostgreSQL through sharding. source
Routing controls
Queries can specify a sharding key or explicitly select a shard in a SQL comment. source
Scale
The product site says SPQR has handled terabytes of data and 100K+ queries per second. source
Security
The docs show PostgreSQL connections configured with SSL modes including require and verify-full. source
Sharding keys
SPQR supports single-column and composite multi-column sharding keys. source
Sharding keys
The router supports single-column and composite sharding keys and routes queries using the key value. source
Support
The project GitHub page directs users to a Telegram chat for discussion and GitHub Issues for bugs or feature requests. source
Support
The project directs users to its Telegram chat for discussion and GitHub Issues for bug reports or feature requests. source
Use cases
The maker recommends SPQR for developers who want to keep PostgreSQL and avoid implementing sharding logic in the application, especially for databases suited to single-shard OLTP queries. source
What it does
SPQR is a stateless PostgreSQL query router for horizontally scaling PostgreSQL through sharding. source

Checked against the maker's pages on 11 Oct 2026.