Skip to main content
Horizontal sharding distributes a logical table’s rows across Postgres shards, each with its own primary and replicas. Sharding is recommended when one primary remains a bottleneck, even after you tune Postgres configuration, query performance, indexes, and storage. Sharding allows you to spread data across multiple primary Postgres servers, alleviating both storage pressure and read and write throughput limitations of single-primary Postgres setups.

​
What sharding changes

Each shard can be configured to have a different number of replicas. Replicas can provide failover capacity in a multi-node profile and can offload read traffic from the primary. A shard configured with no replicas is not highly available.

​
Partitioning vs sharding

Postgres declarative partitioning splits a logical table into physical tables. In a typical Postgres deployment, it can improve performance and make data pruning cheaper. However, it does not remove a single-primary write bottleneck or let data exceed the capacity of one Postgres instance. Neki distributes a logical table across independent Postgres shards, each with its own primary, storage, and replication state.

​
When sharding is the correct choice

Sharding becomes a good next step for scaling when one or more of these are true:
  • The primary is persistently limited by write throughput or disk IOPS.
  • The working set of your relational data no longer fits within the RAM available on a single instance.
  • Independent shards would reduce the amount of data affected by one primary failure.
  • The workload has a stable routing key that keeps related data and common queries on one shard.
A tenant key (such as a customer_id or company_id) often keeps each tenant’s rows together in the query workload.

​
Evaluate single-shard changes first

Before sharding, evaluate whether configuration tuning, schema changes, query optimization, or a larger cluster size can remove the bottleneck. Query Insights identifies expensive and frequently run queries. It can also surface schema recommendations. These tools can help identify improvements for an existing Postgres database. In addition, Metal uses locally attached NVMe and can provide higher I/O throughput and lower latency than network-attached storage.

​
Design considerations

Taking a database from unsharded to sharded requires an up-front decision about how to distribute the rows of logical tables. For predictable performance, design the topology so most queries reach one shard instead of requiring several shards to fulfill each query. The data topology controls which tables are distributed across which shards and how their rows are divided. Before moving data, validate the topology against the schema and the application’s common access patterns.

​
Need help?

Get help from the PlanetScale Support team, or join our Discord community to see how others are using PlanetScale.