Figma: Horizontal Postgres Sharding Without Stopping Growth

Figma grew too fast for its own data infrastructure. For years, the database architecture followed the classic successful-startup pattern: a primary Postgres with read replicas, scaling vertically whenever warning signs appeared. That approach worked — until the moment it stopped working.

The problem was not a single catastrophic event. It was a convergence of pressures: the primary instance accumulating chronically high CPU, WAL (Write-Ahead Log) showing increasing lag on replicas, and the connection pool operating near PgBouncer's physical limits. In high-frequency transactional systems like Figma — where multiple users edit the same document in real time — any degradation in the primary database propagates directly to the user experience.

Vertical scaling had reached its practical ceiling. Moving to a larger instance would solve the problem for months, not years. The team needed a structural solution, and the only way out was horizontal sharding — distributing data across multiple independent Postgres nodes, each responsible for a subset of the system's entities.

What makes this problem especially hard is that Figma did not have the luxury of pausing the product to perform the migration. Business growth continued, new users arrived, new files were created. The migration had to happen underneath a fully operational system, without users noticing.

Figma's solution can be decomposed into three interdependent layers: logical partitioning, dynamic routing, and incremental migration with dual-write.

Logical partitioning by entity key

The chosen sharding scheme was key-based — specifically, on the root entity identifier (typically file_id or tenant equivalent). This means all data related to a given file or user is colocated on the same physical shard. Colocation is critical: cross-shard queries are extremely costly and, if poorly planned, eliminate any scaling gains. Figma opted for aggressive colocation to avoid this antipattern.

The number of logical shards was defined as an intentional multiple of the physical shards. This is a sophisticated engineering decision: by separating logical shards from physical shards, the system can rebalance data by moving logical shards between physical nodes without needing to rehash all keys. It is the same principle as consistent hashing, but implemented more explicitly with an application-controlled shard map.

Dynamic routing at the application layer

Instead of adopting an external database proxy (such as Vitess or Citus), Figma implemented routing inside the Rails application itself. A central component — the shard map — maintains the mapping of logical shard_id → physical Postgres instance. Before any query, the application consults this map to determine which database connection to route the operation to.

This choice has deep implications. On one hand, it eliminates a network hop and an additional infrastructure layer to operate. On the other hand, it couples routing logic to application code, meaning every change to the shard map needs to be coordinated with application deploys — or managed via feature flags and dynamic configuration.

Incremental migration with dual-write and verification

The most delicate part of the entire operation was migrating existing data without downtime. The process followed a classic online migration pattern: first, enable dual-write for the entities being migrated, where each write goes to both the source and destination shard; second, run the historical data backfill in the background with rate control to avoid overloading the primary; third, verify consistency between source and destination before cutting read traffic; fourth, promote the destination shard as authoritative and remove the duplicate write.

Each phase of this migration was executed incrementally, table by table, entity by entity. It was not a big-bang migration — it was a series of surgical migrations, each with a defined rollback path.

Any sharding diagram looks reasonable on paper. The brutality is in the operational details the diagram doesn't capture.

The distributed transactions problem

Postgres has no native support for distributed transactions across independent instances. This means any operation that needs atomicity across two different shards must be redesigned. Figma solved this in two ways: first, through aggressive colocation of related entities on the same shard (avoiding the problem at the source); second, by accepting eventual consistency in cases where cross-shard atomicity was infeasible and redesigning the data model to eliminate cross-shard dependencies wherever possible.

This is a design decision with direct product impact. Some query patterns that were trivial in the monolith — a JOIN between tables of different entities — become prohibited or very costly in the sharded world. The engineering team had to audit all existing queries and classify them by access pattern before defining the partitioning strategy.

The human cost of dual-write

The dual-write phase is conceptually simple but operationally expensive. During the migration period, each relevant write needs to go to two destinations. This increases write latency, doubles pressure on the connection pool, and introduces a new failure vector: what happens if the write to the destination shard fails? Figma had to define explicit failure-handling policies for each phase of the migration — and those policies had to be conservative enough not to corrupt data, but aggressive enough not to stall the product.

Managing the shard map as critical infrastructure

The shard map is not a static configuration file. It is an infrastructure component that needs to be read at high frequency (every query passes through it), have very low latency, and be updated atomically during rebalancing. Figma had to treat the shard map as a first-class service — with application-level caching, controlled invalidation, and dedicated monitoring. A shard map failure is a global failure: if the application cannot resolve which shard to route a query to, it cannot serve any request.

Schema migrations in a sharded world

In a monolith, a schema migration is a single, controlled event. With N physical shards, each migration needs to be executed N times, in a coordinated fashion, without causing inconsistency between shards during the transition period. Figma adopted the practice of backward-compatible schema changes — adding columns as nullable before making them required, keeping old columns during transition periods — to ensure that different shards could be in slightly different schema states during rollout.