Sharding Postgres Without Leaving Postgres

Figma's database stack has grown almost 100x since 2020: the kind of problem a business wants, and the kind an infrastructure team has to stay ahead of. In 2020 the company ran a single Postgres database on AWS's largest instance. By the end of 2022 the team had a distributed setup with caching, read replicas, and a dozen vertically partitioned databases, each holding a group of related tables like 'Figma files' or 'Organizations'. Figma's earlier post on scaling to multiple databases frames vertical partitioning the same way this one does: an easy, high-impact lever that bought real runway, and a stepping stone toward the real goal, horizontal sharding, not the finish line.

Staying ahead meant measuring where the limit actually was. As the fleet grew, the team combined historical data and load testing to quantify each database's limits (CPU, IO, table size, rows written) and predict the runway left per shard. The data showed that some tables, at several terabytes and billions of rows, were becoming too large for any single database. Reliability began to suffer during Postgres vacuums, the background cleanup that keeps Postgres from running out of transaction IDs and breaking down, and the highest-write tables were on track to exceed the write speed Amazon RDS could give them. Vertical partitioning could not save them, because its smallest unit is a single table.

The two moves are different in kind: vertical partitioning moves whole tables onto separate servers, while horizontal sharding spreads one table's rows across servers. Only the second can relieve a single oversized table.

TWO DIFFERENT CUTS

The obvious exits were all one-way doors. The team evaluated CockroachDB, TiDB, Spanner, and Vitess, but moving to any of them meant a complex migration across two different database stores and setting aside years of hard-won expertise running RDS Postgres. With only months of runway at Figma's growth rate, proving a whole new storage system safe while migrating the most business-critical data was judged too risky; the team favored known low-risk options over easier-looking ones with more uncertainty. NoSQL was ruled out on its own grounds: Figma's product runs on a complex relational data model (file and organization metadata, comments, file versions) that NoSQL APIs can't express, and adopting one would have meant rewriting almost the entire backend.

That left building horizontal sharding on top of the RDS Postgres the team already ran, without reimplementing a general-purpose sharded database in-house and competing with open-source projects and database vendors. Because the solution was tailored to Figma's architecture, it could ship a much smaller feature set. It skipped all-or-nothing writes that span shards, grouped related tables so application code barely had to change, and supported only the slice of Postgres the product actually used. And the sharded and unsharded versions stayed compatible, so the team could roll back if something unexpected went wrong.

The project began with an unusually explicit goals list that explains most of the design:

• Minimize developer impact, so product teams keep shipping instead of refactoring.
• Scale out transparently, so future shard splits need no application changes.
• Skip expensive backfills, which at Figma's table sizes would have taken months.
• Make incremental progress and avoid one-way migrations, keeping rollback possible after a physical split.
• Keep strong consistency without tricks like double-writes, and play to the team's strengths under deadline.

The first decision was the shard key, and Figma's answer diverges from the textbook. No single column worked across the data model, and a unified key would have meant a new column on every table, backfills, and heavy refactoring. Instead the team chose a handful of keys, UserID, FileID, OrgID, so almost every table could shard by one. Related tables sharing a key are grouped into 'colos' that share one shard key and physical layout. Inside a colo, joins and transactions still work as long as they stay within a single shard-key value, which is how most code already queried.

Many of those keys either counted up in order or started with a timestamp, so most rows would have piled onto a few shards. Rather than migrate to random IDs, the team routes on a hash of the shard key for an even spread, trading away efficient range scans (rare enough at Figma to accept).

The serving stack was rebuilt around DBProxy, a new Go service between the application and the connection pooler (the layer that hands out database connections). It adds load-shedding and retries, plus the query engine at the heart of the system, which runs a short pipeline:

• A parser turns the application's SQL into a tree.
• A logical planner reads it for the query type and the logical shard IDs.
• A physical planner maps those to real databases and rewrites the query for the right shard.

A query that carries a shard key routes to one database; a query without one must ask every shard and combine the answers (a scatter-gather), as expensive as if nothing were sharded. A shadow-planning test harness tried possible schemes against real traffic without affecting it. From that the team picked a query language covering the most common 90% of queries: all range scans and point lookups, but joins only within a colo, on the shard key.

WHY QUERIES NEED A SHARD KEY

The signature move is separating logical sharding from physical sharding. Logical sharding makes a table behave as if it were already split, while every row still sits on one server. Figma builds this with Postgres 'views' (saved queries), one per shard, each exposing just that shard's rows, so the application reads and writes 'shards' that are really still one table. Rollout ran gradually behind on/off flags, and rolling back a bug was a config change that rerouted to the main table in seconds. The views were a risk to prove, not assume, since they add overhead and can change how Postgres plans queries; the team load-tested them (under 10% overhead worst case) against live traffic. By the first real split, the sharded setup had already been running in production.

PRETEND FIRST, MOVE LATER

Routing depends on an always-current map of which rows live on which database, and sending a query to the wrong one is the single failure the team could not tolerate. The team's system pushes updates to that map in under a second and enforces one rule above all: every shard maps to exactly one physical database.

The real split moves data from one database to many, and the switchover had to survive a new failure mode: succeeding on only some shards. The team skipped filtered replication (copying only each shard's own slice) and instead copies the whole dataset to every shard, then limits each to its subset. The first sharded table shipped in September 2023, about 9 months in, with just 10 seconds where some writes failed on the main databases and no slowdowns after. Ahead lie more complex databases (dozens of tables, thousands of call-sites) and a named list of things still to build:

• sharded schema updates,
• globally unique IDs for sharded primary keys,
• all-or-nothing writes across shards for critical cases,
• unique indexes that hold across shards,
• a data-access library (ORM) that works seamlessly with sharding,
• and one-click resharding.

And the post is honest: once enough runway is banked, the team will weigh this in-house RDS path against the maturing NewSQL options.