Skip to content

PATTERN Cited by 1 source

Colocation sharding ("colos")

Group related tables that share a shard key into a colocation ("colo"), and make the colo the unit of physical sharding. Tables within the same colo can still support cross-table joins + full transactions when restricted to a single shard-key value — the two operations application code relies on most — without the router needing to resolve anything more complex than "route to this one shard".

Shape

  • Pick a small set of shard keys that collectively partition almost every table (Figma: UserID, FileID, OrgID — Source: sources/2026-04-21-figma-how-figmas-databases-team-lived-to-tell-the-scale).
  • Each shard key defines a colo. Tables sharded by the same key live in the same colo.
  • All tables in a colo share one physical sharding layout — same hash function, same shard boundaries, same physical shards.
  • For a given shard-key value (e.g. one user_id), all rows across all tables in the colo land on the same physical shard — so a join across tables in the colo scoped to that value is a single-shard operation, and a transaction across them is a normal Postgres transaction.

What this buys you

  1. Minimal application refactor. Most product queries are already scoped to a single user / file / org — so they already look single-colo / single-shard-key without any change. Cross-table joins + transactions continue to work unchanged.
  2. Narrow router scope. The router only needs to route on shard-key predicate; it doesn't need to coordinate distributed transactions or plan cross-shard joins for the common case.
  3. Data-model-aligned partitioning. The shard-key set is discovered from the data model, not imposed on it. No synthetic composite keys, no schema changes, no backfills.

Trade-offs

  • No cross-colo joins. If UserID colo and FileID colo both have tables the query wants to join, that join is not a single-shard op. Typically handled by (a) denormalizing across colos, (b) application-layer join, or (c) rewriting the query to be scoped to one colo.
  • Joins outside the shard key. Even within a colo, joins not on the shard key are not single-shard (different rows on the same table may live on different shards). Figma's DBProxy only allows joins on the shard key within the same colo.
  • Colos must share physical layout. Adding a new table to a colo inherits its physical sharding; a table that wants different sharding needs a different colo.
  • Some tables may sit awkwardly between colos. Typically resolved by (a) choosing the best-fit colo + accepting minor sub-optimality, (b) duplicating denormalized reads into multiple colos, or (c) keeping the table unsharded.

Contrast with a single-universal-shard-key approach

A single shard key across all tables (the one-ring alternative) is attractive in theory — every query routes cleanly, every join is single-shard. In practice, many relational data models have no single natural key; enforcing one requires a composite key + adding a column to every table + expensive backfill + substantial refactor of product logic touching that composite key. Colos trade some edge-case capability (cross-colo joins / transactions) for avoiding all of that migration cost — the pragmatic choice when an application's data model has multiple natural partition axes (Source: sources/2026-04-21-figma-how-figmas-databases-team-lived-to-tell-the-scale).

Seen in

Last updated · 200 distilled / 1,178 read