Lesson 01 · The first warning

The vault groans. The scribes demand partitions.

Six years of orders now live in one table. Reports are slower, checkout occasionally stalls, and last month’s cleanup ran until dawn. The proposed cure is already on the board: SHARD IT.

BottlenecksBaselinesDesign pressure

01 · Interactive diagnosis lab

Name the pressure before choosing the cure.

Select a moment in the vault’s day, run its workload, and read the evidence. The numbers are modeled, but their relationships follow real database behavior.

Evidence0 / 3 found

Evening reports

orders-primary · PostgreSQL

WorkloadCustomer order history

SELECT *
FROM orders
WHERE customer_id = 84217
ORDER BY created_at DESC
LIMIT 50;

CCallerReports UI

AServiceOrders API

DB218 GBOrders Vault

Metrics will appear after the workload completes.

Observed evidenceWaiting

Query p95—response time

Buffer hit—pages found in memory

CPU—primary utilization

Disk reads—physical pages / sec

HighLow

The Old Dragon is watching

Run the workload. Numbers are more loyal than guesses.

02 · What “slow” can mean

A database has four finite resources.

Every scaling technique moves pressure away from something. If you cannot name that resource, you cannot know whether the technique worked.

CPU

Parsing, planning, joins, sorting, compression, and row processing consume compute.

Signalhigh utilization + runnable queue

Memory

The buffer pool keeps useful pages close. When the active set no longer fits, disk work rises sharply.

Signalfalling hit ratio + rising reads

Disk

Random reads, WAL flushes, checkpoints, and maintenance compete for finite IOPS and bandwidth.

SignalI/O wait + queue depth

Network

Large results, replication streams, and cross-machine queries consume throughput and round trips.

Signaltransfer time + saturation

03 · Three different walls

Partitioning and sharding answer different complaints.

The word “split” hides three distinct goals. Only one necessarily needs more machines.

PressureWhat hurtsFirst questionsLikely direction

Query pressureToo many pages touchedIs the access path wrong?Query + index

Lifecycle pressureOld data is costly to manageDo natural boundaries exist?Partition

Capacity pressureWrites or data exceed one hostCan ownership be divided?Shard

The Old Dragon “You came to me with a cure and you leave with a question. That is progress, keeper. Now come below, and see where your answers actually live.”

The Dragon’s Reckoning

Where we stand

We have not changed the architecture. That is progress: we now know what must be understood before adding one.

What we learned“Slow” is not a diagnosis

CPU, memory, disk, network, and maintenance pressure leave different evidence.

What we solvedNothing—yet

We resisted an unjustified split and established the questions that must come first.

What remainsWhy pages become expensive

The buffer pool and working set will explain the first sharp performance cliff.

Our system nowOne API · one database

The original architecture remains intact while we descend beneath its tables.

Next · Lesson 02

Beneath the Vault

Follow one query through disk pages, memory, and eviction.

The map Enter the next vault →