How Google Spanner Works

A SQL database that spans the planet and still behaves as if every transaction ran one at a time. The trick is TrueTime — a clock that hands back an interval, not an instant, so a committing transaction can wait out its own uncertainty. We walk the splits and Paxos groups, the commit-wait rule that buys external consistency, how reads and writes scale, and when you do not need any of it — drawn, computed, and animated.

System design · Systems. The source ↗

A free, interactive, animated visual explainer of How Google Spanner Works — built to be understood, not skimmed.

Questions

What is Google Spanner?
Spanner is Google’s globally distributed SQL database. The OSDI 2012 paper describes it as "Google’s scalable, multi-version, globally-distributed, and synchronously-replicated database" and "the first system to distribute data at global scale and support externally-consistent distributed transactions." It shards data "across many sets of Paxos state machines in datacenters spread all over the world," is "designed to scale up to millions of machines across hundreds of datacenters and trillions of database rows," and exposes schematized semi-relational tables with a SQL-based query language — so it reads and writes like a relational database while surviving whole-datacenter failures.
What is TrueTime in Spanner?
TrueTime is Spanner’s clock API, and its defining feature is that it does not return a single timestamp — it returns an interval. TT.now() returns "a TTinterval that is guaranteed to contain the absolute time during which TT.now() was invoked," bounded by an uncertainty ε on each side. It is built on two independent hardware references, GPS receivers and atomic clocks, and the implementation "keeps uncertainty small (generally less than 10ms)." In Google’s production environment the instantaneous bound ε "is typically a sawtooth function of time, varying from about 1 to 7 ms," so the average bound is about 4 ms.
What is commit-wait and how does it give external consistency?
Commit-wait is the rule that makes Spanner externally consistent: a committing transaction deliberately waits out its own clock uncertainty before it lets anyone see its writes. The coordinator picks a commit timestamp s of at least TT.now().latest, then "ensures that clients cannot see any data committed by Ti until TT.after(si) is true" — that is, until the current time interval has definitely moved past s. The expected wait is at least 2·ε̄ (about 5 ms measured in the paper). Because every transaction does this, if one commits before another starts, the first is guaranteed the smaller timestamp — the definition of external consistency.
How do reads scale in Spanner without slowing down writes?
Reads run at a timestamp, without locks. A snapshot read "is a read in the past that executes without locking," and a lock-free read-only transaction executes "at a system-chosen timestamp without locking, so that incoming writes are not blocked." Any replica that is "sufficiently up-to-date" — past a value the paper calls safe time — can answer, so reads spread across replicas instead of funnelling through a leader. A strong read sees everything committed before it started; a stale read "at a timestamp in the past" trades freshness for even lower latency by reading a nearby replica.
When should you not use Spanner?
When you do not need what it costs. Spanner’s guarantees rest on specialised time infrastructure — GPS and atomic clocks in every datacenter — and on commit-wait, which adds a few milliseconds of deliberate latency to every write to pay for external consistency. If your data fits comfortably on one primary in one region, or your application can tolerate eventual consistency, a single-region relational database or a simpler replicated store delivers the same result without the clock hardware or the commit-wait tax. Spanner earns its complexity only when you genuinely need strong consistency across the globe.

Related explainers