Why Azure?

Many teams run their apps on Azure, and we've received consistent requests, especially over the past year, to bring PlanetScale to where they're building. Now those teams can use PlanetScale alongside all their other Azure compute and infrastructure.

What's included?

Databases on Azure get the same PlanetScale features you use on our other clouds: high availability with a primary and replicas spread across 3 availability zones, Query Insights, schema recommendations, automated backups, and more. That includes Metal clusters with locally attached NVMe storage, the fastest way to run databases in the cloud.

Supported Azure regions

Azure support is currently available in the following regions:

• centralus (Iowa, USA)
• eastus2 (Virginia, USA)
• westeurope (Netherlands)

If you'd like to see PlanetScale in other Azure regions, let us know. See the regions documentation for the full list across all cloud providers.

What it took

Bringing PlanetScale to a new cloud took significant time, particularly in testing and ensuring it behaves just as seamlessly on Azure as it does on AWS and GCP. Every cloud has its quirks, and Azure is no exception.

Kubernetes pod networking is a good example. PlanetScale runs databases on Kubernetes, and every database pod needs its own IP address on the network. We wanted those addresses to come from the Azure virtual network directly, with native routing and no overlay for maximum performance and low latency.

The simple approach is to request one IP from Azure per pod, which causes two problems. Azure caps a virtual network at 65,536 private IP addresses, which would limit the whole network to about 65,000 pods. It also puts the Kubernetes API server in the path of every pod start, which slows things down under load.

We solved both by handing out addresses in blocks. Each node gets blocks of 16 IPs (/28 prefixes) on its network interface, and Azure counts each block as a single address toward the cap. That increases our overall IP capacity by 16x, to over a million pod IPs per network. A background service on each node tracks its blocks, and a lightweight CNI plugin assigns pod IPs from them locally, so the API server stays out of the way. When a node gets down to 8 free addresses, it grabs another block, up to 256 blocks (4,096 pod IPs) per node.

This sounds like a simple solution, but it took a surprising amount of custom work to get just right.

Azure had a few additional networking challenges along the way. /28 is the only block size it offers, so the design had to work around that. Older versions of the network interface API don't return prefixes at all, and the block's range comes back in a field normally used for a single address. There's also a chicken-and-egg problem: system pods need IPs before the Kubernetes operator that manages the blocks is running. To handle that, the operator has a bootstrap mode that runs on the host network.

In scale testing, one cluster ran over 6,700 pods across more than 100 node pools, with the busiest nodes holding 15 blocks (240 IPs) each.

This is just one of many pieces we had to carefully construct to make PlanetScale on Azure a seamless experience for our customers. Storage, load balancing, identity, and backups all needed the same level of care. All of that work culminates in today's launch.

Getting started

To create a database on Azure, choose Azure as the cloud provider when you create a new database, then select a region. Existing databases can be migrated to Azure by contacting support.

If you have questions or want help planning a move, get in touch.

Sometimes, the answer is obvious. Is the user logged in? Does their role have the required permissions?

Sometimes it's less obvious. Are there sufficient resources available? Is this work a higher priority than everything else?

There are many names for the mechanisms that block or allow actions in software. Most commonly they are referred to as admission control. Perhaps you'll be familiar with a leaky bucket implementation.

A brief history of leaky buckets

Engineering applications for leaky buckets predate computers. From around 1600 BC the Babylonians, Egyptians, and Persians all used vessels with a small hole in the bottom as primitive clocks, measuring elapsed time by the volume of the container as it drained at a constant rate.

By around 200 BC the Greeks had advanced leaky buckets into accurate clocks. A floating regulator kept water flowing steadily from one bucket into a second, where a rising float moved a pointer to show the hour. A siphon emptied the second bucket once it was full. Most notably, Ctesibius added gears to regularly advance each "tick" of the clock, turning the display which indicated the current season.

A mechanical movement driven by a leaky bucket was born, and it became the gold standard of timekeeping for centuries.

Water-based clocks were used as a form of admission control. In Athenian courts, the length of time a speaker had to plead their case was measured by the time water took to drain from a vessel. The amount of water poured into the vessel was determined by the severity of the case.

Finally, in the computer age, Jonathan Turner is said to have used the term "leaky bucket" first in 1986, writing "New directions in communications" for IEEE Comms Magazine. The piece describes how a system can police the pace at which packets are sent over broadband connections. (If you haven't read it, spoiler: it's not much slower than your connection at home today.)

Leaky buckets in software

There are two kinds of leaky buckets in software, to implement a meter or a queue.

In both, each unit of "work" is assigned a value which is checked against the current volume of a "bucket." If the bucket lacks capacity for the size of new work, that work is rejected. Otherwise the work is allowed and its value adds to the bucket's current volume. The bucket drains (or leaks, if you will), so over time, new work can't be admitted faster than the bucket drains. The drain rate is based on time elapsed, not on the completion of work.

When used as a meter, the bucket defines if and how much work is permitted to immediately proceed. As a queue, the bucket defines the volume of work that can wait to proceed, but work only begins as it drains from the bucket.

In this post we'll focus on leaky buckets as a meter.

Typically, leaky buckets are implemented in software to keep systems healthy. A sort of resource management to ensure the system is not overwhelmed.

It's not hard to imagine this being useful in a database. Imagine being able to block or allow queries, before they execute, based on available resources or concurrency limits. One can dream!

The leaky bucket can be tweaked by modifying its volume and the rate at which it drains.

At its core a leaky bucket prevents work, but it also forces us to reason about the total volume of work that results in a block, how quickly more capacity becomes available, and how to handle the expected failure state when work is rejected.

Leaky buckets in API design

Shopify's GraphQL Admin API implements rate limiting with a documented leaky bucket. Each app on each store gets a bucket with a fixed size and restore rate.

Each request costs a different amount based on what the query asks for, not how many requests are made. Before a query runs, the bucket must have room for its estimated cost. Once it completes, the bucket is refunded or charged any difference between the estimated and actual cost. Apps can burst faster than the restore rate until the bucket has no room left, at which point requests are throttled.

Responses include the current state of the bucket, so apps can slow down before they're throttled and treat throttling as an expected outcome, not a surprise.

Classification as admission control

Now let's consider the AI age. Jev, a "System One" model (perhaps better named a "Decision Model"), recently launched, making classification through inference cheap and fast. It could classify "should this work proceed or not" based on a predefined set of options and return a response in hundreds of milliseconds.

Whether our decision gate is mechanical (leaky bucket) or requires inference (Jev), the requirement is the same: answering "should this proceed?"

Low cost throttling

One of the great benefits of leaky buckets in software is how cheap they are. What we've described as a slowly draining bucket isn't a long-running process that is using CPU to "drain".

Simply put, a bucket is a stateful object that holds two values:

1. how full it was the last time anyone looked
2. when that was

From those values, you can work out how full the bucket is now:

level_now = max(0, level_then - drain_rate × (now - then))

Any work rejected or admitted by the bucket updates its current state. In this way, buckets are lazily drained (as in, only when checked) and empty buckets hold no values.

Admission controls and databases

Just like hardware, operating systems, applications, and ancient Greeks, databases benefit from leaky buckets.

However, open-source databases like Postgres and MySQL don't have this functionality baked in.

One of the most common failure modes for databases in production is the inability to deliberately reject work they cannot complete. Blast a billion queries at your typical relational database, and it'll try its best to execute them. Success isn't likely. Some hardware, configuration, or connection limitation will unwittingly play the role of an admission control system and start blocking work in some unhandled, undesirable way.

Some proprietary databases have a form of resource management so that workloads can be throttled (but not rejected). For example, in 1999 the Oracle Database Resource Manager added mapping rules to sessions for users, services, clients, and more, which could then be used to apply limits on things like resource use and concurrency.

In 2008, SQL Server added the SQL Server Resource Governor, which added classifier functions to sessions that can then apply rules to queries in that session.

Postgres has some configuration options to control expensive queries that have already consumed resources, such as statement_timeout, but nothing to prevent expensive work before it happens. And so in 2026, PlanetScale brought decision gates to Postgres with Database Traffic Control®.

Database Traffic Control

The health of your Postgres database is laid bare at the mercy of your applications. An unexpected connection storm or failure of the query planner can ask more of your database than it can reasonably be expected to handle.

To protect your Postgres database from your application (and at times, from itself), we built Traffic Control, admission control for Postgres. In it, resource budgets determine how many resources or how much concurrency one or many queries can consume.

Each budget admits or blocks queries that match a specified set of tags. Those tags can be specified as comments in the query, or they can refer to the user or application that sent it. If the resource budget determines the query should not proceed, it will log a warning or block it, depending on your resource budget configuration.

Creating a resource budget opts you into an expected failure state, so it forces you to reason about the behavior your application should exhibit when queries are blocked. For this reason, we recommend creating a new budget in warning mode first, monitoring how much traffic is affected, preparing your application for blocked queries, and then updating the mode.

Admission controls but for traffic

You configure three major settings on a resource budget.

Server share and burst limit, the token* bucket. Server share determines how fast the bucket replenishes with tokens, expressed as a percentage of server resources. The burst limit sets the maximum capacity of the bucket, expressed in whole-server seconds.

Because a database doesn't know the cost of a query before execution, Traffic Control estimates its cost based on the query plan and historical behavior of queries with that shape. If the budget has sufficient capacity the query proceeds. After execution, the cost of the query is calculated and any difference is either refunded or charged to the token bucket.

Why is the refill rate measured in server capacity instead of seconds? Because not all time spent executing a query is equal. A query that took 8 cores a single second is different from a query that took one core a single second. Consider different server sizes as well: a 25% server share means a quarter of your server's capacity drains back every second, whether that server has 2 cores or 64.

Per-query limit sets an upper limit on the maximum capacity a single query can consume. This makes an admission-control decision directly on a single query instead of measuring it against available capacity in a bucket.

Maximum concurrent workers similarly controls the resources a single query can consume, but measures it by available workers instead of execution time.

A query may be targeted by multiple resource budgets and must satisfy all of them to proceed.

For specific scenarios where resource budgets help, along with how to tag queries in your codebase, see Patterns for Postgres Traffic Control.

Summary

Admission control forces you to decide what should happen when work can't proceed, and leaky buckets have been a cheap way to make that decision for a very long time. Traffic Control makes that decision for Postgres before an expensive query runs, not after.

Get started with Database Traffic Control

Neki adds a layer between a PostgreSQL client and PostgreSQL. We need that layer to route queries to shards and to make many PostgreSQL servers look like one. The downside is that every query now has another network hop and has to pass through the router.

We can't make that hop disappear, so a lot of the performance work in Neki comes down to what we can avoid doing while the query passes through it. If the router doesn't need to understand a result, why decode it? If it only needs one column, why decode the other ten columns in the same row?

The key part here is that we can design this to be lazy and composable. Walking the PostgreSQL messages in a response does not mean we also need to construct rows. Finding the rows does not mean we need to decode their columns either. Even if the router needs one value, the rest of the row can stay as protocol bytes.

Why not decode everything up front?

The usual way to build a layer like this is to parse whatever comes over the wire into your own types as soon as it arrives. Every row becomes a list of values, and the rest of the code only ever deals with those. It's a sensible default because it gives the rest of the system one consistent thing to work with.

Vitess, the MySQL sharding system we maintain, works this way, so it's a useful comparison. Vitess sends query results between its components using protobuf. Leaving out the fields that aren't important here, QueryResult and Row look like this:

message QueryResult {
  repeated Field fields = 1;
  uint64 rows_affected = 2;
  uint64 insert_id = 3;
  repeated Row rows = 4;
  string info = 6;
  string session_state_changes = 7;
  bool insert_id_changed = 8;
}

message Row {
  // -1 means NULL.
  repeated sint64 lengths = 1;

  // All non-NULL values concatenated together.
  bytes values = 2;
}

This is a pretty compact protobuf representation. lengths tells us where the values are in the shared values byte string, so the protobuf doesn't need a separate allocation for every value. The query engine can't use the protobuf rows directly though. At the RPC boundary, proto3ToRows converts all of them:

func proto3ToRows(fields []*querypb.Field, rows []*querypb.Row) [][]Value {
    result := make([][]Value, len(rows))
    for i, r := range rows {
        result[i] = MakeRowTrusted(fields, r)
    }
    return result
}

And MakeRowTrusted walks every column in every row:

func MakeRowTrusted(fields []*querypb.Field, row *querypb.Row) []Value {
    sqlRow := make([]Value, len(row.Lengths))
    var offset int64
    for i, length := range row.Lengths {
        if length < 0 {
            continue
        }
        sqlRow[i] = MakeTrusted(
            fields[i].Type,
            row.Values[offset:offset+length],
        )
        offset += length
    }
    return sqlRow
}

MakeTrusted doesn't turn every integer into a Go integer. A Value can still point at the bytes in the protobuf row. What we do get is a slice for every row and a Value for every non-NULL column before the query engine can do anything with the result. Going back across an RPC boundary does the reverse. RowToProto3Inplace first walks all the values to build the lengths and then walks them again to concatenate their bytes.

The protobuf result sits between separate Vitess components, while the query engine works with [][]Value. Converting at the boundary gives the engine one consistent type to work with. The downside is that every result gets converted, even when the router never looks at a value.

We wanted Neki to perform better, and therefore do less work in such cases.

Keeping the PostgreSQL response

Neki also uses protobuf between the router and the sidecar that sits in front of each PostgreSQL instance, but the result protobuf looks very different. Our ExecuteResponse is mostly a byte string:

message ExecuteResponse {
  bytes raw = 1;
  int64 conn_id = 2;
  ...
}

raw contains PostgreSQL response messages. A DataRow in there is already a valid PostgreSQL DataRow that we can send to the client. Of course we still have to decode the ExecuteResponse protobuf to get the raw byte slice. That still leaves us with one byte slice. What we avoid is a protobuf object for every row, another slice of lengths for that row and a value for every column.

That doesn't mean the router ignores the response. NewQueryResponse walks the five-byte message headers, validates the lengths, handles CommandComplete and finds the region containing the DataRow and NoticeResponse messages. This is stored as one byte slice in DataRows. We only open it further if the query needs us to.

For the examples here, we'll use an orders table sharded by account_id:

CREATE TABLE orders (
    id uuid NOT NULL,
    account_id bigint NOT NULL,
    status text NOT NULL,
    created_at timestamptz NOT NULL,
    total numeric NOT NULL,
    PRIMARY KEY (account_id, id)
);

A result we don't need to decode

The simplest example is a point lookup:

SELECT id, status, total
FROM orders
WHERE account_id = $1
  AND id = $2;

Because account_id is the sharding key, Neki needs the value in $1 to pick the shard. It doesn't need to understand id, status or total when they come back. Those values only need to make it from PostgreSQL to the client. We can use the same approach on the way into the router too.

Bind parameters are rows going the other way

With PostgreSQL's extended query protocol, $1 and $2 arrive in a Bind message. Each parameter is length-prefixed as a column in a DataRow:

NULL:     Int32(-1)
non-NULL: Int32(length), followed by value bytes

The difference is where the format comes from. Bind includes format codes for its parameters, while the formats for DataRow columns come from RowDescription. The PostgreSQL protocol message documentation has all the details if you want to know all the fun little bits about the protocol.

Neki keeps the original Bind message and a cache for the parameters it has decoded. For our point lookup, the router scans the parameter frames, decodes the bigint in $1 and caches it. We don't need $2 for routing. When the query is sent to the shard, Neki writes the original parameter frames directly as long as the client encoding hasn't changed.

Keeping the original frames also helps when we rewrite a query. A rewritten query might use only some parameters, put them in a different order or use the same one multiple times. A mapping like [1, 0, 1] copies the parameter frames into a new Bind. We can use the same approach when adding parameters to the existing list.

Nested loop joins have a similar case. A column from a row on the left becomes a parameter for a query on the right. Neki copies the complete length-prefixed column frame from the DataRow into the new Bind. We only turn the join key into a typed value if we also need it for routing or evaluation.

Text stays text and binary stays binary

There is one more wrinkle: PostgreSQL values can be sent as text or binary. The client uses Bind to tell PostgreSQL which formats it used for the parameters and wants for the result columns. Instead of up-front conversions like Vitess would require, Neki keeps values in the original formats.

When a query selects id and account_id but orders by created_at without selecting it, id and account_id use the formats requested by the client. The extra created_at column uses binary because only Neki needs it. The client will never see those column values.

If Neki needs to decode a value, RowDescription tells it whether to use the text or binary decoder. If it doesn't, the bytes stay untouched. When Neki produces a new value, it uses the format requested by the client.

Conversion is still needed if client_encoding changes between Bind and Execute. Affected text parameters are recoded before they are sent to PostgreSQL. The other parameters stay as they are.

Now let's go back to the result from the point lookup. DataRows can hold one raw byte slice, a slice of rows that point into those bytes or a slice of pointers used to select and reorder those rows. It only creates the next representation when a query needs it.

In this case, Neki writes the raw bytes straight to the client.

No DataRow structs and no columns! Just the PostgreSQL messages that we already had in the correct Postgres wire format. This also works for cross-shard queries. In the query below, status isn't the sharding key so it will have to get passed along to every shard to collect results:

SELECT id, account_id, status
FROM orders
WHERE status = 'pending';

There is no global order and no sums / averages to calculate across the results. This means we can optimize. After sending the scatter queries, Neki streams response chunks from each shard, combines the separate CommandComplete messages with Collapse, and DataRows can be passed along unmodified. It's a "complex" distributed query, but there is nothing in the rows we need to decode.

Adding LIMIT

Now let's add a limit:

SELECT id, account_id, status
FROM orders
WHERE status = 'pending'
LIMIT 100;

Now we need to know when we've sent 100 rows, which means the response cannot be an opaque byte slice. Limit calls DataRows.Len(), and on the first call we walk the raw response and count the DataRow messages so the row slice can be allocated once. In a second pass, we create the DataRow wrappers which all point into the original response buffer.

Once we have the row boundaries, Limit builds a pointer slice for the requested window:

ptrs := make([]*runtime.DataRow, n)
for i := range n {
    ptrs[i] = response.Rows.Row(int(startIdx) + int(i))
}

response.Rows = runtime.NewDataRowsFromPtrsWithNotices(
    ptrs,
    notices,
)

ptrs is the third representation in DataRows. It lets us take a subset of the rows or put them in a different order without moving row messages.

For this query Neki knows where every row starts and ends. What it doesn't know is the value of a single id, account_id or status column. Counting rows doesn't require that... but what if it did?

Sorting means decoding the sort key

For a pending orders page, we'd probably want a stable sorting:

SELECT id, account_id, created_at
FROM orders
WHERE status = 'pending'
ORDER BY created_at DESC
LIMIT 100;

Each shard sorts its subset of results (within Postgres), but the router has to merge those distinct result sets into a global order. Now we finally have to decode a column. First we need the rows, the same as for LIMIT, and then we need to find created_at inside each row.

At the protocol level, a DataRow keeps the complete PostgreSQL message and a view of the bytes containing its columns. The column bytes start after the five-byte message header and the two-byte column count. Each column has a four-byte length followed by the value bytes. A length of -1 means NULL.

To get to the third column, we have to read the lengths of the first two columns and skip their payloads. Reading the lengths of these columns doesn't decode the values. We now know where id and account_id are, but the bytes still have no meaning to the router. With the offsets, we can jump to the correct bytes to grab created_at for each row.

These timestamps are cached because a row will normally be compared more than once while merging results. At this point all rows have been exposed and we've looked at their column framing. The actual values look like this though:

id          frame located, payload not decoded
account_id  frame located, payload not decoded
created_at  frame located, payload decoded and cached

The merge produces another DataRows with pointers to the original rows, now in the right order. Sorting rows doesn't require copying the rows.

Dropping a column without decoding

A small change can have a big impact on what work we can and cannot skip. How about we don't select created_at:

SELECT id, account_id
FROM orders
WHERE status = 'pending'
ORDER BY created_at DESC
LIMIT 100;

Ordering by a column without returning it is a very normal query, but it does give the router one extra problem. The shards have to return created_at because Neki needs it for the merge. Before we send the rows to the client, that extra column has to be removed.

Recall from the last section that by the end we reached the point where created_at had been decoded, but id and account_id were still only protocol frames. For this one, there's more to do.

The naive implementation would read id and account_id as values, build a new row and serialize them again. That's a lot of work to remove a few bytes from the end of a message.

Instead, SimpleProjection stores the projection as runs of adjacent input columns. Each run contains the first and last column, so {0,2} is one run covering columns 0, 1 and 2. This lets ProjectInto copy all three column frames as one byte range. Skipping, reordering or duplicating columns creates more runs, stored in output order:

stored runs          byte ranges copied
[{0,2}]              columns 0–2 in one copy
[{0,2}, {4,6}]       columns 0–2, then 4–6 in two copies
[{3,3}, {0,2}]       column 3, then 0–2 in two copies
[{0,0}, {0,0}]       column 0 twice in two copies

Our query needs only one run, {0,1}. At execution time we find the byte range containing both length-prefixed columns, write a new DataRow header with a column count of two and append both columns at once.

The byte-backed projection does one append per run. Values is the row's view of the column bytes, and offsets contains the frame boundaries found while scanning it:

for _, r := range runs {
    dst = append(
        dst,
        dr.Values[offsets[r.Start]:offsets[r.End+1]]...,
    )
}

This isn't zero-copy because we are creating a different PostgreSQL message. The new header and the columns have to go somewhere. We do copy the exact id and account_id frames though, still saving a good amount of work through careful optimization.

Normally we're projecting a complete response batch, not one random row. Neki appends all the new rows to one shared wire buffer. The finished rows are then bounded views into that buffer, so there isn't a separate backing buffer for every output row.

The slightly funny part is that we decoded created_at, which the client didn't ask for, and didn't decode id or account_id, which it did ask for. That's exactly the work this query required. In Neki, we take every opportunity to skip unnecessary work.

When we really need values

Of course some queries do require the router to understand and produce values. A cross-shard aggregate is a good example:

SELECT status, count(*)
FROM orders
GROUP BY status;

The same status can exist on many shards, so we can't rely on PostgreSQL to do the full GROUP BY. The Neki router must handle it.

We need the group key and the partial counts as values. There isn't a useful byte-level trick for grouping equal values and adding the counts. The final count is also a new value produced by the router, so there are no original PostgreSQL bytes to copy.

For a row like this, we cannot get away with just passing along bytes from Postgres to clients.

When a results row from this query is sent to the client, Neki serializes those values into a new PostgreSQL DataRow in the format the client requested. This query MUST go through every layer:

response messages
    -> result batches
        -> rows
            -> column frames
                -> typed values
                    -> newly computed values

Bytes and values at the same time

Neki doesn't have one internal row representation. A row received from PostgreSQL starts wire-backed, while a row produced by an aggregate can be completely value-backed. The sorted rows from a few sections ago are a mix of the two: they keep the original message and have a cached created_at value.

Original: complete PostgreSQL DataRow

values[0]: no decoded value
values[1]: no decoded value
values[2]: decoded created_at

The original message is still available for forwarding or projection, while the cache avoids decoding created_at again every time the row is compared.

Cached values survive projection too. If a projection keeps or moves a decoded column, Neki copies the original frame and remaps the cached value to its new position. We took the performance hit in decoding the timestamp because the query needed it, but we want to make sure we don't decode or serialize it again.

For PostgreSQL records this can also be necessary for correctness. A record can have a transient typmod describing it, which isn't always recoverable from the wire bytes. Raw projection won't allocate a cache in the case where none of the projected columns have decoded values.

Using this trick elsewhere

This way of working with protocol frames isn't limited to sorting and projection. For joins, we decode the keys needed to match rows. The output can still be assembled from contiguous runs of columns from the left and right rows. We avoid doing the extra work of producing values whenever we can!

When we need to spill rows to disk, we also keep things in the self-framing PostgreSQL DataRow format. We can write and read from disk with minimal additional decoding overhead.

Keeping bind parameters in their original length-prefixed representation is not just about performance either. Parsing and serializing a value isn't guaranteed to give us identical bytes. A floating point NaN payload, for example, can survive PostgreSQL's receive function but change when it is sent again.

PostgreSQL extension types are another useful case. The router might have no idea how to evaluate a value from an extension, but it can still pass the protocol bytes through.

Keeping the layers composable

The nice part of this model is that each representation builds on the previous one. DataRows can start with raw response bytes, expose those bytes as a row slice and then add a pointer slice for a subset or a different order. An individual row can keep its original PostgreSQL message while also caching the values that have been decoded. Going one layer deeper for one part of a query doesn't force all columns / values to do so.

Of course that doesn't make the complexity disappear. Byte-level projection still has to calculate the right offsets, write a new message header and copy the right column frames in the right order. The key thing for Neki's performance though, is that it's all contained in the row projection and batch builder.

It also gives us a small surface we can test directly. The projection tests construct PostgreSQL messages byte by byte and cover reordering, NULL, empty strings, empty bytea, duplicate columns and the protocol-backed path.

There are a few invariants we have to maintain for that containment to work. Shared response buffers have to remain alive as long as a row still points into them. We use three-index slices because an append through one row must not overwrite the next PostgreSQL message in the same buffer. Two consumers replaying the same buffered row need their own row wrapper and value cache, while the immutable protocol bytes can still be shared.

Memory accounting also has to know that a row can grow. It starts out retaining the wire bytes, but every string, numeric or record added to the cache uses more memory. And then it all has to work with NULL, text and binary formats, client encodings, arrays, domains, records and user-defined types. If moving the bytes around changes the result, we've built a very fast bug 😉.

Nothing is still the fastest

Neki does a lot of real work. It routes queries and sometimes has to merge, compare, group or compute values across shards, but it doesn't have to do all of that for every column in every query. A point lookup can keep the result as PostgreSQL messages. LIMIT needs row boundaries. Sorting needs the sort keys. Projection can move existing column frames around. An aggregate generates newly computed values because there is no earlier layer where it can stop.

For every query the router tries to do the least possible work. The best way to make software fast is to avoid work at all costs.

Real Postgres

Neki is built as a sharding and scaling solution for real Postgres. It's not a fork, nor a wire-compatible reimplementation, nor a MySQL sharding idea wearing a Postgres label. Neki uses ordinary PostgreSQL instances that store rows in Postgres data pages using MVCC, carry out transactions, and work as you would expect with psql and other Postgres drivers. Neki builds around those instances to let you shard them, scale them, and manage them as one database.

Let's take a look:

PostgresManager

Using vanilla Postgres means Neki needs a way to run and manage each instance. That includes starting and stopping Postgres, owning its data directory, and configuring replication so a new instance can join a shard. PostgresManager handles this coordination, running as the first process in the Postgres container and managing the postgres process directly.

Sidecar

Postgres uses a separate backend process for each connection and limits how many can be open at once. Neki’s Sidecar sits in front of each instance and pools connections, letting many client connections share fewer Postgres backends.

The Router, which is the component that accepts external client connections, communicates with the Postgres nodes via these Sidecars.

It also reports each Postgres instance's health and whether it is a primary or replica, so the rest of the cluster knows whether it can receive write queries.

The pool doesn't treat every connection the same way. The length of time a connection is checked out for use varies depending on what it's being used for. A multi-statement transaction holds on to its connection until commit or rollback. A session-scoped advisory lock needs a connection of its own, because the lock has to outlive whatever transaction is open at the time and can't share that connection. Everything else checks a connection out and hands it back the moment the statement finishes.

The Sidecar knows which of the three to use because the Router sends the necessary information with the query: autocommit, an open transaction, or a session that has to stay on one backend.

Shards

Each Postgres instance gets its own Sidecar and PostgresManager pair. Real deployments need more than one instance: a primary and its replicas. Neki calls that group a shard, the unit it splits data across. It's always advised to run a shard with a primary and 2+ replicas for high availability, as well as for additional read query capacity.

A shard is considered one Postgres cluster. Its replicas are physical copies of the primary, so they share a catalog and the same object identifiers.

Object Identifiers (OIDs) are how Postgres tracks objects internally, rather than by name. A client reads a column’s type OID off the wire to interpret its bytes and may cache that OID for later re-use. A custom type therefore needs to carry the same OID no matter which shard answers the query. Independent shards can assign that type different OIDs, so Neki designates one shard in the entire Neki cluster as the authoritative shard. This shard is the source of truth for translating custom type OIDs in responses from other shards to match. It ensures OIDs are consistent across the many shards of the Neki cluster.

The authoritative shard's Sidecar also watches for schema changes and reports them to the Routers. This keeps the Routers' view of the schema current when a table is renamed or a column is dropped.

Admin

In a distributed system, instances can fail independently while the rest of the system lives on. Neki is no different. A primary or replica can go down at any moment while its fellow instances on the shard are healthy. The Admin's job is to detect failures, promote a replica, and maintain each shard’s durability policy.

It health-checks every Sidecar, tracks replication lag for each replica, and decides when a shard needs a new primary. When a primary goes down, it coordinates an emergency failover, promoting a replica to take its place. It can also coordinate a planned switchover, which are needed for intentional node resizes and version upgrades. In both situations, Admin uses pg_rewind to bring diverged instances onto the new primary’s timeline, copying only the data that changed since the timelines diverged.

Each shard has a durability policy that determines when a commit is acknowledged:

• Async: The primary acknowledges the commit without waiting for a replica.
• Sync: The primary waits for a replica to confirm the commit, protecting against the loss of a single node.
• Cross-zone sync: The primary waits for confirmation from a replica in another availability zone, protecting against the loss of the primary’s zone.

Postgres enforces whichever one is configured, using its own synchronous replication machinery. The Admin keeps that configuration correct as replicas join or leave shards, or a failover moves the primary to a different zone.

Much of Admin’s work, however, doesn’t involve changing the primary. It repoints replicas to the correct replication source and corrects roles when Postgres and the topology disagree.

Operator

Neki’s components need to be deployed, updated, and replaced when their machines fail. Neki is built Kubernetes-first, and the Operator manages this full lifecycle.

The Operator models a cluster as a hierarchy. A cluster owns routers and shards, and each shard owns the pods running its Postgres instances and Sidecars. When the Neki cluster configuration changes, the Operator works out which pods need to be created, updated, or removed.

How it replaces an instance depends on whether that instance is still running. For a live instance, the Operator builds a replacement and confirms it has caught up before deleting the old one. If a node fails and loses its ephemeral storage, the Operator rebuilds the lost instance from scratch once its safety checks pass.

Admin and the Router handle the database side of those disruptions. Admin coordinates a switchover for planned primary replacements or a failover when a primary goes down. The Router can buffer queries that are safe to retry while a healthy primary becomes available.

Router

We've talked a lot about how the Neki cluster operates and handles failure internally. What we've yet to dive into is how applications use the thing!

The Router is the entry point for clients connecting to a Neki cluster, presenting a single Postgres wire-protocol endpoint to connect to a (potentially) massive sharded database. Applications use Postgres drivers to send SQL and open transactions without managing connections to individual shards.

Authentication and role checks are done as if it were the Postgres instance itself, and the protocol's own extended-query flow and prepared-statement lifecycle are all built into the Router.

Once a query arrives, the Router runs a Postgres-compatible parser against the authoritative shard's catalog, plans it against the current sharding layout, and sends it to whichever Sidecar needs to run it over gRPC.

Not every query can run on a single shard. A join may need data from several shards or an aggregate may need to read from all of them. The Router coordinates that work as a distributed query.

Whenever possible, it leaves the work to the Postgres instances. If both sides of a join are on the same shard, the Router sends the join to that shard. When a join needs to run across shards, the Router executes it itself, choosing between nested-loop, hash, and merge joins based on cost estimations.

Earlier, we covered how Admin promotes a new primary during a switchover or failover. If that happens, the Router can buffer queries, giving the Admin time to complete the handover. For queries that can safely be retried after failing against a primary, the Router buffers the query and waits, for a fixed time, for a healthy primary. Once a healthy primary is available, the Router releases queued queries gradually.

Data Topology

Router, Sidecars, and Admin all need a consistent picture of which shards exist, what key ranges they own, and which tables are sharded at all. If the Router's copy is wrong, a query can land on the wrong shard. This is all specified with a Data Topology, and etcd holds the single, authoritative copy of it. When the Data Topology changes, the Router, Sidecars, and Admin pick up the updated configuration without a restart or manual synchronization.

The Data Topology defines shard groups, named sets of physical shards, each owning a range of routing keys. Each table belongs to a shard group. Shard indexes specify the columns or expressions and the strategy used to turn row values into routing keys. Those keys determine which shard receives each row.

Replicator

As a database grows, its layout may need to change. Tables need to be imported, shards need to be split, and schemas need to change all while applications keep using the database.

Neki's Replicator handles the data movement behind all such operations. It runs as a separate process colocated with a shard's Sidecar and Postgres. It is responsible for copying existing rows to new destinations, and also keeping the data current by decoding changes from a Postgres logical replication stream and applying them as SQL.

Three workflows use the Replicator:

• MoveTables relocates a set of tables, including imports from an external Postgres instance
• Reshard redistributes data across shard key ranges, allowing a shard to be split when it outgrows its capacity
• OnlineDDL changes a table's schema by building a shadow table alongside the original and keeping it current through the same change-data-capture pipeline MoveTables and Reshard use to relocate rows. A final rename swaps the new table into place. This supports changes such as repartitioning a table, alongside changes that would otherwise require a blocking operation.

Once the data has been copied and the destination is caught up, the workflow switches from the original tables or shards to their replacements. This is the cutover. The Router uses the same buffering mechanism that handles primary changes for this step. It buffers queries during that switch and releases them afterward.

Together, these components let Neki scale Postgres horizontally while presenting a single database to applications.

Get started

Neki is in Platform Preview right now.

Start a Neki cluster today: build on it from scratch, or import an existing Postgres database.

Neki is built from lessons we’ve learned over eight years of running some of the largest sharded MySQL clusters in the world. Thousands of production workloads with millions of queries per second for companies where even a few seconds of downtime is a very public event. We know what it means to power the world’s biggest tier 0 workloads.

When we released PlanetScale Postgres a year and a half ago, we knew we needed to do more. In that time we’ve onboarded several thousands of customers on PlanetScale, some of them rivaling the size of our largest MySQL customers. Time and time again, we watched teams approach the ceiling of a single machine with Postgres. Metal bought them time, but with customers hitting the upper limit of what a single machine is capable of, we found there was no good option to hand them. Enter Neki.

What is Neki?

Neki is sharded Postgres from PlanetScale. It lets you scale a Postgres database across many machines while keeping real Postgres on every shard.

Your application connects to a Neki router over the standard Postgres wire protocol, so your existing drivers, ORMs, and connection string keep working. Each shard is a full Postgres cluster with one primary and at least two replicas across 3 availability zones. There is no custom storage engine, so extensions, SQL support, and performance behave the way Postgres does.

You choose the shard key and control how tables are grouped and distributed through a JSON data topology. Schema changes, version upgrades, failovers, imports, and resharding all run as built-in fully online workflows. You also get the PlanetScale features you already rely on, including Insights, schema recommendations, branching, and MCP.

You don't have to shard on day one. Run Neki as a single primary with replicas, and when you outgrow one machine, resharding is a workflow you run against the cluster you already have.

Why Neki?

You already know the problems that come with fast-growing Postgres databases: tables too large to vacuum or index without affecting traffic, backups taking hours, connection limits, maintenance windows for schema changes, transaction wraparound and so much more.

You can move to a bigger instance, but eventually you run out of big enough machines, and the problems don’t scale linearly as you add more cores and IOPS.

The existing answers each ask you to give something up. Application-level sharding pushes routing into your code. Postgres-”compatible” distributed databases hide the shard key from you, take away your extensions, and add complexity and latency which becomes difficult to handle and debug.

So we built Neki with a few principles, the biggest one being: stick to Postgres, don’t work around it, fake it, or turn away from it.

How does Neki work?

We architected Neki from first principles for Postgres, with real Postgres on every shard. There are four moving parts.

Neki routers

Your application first connects to a Neki router. The router speaks the Postgres wire protocol so your existing drivers and ORMs keep working with a single connection string. A router has a full Postgres query parser, a distributed query planner, query buffering and more. It parses your query, builds a plan that decides which shards should run it, sends the work out, and combines the results back into one stream. Routers can scale vertically and horizontally, so no single router becomes the bottleneck.

Sharding and shard groups

Every shard in Neki is real Postgres with 1 primary and at least 2 replicas, spread across availability zones. There is no modified storage engine. Extensions, SQL support, and performance behave the way Postgres behaves, because it is Postgres.

Shards are organized into shard groups, so different tables or workloads can live on different sets of shards. Each shard uses a configuration profile that defines its instance size, replica count, storage, Postgres parameters, and extensions, so you can size each group for its own traffic.

Connection pooling

Sidecars run alongside every Postgres instance. This is the piece that makes Neki's connection handling meaningfully better than just sticking PgBouncer in front of a database. Because Neki controls both ends of the connection, the router side and the Postgres side, it can size pools to what each instance can actually serve instead of estimating from outside the process.

Control plane

The control plane tracks the health of every node, runs planned switchovers and unplanned failovers, and coordinates the workflows that reshard data, apply schema changes, and perform version upgrades.

Data topology

Tying it together is the data topology, a JSON configuration that maps your logical tables onto physical shards. You define shard indexes, which specify the column Neki routes on and how that value gets hashed, and shard groups, which control how many shards a set of tables spreads across and which shards those are. Routers cache the topology and consult it on every plan.

What you get beyond sharding

Everything you would normally schedule a maintenance window for runs as a built-in workflow in Neki. Workflows provision new target nodes, catch them up with replication, switch traffic with a __neki metafunction, and retire the old nodes. All through the same psql connection your application uses.

This online operations model covers schema changes, version upgrades, planned and unplanned failovers, imports, and resharding.

Neki also includes all of the features you’ve come to rely on with PlanetScale: Insights, schema recommendations, branching, MCP, and more.

You can also run Neki unsharded, as a single primary with replicas. You get the improved connection pooling, online DDL, zero downtime upgrades, and health monitoring before you need to shard. When you do, resharding is a workflow you run against the cluster you already have.

What is a platform preview?

We wanted to get Neki into your hands as soon as possible. You should not run production workloads on Neki during the platform preview. The product is still changing, and some of those changes will be breaking.

If you have any feedback, questions, or face any issues during the platform preview, please let us know. Fill out a support ticket or join our Discord

Try Neki today

Sign in to PlanetScale, opt in to the platform preview, and create a Neki cluster. Read the Neki docs for more information about Neki's architecture, how to shard, and more.

If you have a large Postgres cluster and are curious whether Neki is a good fit, get in touch. We would love to do a private demo for your team, dig into your schema and query patterns, and give you real suggestions on how to shard.

You've just been paged. Every query is failing to execute. Find out why.

Years ago at GitHub, this was a question Sam Lambert would ask in interviews.

The solution involved a downed database that started with a MySQL schema change needing an exclusive lock on a table, but it couldn't get one. Another session had already touched that table and never committed. That open transaction blocked the schema change.

Once the schema change was waiting, new queries on the same table queued up behind it. Nothing was deadlocked. Nothing would time out on its own. The whole pile-up sat there until someone found the connection at the top of the chain and killed it.

(By the way, you'd avoid this MySQL lock on PlanetScale Vitess since ALTER would have been an online schema change, copying in the background and only taking a brief lock at cutover.)

This isn't rare, and it isn't exclusive to MySQL. You can reproduce the same pile-up on Postgres just as easily.

Want to see a stuck database?

You won't need elevated permissions. A normal application connection is enough.

All it takes is an unhandled exception and a poorly timed migration.

Say you have a Postgres database with a hot table named orders.

On one connection, a transaction begins a SELECT query, but the app throws an exception.

-- Connection A: Ordinary application user
BEGIN;

SELECT * FROM orders WHERE id = 123;

-- ...then the app throws an exception 💀

The SELECT query finished, but Postgres keeps holding the connection, waiting for the transaction to end with COMMIT or ROLLBACK, which it never does because of the app's thrown exception.

While Postgres waits on that connection, another connection attempts to run a migration.

-- Connection B: Migration role waiting on lock
ALTER TABLE orders ADD COLUMN foo integer;

The SELECT query only needed a read lock (ACCESS SHARE). The migration needs a lock that blocks all other access (ACCESS EXCLUSIVE), so it waits.

Postgres will not let later queries jump the queue. Every new query on orders waits behind the already-stuck migration, which is itself stuck behind the initial SELECT connection that never closed.

-- Connections C, D, E, etc: Waiting on the lock
SELECT *
FROM orders
WHERE customer_id = ?;

If the app doesn't handle errors gracefully and depends on quick responses from orders, you've got downtime.

Not because of a hack, but because one unhandled exception prevented a COMMIT, kept a connection open, blocked a migration, and that migration blocked everything else.

By the way, this is preventable. It happens because the default for idle_in_transaction_session_timeout is disabled. Give it a value and Postgres times out transactions that haven't closed.

Freeing a stuck database

Debugging the state of connections in MySQL and Postgres can be clunky.

As covered in See what your database is doing right now with Connections it is possible to run a query on a loop in your terminal to see active connections. But it's not an ideal interface.

It also depends on your database having spare connection slots. The worst-case scenario is your database is overwhelmed with connections that haven't been closed, meaning even you can't connect to debug and kill them.

Because this experience is so terrible, we've added the ability to view and kill connections in Postgres and MySQL databases on PlanetScale.

Connections in the dashboard

PlanetScale's connections tooling uses a reserved administrative connection so it can still show you a list of active connections and processes even when connections are exhausted and your application can't connect.

In the PlanetScale dashboard, you can now click the Connections tab to view a live list of connections. You'll see a bunch of useful columns like Process ID, State, and Duration, but most importantly, you will see a column for Blocked Queries.

From here, it's easy to see which connections are currently blocking others from proceeding. You can click into any connection to see more details, such as the query currently being performed by that connection.

Kill process gives you three options, from least to most disruptive:

• Cancel query stops the running statement and leaves the connection open, so the app can send another query
• Terminate transaction rolls back the open transaction and closes the connection, but only if that same transaction is still running
• Terminate connection drops the backend entirely, whether it is idle or mid-query

Thinking back to the downtime example, the idle SELECT had already finished, so canceling the query will not release the lock. In that scenario you would need to terminate the transaction or the connection.

Over on Vitess, each process has two options: cancel the query or terminate the connection. In a sharded database, you can view the process list per keyspace and shard.

Connections via CLI

If you'd rather work with a terminal UI, launch:

pscale branch connections top <database> <branch>

This opens an interactive live view that refreshes about once every second. The most important connections are sorted toward the top. You can navigate through the view using keyboard shortcuts and open any connection to see more details.

If your agents prefer the current state of connections in JSON, use this one-shot command instead of the live view:

pscale branch connections show <database> <branch> --format json

That output includes the IDs needed to cancel a query or terminate a connection, which you can still require confirmation for. See the CLI reference for the kill commands that go with it.

Migrate today, stress less later

The correct answer to land your dream job today is "Use PlanetScale."

Next time you're paged because everything is erroring, I hope you've already migrated over. The interview answer hasn't changed, but connection management on PlanetScale has made it easier than ever before.

Product success leads to lots of data, lots of data leads to big tables, but big tables lead to predictable problems.

A table can be large (many rows), wide (many columns), or "fat" (oversized values). Any of these can cause you problems.

How a large table can cause an outage

First, let me tell you a story.

A customer had two tables, A and B. Table B is large and unpartitioned. It has a foreign key to A with cascade delete turned on. A single delete on A has to delete every child row in B. That can be 100s or 1000s of rows in B for every one in A.

In this customer's case, deletions from A ran in a background job and attempted to remove around 100,000 rows from A. The deletes took so long that they timed out. The job retried. Each attempt generated a pile of WAL (the write-ahead log Postgres uses to record every change), which saturated the network and CPU between the primary and its replicas. This caused the replicas to lag.

The application checked replica LSN (a replica's position in that WAL stream) before sending a read to a secondary. The secondaries were not caught up, so every query went to the primary.

The primary was already busy writing WAL. It also had to respond to all of the reads. And so a simple cascade delete on a large table quickly became an outage.

Possible fixes for a large table

The problems covered in this post are common to all Postgres databases but are made worse by those containing large tables. You might reach for one of a few solutions, which we'll examine throughout.

Partitioning splits a large table based on a key value. For example, if your large table stores rows with a specific date, such as when an event occurred, cutting that table into partitions of months or years creates more, smaller, and more manageable tables.

This can be useful for some large-table problems.

Vertical scaling refers to adding more resources to make more space or brute-forcing your way out of performance bottlenecks such as increasing CPU, RAM, or buying larger and faster disks.

It's almost always a band-aid solution that only hides the real problem.

Sharding (horizontal scaling) splits the large table, or the entire database, into separate database clusters connected by a router to act as one. Just as Vitess is sharded MySQL, Neki is sharded Postgres.

With more, smaller, and isolated database clusters, almost all of your expected large table problems are resolved. More on that later in the post.

Slow, late vacuum

You may already know that deleted rows in Postgres aren't automatically removed; they are marked for deletion. These marked rows hold space until the vacuum process reclaims it. Read Every UPDATE leaves a ghost to learn more.

What you might not realize is that vacuum runs per table.

Vacuuming a single large table can tie up a worker for a long time. Vacuum uses a ring buffer so it does not evict the rest of shared_buffers (Postgres's shared page cache), but on a table larger than RAM it still competes with user queries for the same disks.

Large tables take longer to vacuum, and they also wait longer to start.

On Postgres 17, the default trigger is 20% of the table. A table with ~500 million rows needs ~100 million dead tuples before autovacuum begins. You can modify this value cluster-wide or per table by changing autovacuum_vacuum_scale_factor.

Postgres 18 added autovacuum_vacuum_max_threshold with a default value of 100,000,000. So a billion-row table triggered autovacuum at 100 million (still a high number) instead of 200 million. Below 500 million rows, the old scale factor was still in play.

Postgres 19 adds parallel autovacuum, off by default. Extra workers can finish one large table faster, but that still doesn't change when vacuum starts.

Autovacuum also runs ANALYZE, which has the same default-doesn't-scale problem. It samples a fixed number of rows no matter how large the table is. So the planner's estimates potentially get worse as the table grows. Raise the target with ALTER TABLE ... SET STATISTICS on the columns the planner actually needs to get right.

Vacuum on large tables is late to start, slow to finish, with more dead rows while it runs. Each cycle is worse than the last, even when vacuum reports success.

Partitioning can be a good first move to split your large table into more reasonable-size chunks, if it has a suitable key.

Partitioning also helps avoid autovacuum's late start. Each partition is its own smaller heap, so the 20% trigger fires after far fewer dead tuples. Workers vacuum partitions in parallel and ANALYZE samples a smaller relation.

Disks and shared_buffers are still shared with the rest of the cluster, so it's not a perfect solution.

Vertical scaling can help more workers finish sooner with faster disks. That does not change the trigger on one huge heap, and the table may still not fit in RAM.

Sharding (horizontal scaling) gives you the best of both worlds. Smaller tables on smaller databases, each with their own isolated resources.

Sharding also solves foundational parts of Postgres that can't be resolved by more resources.

Every write transaction gets a 32-bit ID, and vacuum uses these IDs (xmin) to decide which row versions are still visible. These IDs are cluster-wide, not per-table. Vacuum freezes old tuples so XIDs can be reused; wraparound is the age of the oldest unfrozen XID (relfrozenxid in pg_class), not how many XIDs the database has ever issued. If that age reaches around 2.1 billion, Postgres goes into read-only mode. Postgres backups under the hood covers transaction wraparound in more detail.

Since each shard is its own cluster, a large table separated across shards is less likely to put a cluster into read-only mode.

Additionally with isolated I/O, any work vacuum does on one shard does not contend with queries on another. ANALYZE becomes a per-shard operation.

Wasted time on incomplete repacking

Vacuum can be prevented from reclaiming space even if it finishes successfully.

Vacuum can't remove a dead tuple while any transaction in the cluster still needs it.

But a slow vacuum on a large table may have wasted its time to completion. Many of the rows it found to remove may still be required by transactions that started before vacuum finished and haven't completed yet. Vacuum will need to walk the entire table again later.

This can be an issue on tables of any size, but is more annoying on large tables as they take longer to complete.

Free space that was successfully reclaimed can be reused for new rows, but the table file usually does not shrink. That leftover file size is bloat.

Should your table get bloated, PlanetScale Insights scans once a day and opens a recommendation when estimated bloat is over 25% and 100MB.

To compact a bloated table while reads and writes continue, enable pg_squeeze on the database's Clusters page (that requires a restart), then run a one-time squeeze or register the table for regular cleanup.

Be aware that pg_squeeze has no throttle. Squeezing a large table can saturate I/O and CPU and cause an outage. Only run it when the cluster has spare capacity.

Partitioning creates more, smaller heaps. So a wasted pass is cheaper and can be retried sooner. Squeeze is per partition, so the spare disk you need to run squeeze is the size of a partition, not the whole table.

Splitting the table does not split the snapshot horizon. xmin is still cluster-wide, so a long query anywhere on the cluster still pins every partition.

You can drop old or bloated partitions instead of compacting them.

Vertical scaling adds more spare disk space, which may be the only reason squeeze can run at all and/or finish sooner. That lets you compact the same large file faster.

Sharding creates distinct Postgres database clusters, so a long query or dump on one shard doesn't pin vacuum on any other. Squeeze runs only on the copy in its shard, not the entire large table. Each cluster tracks its own xmin.

In a sharded database, wasted vacuum passes are cheaper and less likely to happen.

Slow queries hold connections longer

It is impossible to write a Postgres article about performance and not mention that Postgres has a connection-per-process architecture. Connection hygiene matters even more when your database has a large table.

Sequential scans (reading large segments of the table from start to finish), big sorts, and heavy joins against a large table take longer, so they hold connections longer.

Raising max_connections feels like a logical solution to avoid "too many clients already," but this only lets more concurrent connections perform these slow queries. At best, this starves other workloads of new connections. At worst, a traffic spike on your large table is more likely to trigger an out-of-memory (OOM) event.

A large table will not stay in shared_buffers. More processes scanning it means more cache eviction, more disk usage, slower queries, and longer-held connections.

Partitioning splits your large table, which can help queries finish faster (and release connections sooner) so long as they access only one or a few partitions. But cross-partition queries can get worse.

Buy all the RAM and CPU you like with vertical scaling, but you're still not putting a hundreds-of-GB table into cache. You cannot spend your way out of inefficient connection handling.

Sharding spreads your backends across multiple clusters, where each shard-distinct query is shorter and more likely cached.

A connection held by a large table is one the rest of the product cannot use. With workloads spread across shards there may be less overlap.

A scatter-gather query with no shard key can hold more connections, not fewer. Selecting the right key to shard on is critical to seeing performance benefits from sharding.

Slower backups and recovery

Postgres gives you three ways to take a backup. A large table complicates each one in a unique way.

A logical dump with pg_dump writes live rows, so dead tuples stay out of the output. The dump still walks the bloated heap, and it holds a transaction snapshot the whole time. On a small table, that pin is brief. On a large table, the backup is a long-running transaction against the cluster.

A file system backup copies the data directory, bloat and all. Faster than dumping rows. A consistent copy usually means shutting the database down, or relying on atomic snapshots from the file system. You might be okay with a maintenance window for a database of small tables, but a single large table could add hours just to copy one relation.

Continuous archiving copies the data files while Postgres is still running, then keeps the WAL so you can replay through the modified bits and land on a consistent copy. No dump pin, no shutdown. You still copy the large table, bloat, and its indexes. What grows with the table is restore time. How long an incident waits on this heap plus the WAL written while the copy ran.

That third option is how PlanetScale backs up Postgres. We copy the data files and continuously archive WAL on a throwaway node rather than on your primary, so the backup doesn't compete with production queries for disk and doesn't pin the primary.

We can't skip the size of those files. A large table that doesn't fit in memory, plus its indexes, plus its bloat, is what has to land in object storage.

Partitioning rearranges files but doesn't shrink the copy. A pin held during dump is still cluster-wide. A physical backup includes the same bloat even if it is split across smaller tables.

Vertical scaling means faster copies through more resources. But the files aren't any smaller, so restore is only quicker because the disks are faster.

But neither partitioning nor vertical scaling changes the size of the data.

Sharding breaks down backups and restores into smaller, distinct units of work, allowing them to complete much faster. Recovery time depends on the slowest shard instead of the largest table.

Too many indexes

A large table isn't viable to scan from start to finish and is likely queried in many different ways.

To keep queries fast, you keep adding indexes to the table. While indexes make queries fast, they aren't free. They take disk, get vacuumed, get backed up, and make every write touch more files.

There are no good options here. Prune indexes and your queries get slower. Accumulate indexes and pay for it with an enlarged heap, while also vacuuming, packing, and copying many access paths.

The indexes that make a large table usable are part of what makes it too large to keep indexing.

Indexes on a partitioned table are created on the logical table but stored and updated on each partition. Those smaller indexes are faster to build and cheaper to REINDEX.

Vertical scaling buys you more space to store more indexes ... but that's like fixing traffic congestion by adding another lane to the freeway.

Sharding creates more, smaller databases, so having more indexes is less of a problem. You can afford to create many more indexes than if your large table was on a single cluster since a write only updates indexes on the shard that owns that row. Sharding is the good option for balancing a lot of data and many indexes.

Wide tables split across pages and files

A table is not only large because it has many rows; it might be that the rows are wide with many columns, or each row contains a large amount of data.

If a row exceeds ~2KB, oversized values go to TOAST, a separate table and indexes next to the heap you are already struggling to vacuum.

Each toasted value gets a 32-bit OID, about 4 billion per table. Updates of toasted values take a new OID. High-churn wide tables fill that space, and inserts slow down as Postgres hunts for a free one before the hard stop.

Whatever is left still has to fit into a single 8KB page, as Postgres will not split a row across pages. If a tuple cannot fit in the free space on any existing page, it gets a new page.

For a read-heavy table, you want pages packed tight (a high fillfactor), so scans walk as few pages as possible. For an update-heavy table, you want the opposite. Lower the fillfactor so an update can often stay on the same page instead of allocating a new one.

On a small table, the wrong fillfactor is a few wasted pages. On a large, wide table it could be terabytes of sparse pages, or a constant stream of new ones that vacuum, WAL, and backups all have to follow.

A large table is a heap, plus indexes, plus TOAST, and some operations still walk those files one at a time. pg_database_size() is one example. It stats every file in the database serially. On a large, wide table, that can pin a core.

Partitioning is a genuinely good solution for this class of large-table problems. Fillfactor can differ per-partition. Each partition gets its own TOAST table, so OID space is per slice.

However, with more files in one cluster, pg_database_size() can get worse.

Vertical scaling can hide a bad fillfactor for a while with extra disk space. Faster disks make TOAST vacuum and file stat()s cheaper. But you cannot buy greater limits than 8KB pages, the 2KB TOAST threshold, or the 4 billion OIDs.

Sharding creates individual Postgres instances, so TOAST OID space resets per cluster. A bad fillfactor hurts less because the heap is smaller. File walks are per shard.

Sharding does not, by itself, let hot and cold rows use different fillfactors. Partitioning still wins there.

Sharding is the solution to large tables

Just as partitioning breaks up a single table into many small pieces, sharding distributes the workload of your reads and writes across many database clusters.

Let's revisit the cascade delete story.

When replicas lagged, every read went to the primary. On a sharded database, each shard is its own cluster, with its own WAL and replicas. If the affected rows of A and B lived on one shard, that shard could still lag, and its reads pile onto its primary, but that could not fail the LSN check for the rest of the product. If those 100,000 deletes were spread across shards, the WAL burst would be split. No replica stream would have to replay the whole thing.

Your single-cluster large table likely processes a high throughput of traffic. Vertical scaling can help, but sharding does it better. With more clusters receiving and processing writes, a single table doesn't strain the entire cluster.

Additionally, cluster limits that cannot be solved by partitioning or vertical scaling are resolved. Postgres' hard-coded ceilings of 32-bit XIDs, TOAST OID and more become per-shard limits instead.

Sharded database backups are individually smaller and can be massively parallelized, making database restoration faster as well. Operations finish at the time of the slowest shard, not all at once waiting on large, bloated tables.

Cache eviction is a problem with large tables and their working sets. While more resources won't fit a large table into RAM, you often can per shard. Shard-local queries become shorter and faster.

Neki, sharded Postgres, lets your application write queries as if it were a single database, while splitting a large table into smaller, automatically distributed parts.

It contains the logic for where to send reads and writes. You still have to determine how that data is spread. That fan-out is covered in our post on data topologies.

Sharding shares the large table load across multiple clusters. If that's a problem you need solved, sign up for a PlanetScale account to use Neki today.