Chapter One · The Postgres Model

The Postgres Model

Postgres never overwrites a live row, keeps its type system and index methods as catalogue entries you can add to, and answers to no company. Five topics set the vocabulary (row versions, processes, clusters and schemas, the catalogue) and then hand you Cartwheel, the grocery-delivery system every later example is built on, with two unexplained failures already inside it.

5 topics

SQL is the part of Postgres you can see. What this book adds is the engine underneath it: why a query that started thirty seconds ago still returns a row that was deleted twenty seconds ago, why 400 application connections cost more than 400 threads would, why a table the migration definitely created is invisible to \dt, and why almost every "why does Postgres do that" question has the same root.

That root is one design decision. An UPDATE does not edit a row; it writes a new version of it and leaves the old one readable by anyone who started earlier. Snapshots, isolation levels, dead tuples, vacuum, bloat, index maintenance and physical replication all fall out of that, and each gets a chapter of its own later. This one plants the idea and hands you three tools to see it with: the process model, the three levels of namespace, and the catalogue that psql is a thin shell over.

The chapter ends on Cartwheel: a grocery-delivery service on one box called pg-primary, eight tables, 40 million orders, and a Saturday-morning peak of 3,000 orders a minute. Nadia owns that database for the rest of the book. Two things about it do not make sense yet, and both stay unexplained deliberately until the machinery exists to explain them properly rather than plausibly.

One design decision, and what falls out of it
UPDATEdoes not edit the row
A new versionwritten, not overwritten
The old one staysreadable by anyone who started earlier
Everything downstreamsnapshots · isolation · dead tuples · vacuum · bloat · replication

Topics in This Chapter

Topic 01
What PostgreSQL Actually Is
A row is a version, not a slot: an UPDATE writes a new copy and expires the old one, which is where vacuum, isolation and bloat all begin. Plus the two facts that shape the rest — a catalogue-driven design anyone can extend, and a project no company owns.
Fundamentals
Topic 02
The Process Model
One operating-system process per connection, a crew of background processes around them, and a single shared memory region where they all meet. Almost every operational limit in this book — pooling, work_mem, idle in transaction — traces straight back to that picture.
Architecture
Topic 03
Clusters, Databases, and Schemas
Three levels of namespace, and the middle one is a wall: a session reaches exactly one database and cannot join across to another. Templates, search_path, what changed about the public schema in 15, and how name resolution turns into a security problem.
Namespaces
Topic 04
psql and the System Catalog
Every backslash command is shorthand for a catalogue query, which means anything psql can show you, you can compute, filter and schedule. The commands worth memorizing, \copy against COPY, reltuples as an estimate, and a .psqlrc that prevents a class of misread results.
Tooling
Topic 05
Meet Cartwheel
Eight tables, 40 million orders, 3,000 orders a minute on a Saturday, and 400 connections aimed at a server that accepts 200. Two failures open here and stay open: a monthly slowdown nobody can explain, and the morning two customers were both sold the last box of strawberries.
Running Example