The Scaling Ladder: How Nextdoor Evolved PostgreSQL Through Pooling, Replication, and Sharding
How Nextdoor scaled PostgreSQL from a single server to a multi-tiered architecture: PgBouncer connection pooling, read replicas, and horizontal sharding.
On this page
When building an internet application, every engineering team dreams of massive user growth.
Yet, when rapid growth actually arrives, it lands with brutal force upon the foundational database.
At Nextdoor, the neighborhood social network connecting tens of millions of neighbors across worldwide communities, that foundational database was PostgreSQL.
Nextdoor did not begin with a hyper-complex distributed database. They began, like almost every successful technology company, with a single primary PostgreSQL server.
As neighborhood signups exploded, that single server reached physical hardware saturation.
Nextdoor did not panic and attempt an immediate, high-risk migration to a NoSQL database. Instead, they climbed the Database Scaling Ladder: a methodical, step-by-step sequence of architectural evolutions where each rung solved an immediate bottleneck while introducing new consistency challenges that required the next architectural rung.
+-------------------------------------------------------------------------------+
| NEXTDOOR'S DATABASE SCALING LADDER |
+-------------------------------------------------------------------------------+
[Rung 4: Horizontal Database Sharding (Citús / Partitioning)]
- Shards relational tables horizontally by neighborhood_id.
- Multiplies write capacity by 16x; trades cross-shard join capability.
^
| (When single primary reaches write saturation)
[Rung 3: Read-Replication & Primary-Replica Split]
- Routes 85% of queries (SELECTs) to read-only replicas.
- Introduces replication lag & requires Read-Your-Own-Writes routing.
^
| (When read traffic saturates CPU & memory caches)
[Rung 2: PgBouncer Connection Pooling (Transaction Mode)]
- Multiplexes 10,000 application threads across 200 physical DB connections.
- Eliminates OS process context-switching stalls.
^
| (When connection counts exhaust RAM & Linux process limits)
[Rung 1: The Monolithic Single PostgreSQL Server]
- Maximum developer velocity; simple ACID joins; vertical hardware upgrades.
1. Rung 1 to Rung 2: The Connection Exhaustion Crisis (PgBouncer)
Nextdoor’s application tier was built on Django, running hundreds of containerized Python application workers.
The Failure Mode
PostgreSQL handles connections using a process-per-connection model. For every client that connects, the Linux kernel forks a dedicated postgres operating system process consuming roughly 10MB of RAM.
When Nextdoor scaled to 5,000 concurrent application workers, PostgreSQL attempted to maintain 5,000 active processes:
- Over 50GB of RAM was wasted solely on connection overhead.
- The Linux kernel scheduler spent massive CPU cycles context-switching between thousands of competing processes.
- Memory bus contention stalled transaction commit throughput.
The Fix: PgBouncer Transaction Pooling
Nextdoor inserted a PgBouncer proxy fleet between Django and PostgreSQL:
[5,000 Django Web Workers]
|
v (Lightweight, persistent TCP connections to PgBouncer)
[PgBouncer Proxy Fleet]
|
v (Fixed pool of ONLY 150 physical PostgreSQL connections!)
[Single Primary PostgreSQL Server]
By operating PgBouncer in Transaction Pooling Mode, a physical connection is only assigned to a worker for the few milliseconds it takes to execute a SQL transaction.
The moment COMMIT executes, the physical connection returns to the pool. A compact pool of 150 physical connections multiplexed thousands of web workers with zero connection exhaustion.
2. Rung 2 to Rung 3: The Read Saturation Wall (Primary-Replica Split)
Connection pooling stabilized the database, but total query volume continued to climb. CPU utilization on the single primary server hovered at 95% due to read-heavy neighborhood feed requests.
Because over 85% of Nextdoor’s workload was reads, the next logical rung was Physical Read Replication:
+-------------------------------------------------------------------------------+
| PRIMARY-REPLICA QUERY ROUTING |
+-------------------------------------------------------------------------------+
[Django Application ORM Router]
|
+---> [Mutations: INSERT / UPDATE / DELETE] ---> [Primary Writer]
| |
| v (Physical Streaming WAL)
+---> [Queries: SELECT Lookups] ---------------> [Read Replica Pool (1..N)]
The Consistency Dilemma: Replication Lag
Physical replication is asynchronous. Under heavy write bursts, read replicas lag behind the primary by 50 to 500 milliseconds.
This introduced the classic “disappearing post” anomaly:
- A neighbor posts a photo of a lost dog (writes to Primary).
- The page reloads; Django queries a lagging Read Replica.
- The photo is missing! The user assumes the post failed and submits it again.
Nextdoor’s Fix: Session-Based Lag Pinning
Nextdoor implemented custom ORM routing logic: whenever a user executes a write mutation, their user session is pinned to the primary database for 3 seconds.
Subsequent reads from that specific user bypass replicas, guaranteeing read-your-own-writes consistency while 90% of global reads remain offloaded onto replicas.
3. Rung 3 to Rung 4: The Write Bottleneck and Sharding
Eventually, vertical scaling hit a physical hardware ceiling: even on the largest cloud instances available, the single primary writer could not absorb the write-ahead log (WAL) disk write throughput generated by millions of concurrent neighbor actions.
Nextdoor climbed to the final rung: Horizontal Sharding.
+-------------------------------------------------------------------------------+
| HORIZONTAL NEIGHBORHOOD SHARDING |
+-------------------------------------------------------------------------------+
[Application Router: Hashes `neighborhood_id`]
|
+---> Shard 01 (Neighborhoods 1 - 2,500) ---> [PostgreSQL Cluster 1]
+---> Shard 02 (Neighborhoods 2,501 - 5,000) ---> [PostgreSQL Cluster 2]
+---> Shard 03 (Neighborhoods 5,001 - 7,500) ---> [PostgreSQL Cluster 3]
+---> Shard 04 (Neighborhoods 7,501 - 10,000)---> [PostgreSQL Cluster 4]
Selecting the Natural Shard Key
Sharding succeeds or fails based on the choice of Shard Key.
Nextdoor had an enormous architectural advantage: social interaction on the platform is inherently geographically bounded. A neighbor in Seattle rarely interacts with a neighborhood post in Miami.
By selecting neighborhood_id as the universal shard key:
- 99% of queries, joins, and transactions occur strictly within a single neighborhood shard.
- Relational ACID foreign keys and multi-table joins remain fully intact within each independent shard cluster.
- Write throughput scales linearly as new shards are provisioned.
Summary and Key Takeaways
- Climb the ladder sequentially: Never jump directly to sharding; exhaust vertical scaling, connection pooling, and read replication first.
- PgBouncer eliminates connection bloat: Multiplex thousands of application pods across a fixed pool of 100-200 physical database connections.
- Guard against replication lag: When implementing read replicas, pin mutating user sessions to the primary for a few seconds to guarantee read-your-own-writes consistency.
- Choose natural shard keys: Successful sharding requires selecting a partitioning key (like
neighborhood_id) that isolates 99% of transactions to single shards. - Every rung introduces new trade-offs: Each scaling step solves a throughput limit while introducing distributed state and consistency trade-offs that dictate the next architectural evolution.

/* Comments */
Comments are offline right now — we reconnect automatically, nothing is lost.