Skip to main content
Let’s set up the simplest possible installation scenario - when you have two shards and one router.
Download spqr-router for Linux or macOS (amd64, arm64) into ./spqr. The installer verifies the checksum and does not need sudo.
The router does not install PostgreSQL. You need two running PostgreSQL instances, on localhost:5432 and localhost:5433 by default; change the shard hosts in examples/quickstart.yaml if yours run elsewhere. Then start the router:
The router applies examples/init.sql: rows with id from 0 through 49999 go to sh1, and rows with id 50000 or above go to sh2. Check it through the router on port 6432:
CREATE TABLE runs on both shards, and each row lands on its own one:
For the fastest experience, use our pre-built Docker image:Available tags:
  • latest - Latest stable release (recommended for production)
  • stable - Same as latest
  • nightly - Built from master branch (latest features)
  • v1.2.3 - Specific version
Ports:
  • 6432 - Router port (your app connects here)
  • 7432 - Admin console (configure sharding)
  • 7000 - gRPC API
You’ll need to set up PostgreSQL shards and configure the router. See the sharding setup section below for complete instructions.
For local development, you need the latest Go version.How to build:
How to run:

Setting up sharding

First, you need to configure the rules by which the router will decide which of the shards to send each request to. For this purpose, SPQR has an administrative console. This is an app that works by PostgreSQL protocol and you can connect to it by usual psql. You can find the console port in your config file.
To make all things work, the router needs to know the following:
  • What tables do you query
  • Which columns in each table should the router search for
  • Types of these columns
  • Mapping from [range of values] to [shard number]
Let’s create a distribution first:
The next step is to specify a list of tables and columns.
And at the end specify a list of ranges: which values to route to which shard. Note: The right bound is infinity if there are no key ranges.
CREATE KEY RANGES FOR DISTRIBUTION automatically handles the creation order. If you create key ranges manually with CREATE KEY RANGE, you must create them in descending order by lower bound (highest first).
Here we go! You can play with some SELECTs or INSERTs.

Connect to SPQR router

Now we can connect to proxy a.k.a. router and play with it. Please use psql again, but this time connect to a different port.
Then, populate it with an order:
NOTICE messages are disabled by default, specify show_notice_messages setting in the router config to enable them
The order can be found on the first shard:
SPQR can handle such queries as SELECT * FROM table but we don’t recommend using it. This feature is implemented in a non-transactional way.