Start with the big picture: what Spanner is, and why people call it special.

Cloud Spanner is a fully managed, relational database service from Google Cloud. A relational database stores information in tables made of rows and columns, and lets you connect tables together, for example linking customers to their orders. It supports SQL, the standard language for asking questions of such databases, and it supports transactions, which are groups of changes that either all succeed or all fail.

What makes Spanner unusual is that it is also horizontally scalable and globally distributed. Horizontal scaling means you handle more load by adding more machines, rather than buying one bigger machine. Global distribution means copies of your data can live in different regions of the world. Most databases give you one or the other: either strong relational guarantees on a single machine, or easy scaling with weaker guarantees. Spanner aims to give you both together.

Where it came from

Spanner began inside Google. Google needed a database for its advertising business that could grow enormously, survive the loss of entire data centres, and still keep money-related data perfectly correct. Existing systems could not do all three. Google’s engineers built Spanner to meet that need, described it in a well-known research paper in 2012, and later offered it to the public as Cloud Spanner. The fact that it was born to run some of Google’s most important systems is a big reason why many companies trust it.

What you give and what you get

You create an instance, choose where it lives and how much computing power it gets, create a database inside it, and define your tables. In return, Google takes care of replicating every piece of data to several places, splitting large tables across machines, moving load around, patching software, taking backups on request and replacing failed hardware. You never log in to a database server, because there is no server for you to manage.

To understand any tool, first feel the pain it was built to remove.

Imagine you start a small online shop with a standard relational database on one machine. It works beautifully. Then the shop becomes popular. Orders flood in, the machine slows down, and you buy a bigger machine. This approach is called vertical scaling, and it works until you reach the biggest machine money can buy. After that, there is nowhere to go.

The usual next step is sharding, which means splitting your data into pieces and putting each piece on a different database machine. For example, customers whose names start with A to M go on one machine, and N to Z on another. Sharding works, but it brings serious pain. Your application must know which shard holds which data. A change that touches two shards cannot easily be made safely. Reports that span all shards need special tools. Adding a new shard means moving data around while the shop is running. Many companies have spent years of engineering effort building and maintaining their own sharding systems.

The classic trade-off

Some modern databases, often called NoSQL databases, solved the scaling problem by giving up some features. They spread data across many machines easily, but they usually drop joins, flexible SQL queries or strong guarantees about transactions. Teams then had to write that missing logic inside their applications, which is hard and error-prone. For data like game scores or page views, that is often acceptable. For money, inventory and bookings, it is dangerous.

Spanner removes the false choice. It lets you keep SQL, joins and strong transactions while scaling out across machines automatically, and it keeps replicas in several places that always agree. You pay for this with a different cost model and a design style that you must learn, which later chapters explain.

A handful of words explain almost everything in Spanner. Learn them well and the rest becomes easy.

Instance

An instance is the basic unit you create and pay for. It defines where your data lives, called the instance configuration, and how much computing power you have, called the compute capacity. A single instance can hold many databases. Think of an instance as a rented office floor, with databases as the separate companies working on it.

Database, table, row and column

A database lives inside an instance and holds your tables. A table is a grid of information. Each row is one record, such as one customer, and each column is one fact about it, such as an email address. Every table must have a primary key, which is a column, or a group of columns, that uniquely identifies each row. In Spanner, the primary key matters far more than in a single-machine database, because it also decides where the row is stored.

Node and processing unit

Compute capacity is measured in nodes or in smaller pieces called processing units. A node is a bundle of computing and serving capacity. One node equals one thousand processing units, so you can start small with a few hundred processing units and grow to many nodes. More capacity means more reads, writes and storage that the instance can handle.

Replica and leader

Spanner keeps several copies of your data, called replicas, in different zones or regions. For each piece of data, one replica acts as the leader. The leader coordinates writes and makes sure all copies agree. If the leader’s location fails, another replica takes over automatically.

Split

Spanner automatically cuts each table into pieces called splits, based on ranges of the primary key. Different splits can live on different machines. When one split gets too big or too busy, Spanner divides it into two and may move one part to another machine. This is how it scales without you sharding by hand.

Transactions and ACID

A transaction groups several steps into one all-or-nothing action. Transferring money involves subtracting from one account and adding to another. If the machine dies between the two steps, you must not lose the money. Databases promise ACID behaviour to guard against this. The letters stand for atomic, meaning all-or-nothing; consistent, meaning rules stay true; isolated, meaning simultaneous transactions do not trample each other; and durable, meaning once confirmed, the result is never lost. Spanner offers full ACID transactions even across machines and regions.

The first big decision is where your data lives and how many copies you keep. This choice sets your availability, speed and price.

When you create an instance, you pick an instance configuration. This is a template that says where your replicas will be placed. The three main families are regional, dual-region and multi-region. Names and options evolve, so confirm the current list in the official documentation before you decide.

Types of replica

Not every copy does the same job. Spanner uses three kinds of replicas, and understanding them explains how the configurations differ.

The leader region

In configurations with more than one region, writes are coordinated by the leader, which lives in a chosen leader region. Writes from far away must travel to the leader and back, so placing the leader near most of your writers reduces delay. You can set a preferred leader region for a database, so the leaders sit where your writing traffic is heaviest.

Editions

Spanner is also sold in editions, such as Standard, Enterprise and Enterprise Plus. Each edition includes a different set of features, with the higher editions adding capabilities such as more advanced data-handling options, extra availability choices and stronger operational features. The exact feature split changes over time, so compare editions on the official pricing and feature pages before you choose. A sensible approach is to start with the lowest edition that has everything your application needs.

Let us look at the main pieces that sit between your application and the stored rows.

When your program sends a query, a chain of components handles it. Knowing this chain helps you understand why some designs are fast and others are slow. The diagram below shows the parts in a typical regional instance.

flowchart LR
  APP["Your Application"] --> CL["Spanner Client Library"]
  CL --> FE["Spanner API Front End"]
  FE --> SRV["Spanner Servers: Compute Nodes"]
  SRV --> SP1["Split A: rows 1 to 1000"]
  SRV --> SP2["Split B: rows 1001 to 2000"]
  SRV --> SP3["Split C: rows 2001 to 3000"]
  SP1 --> Z1[("Replica in Zone 1")]
  SP1 --> Z2[("Replica in Zone 2")]
  SP1 --> Z3[("Replica in Zone 3")]
  Z1 --> FS[("Distributed File System")]
  Z2 --> FS
  Z3 --> FS
    

Walking through the diagram

Your application talks to Spanner through a client library, a ready-made piece of code for languages such as Java, Python, Go and others. The library manages connections for you, using a pool of sessions, which are reusable conversations with the database. Requests go to the Spanner front end, which checks who you are and routes the request.

The request then reaches the Spanner servers, which are the compute nodes you pay for. These servers are responsible for the splits. Each split is a range of rows, and each split is copied to several replicas in different zones. The replicas keep their data on Google’s distributed file system, which itself stores data redundantly. This separation between compute and storage is an important idea. It means Spanner can add or remove compute nodes quickly without copying huge amounts of data, because the data stays in the shared storage layer.

Key components in plain words

One last idea is worth noting. Because your data is split by key ranges and each range is a unit of movement, the way you choose primary keys shapes how evenly the work spreads across nodes. This single design choice is the biggest influence on whether Spanner feels fast or slow, and a whole later chapter is devoted to it.

Follow one money transfer from your application to safe, agreed storage.

Let us trace what happens when your application saves a change, such as adding a new order. This walk-through shows where the time is spent and why Spanner can promise that data is never lost.

sequenceDiagram
  participant A as Application
  participant L as Split Leader
  participant R1 as Replica 2
  participant R2 as Replica 3
  A->>L: Begin transaction and write order row
  L->>L: Take locks and pick a commit timestamp
  L->>R1: Send change to replicate
  L->>R2: Send change to replicate
  R1-->>L: Acknowledge
  R2-->>L: Acknowledge
  L->>L: Wait out clock uncertainty
  L-->>A: Commit confirmed
    

Step by step

Majority agreement and Paxos

Spanner uses a well-known method called Paxos to make replicas agree. You do not need to know its details. The key idea is that a change is committed once a majority of the replicas for that split have stored it. With three replicas, two must agree. If one replica fails or is unreachable, the other two still form a majority, and the system keeps working without losing any confirmed data.

When a write touches more than one split

Sometimes one transaction changes rows that live in different splits, perhaps on different machines or even in different regions. Spanner then uses two-phase commit. In the first phase, the leader of each split promises that it is ready to commit. In the second phase, a coordinator tells everyone to commit together. Because each leader’s promise is itself replicated, the process survives failures. Such transactions cost more time than single-split ones, which is why good designs keep related rows together, as explained in the data model chapter.

The secret ingredient that lets Spanner order events correctly across the whole planet.

Imagine two people on opposite sides of the world, each saving a change to the same database at nearly the same moment. Which change happened first? To answer, the database needs a clock that everyone can trust. But ordinary computer clocks drift, and two machines never agree perfectly on the time. This is one of the hardest problems in distributed systems.

Google’s solution is TrueTime. Google fits its data centres with very accurate clocks: atomic clocks and GPS receivers. Instead of pretending that time is exact, TrueTime tells software the truth: “the time is now somewhere between this moment and that moment.” It returns a small interval of uncertainty, typically a few milliseconds wide, rather than a single point.

Commit wait

When Spanner commits a write, it picks a commit timestamp and then waits until that timestamp is definitely in the past according to the uncertainty interval. This pause is called commit wait. It usually lasts only a few milliseconds. In return, Spanner gets a powerful promise: if transaction A finishes before transaction B starts, then A’s timestamp is always smaller than B’s, anywhere in the world.

External consistency

This promise has a name: external consistency, sometimes described as the strongest form of consistency, close to what developers call linearizability for transactions. In plain words, the database behaves as if every transaction happened one at a time, in an order that matches real-world time. If you see a change confirmed to a user, any later read anywhere will see it. Applications do not need to reason about stale copies or surprising orderings.

Why this matters to you

Without such ordering, applications need workarounds. A shopper might buy the last item in one country while another shopper sees it in stock in another. A bank might show an old balance after a deposit. With external consistency, these surprises do not occur. You can write application logic in the simple way you would on a single database, and Spanner worries about the planet.

Strong reads and stale reads

By default, reads in Spanner are strong, meaning they see all committed changes up to the moment of the read. Strong reads may need to check with the leader, which can add delay when you are far away. If your application can accept slightly old data, for example a product listing that is a few seconds behind, you can ask for a stale read. A stale read says “give me the data as it was ten seconds ago” and can be served by the nearest replica without contacting the leader. This trade of freshness for speed is a favourite tuning tool, and a later chapter returns to it.

This is the most important design chapter. Good keys make Spanner fly, and bad keys make it crawl.

In an ordinary database on one machine, the primary key is mostly about identity. In Spanner, the primary key also controls physical placement. Rows are stored in sorted order of their primary key, and Spanner divides that sorted order into splits. Rows with similar keys sit together, and rows with distant keys can live on different machines.

The hotspot problem

A hotspot is a part of the database that receives far more traffic than the rest. It is the number one performance mistake in Spanner. It usually happens when keys always increase, such as an auto-counting number or a current timestamp placed first in the key. Every new row lands at the very end of the sorted order, so one split and one server receive all the writes. Adding more nodes does not help, because only one node owns the end of the table.

flowchart TD
  K{"Does the first part of the key always increase over time?"}
  K -- "Yes" --> BAD["Hotspot risk: all new rows hit one split"]
  K -- "No" --> GOOD["Writes spread across many splits"]
  BAD --> F1["Use a random UUID as the key"]
  BAD --> F2["Use a bit-reversed sequence"]
  BAD --> F3["Add a hash or shard prefix"]
  BAD --> F4["Put a well-spread column such as user ID first"]
  F1 --> GOOD
  F2 --> GOOD
  F3 --> GOOD
  F4 --> GOOD
    

Ways to choose a good key

Interleaved tables: keeping family together

Many data sets have parent and child relationships, such as a customer and their orders, or an order and its line items. In Spanner, you can declare a child table as interleaved in its parent. This tells Spanner to store each child row physically next to its parent row, in the same split. When you read a customer and all their orders, the data comes from one place, and when you change both in one transaction, it commits quickly without needing a multi-machine agreement.

Interleaving can also delete children automatically when a parent is deleted, if you choose the cascade option. The child table’s primary key begins with the parent’s key, followed by its own column. Use interleaving when you usually read parent and children together, and when the number of children per parent is reasonable. Avoid it when children are accessed independently of their parents, or when one parent could have an enormous number of children.

Foreign keys

Spanner also supports ordinary foreign keys, which are rules that link one table to another and keep references valid. Unlike interleaving, foreign keys do not place rows together. Use them when relationships are not strictly parent-and-child, or when you want the rule enforced without co-locating data. Interleaving is a performance tool, and foreign keys are a correctness tool, and you can use both.

Secondary indexes

A secondary index lets you find rows quickly by a column other than the primary key, such as searching customers by email. In Spanner, an index is stored like its own small table, sorted by the indexed columns. You can add extra columns to an index with a storing clause, so that a query can be answered entirely from the index without visiting the main table. Every index adds work to each write and uses extra storage, so create only the indexes your queries truly need.

Changing the schema

Spanner lets you change the schema while the database is running. Adding a column, creating an index or changing certain settings are done as online schema changes, which run in the background without blocking reads and writes. Large changes, such as building an index over a billion rows, can take a while, and you can monitor their progress. Plan changes carefully, release in small steps, and make changes backward compatible so old and new versions of your application can both work during a release.

How Spanner keeps simultaneous users from stepping on each other, and how to choose the right kind of read.

Spanner offers different transaction styles for different needs. Choosing the right one is both a correctness and a cost decision, because stronger styles use more resources.

Read-write transactions

A read-write transaction is used whenever you change data. It uses locks, which are temporary reservations on rows. While you hold a lock on a row, others who want to change it must wait. By default, Spanner provides the strictest level of isolation, called serializable, which means the result is as if all transactions ran one after another. Some versions also offer a gentler isolation option for workloads that prefer fewer conflicts, so check the current documentation for what is available.

Deadlocks and aborts

A deadlock happens when two transactions each hold something the other needs, and both wait forever. Spanner prevents this by choosing one transaction to abort, which means cancelling it. The aborted transaction must be tried again. This is normal and expected, not an error in your system. The official client libraries include helper functions that automatically retry aborted transactions, so write your transaction code inside those helpers and make sure it is safe to run more than once.

Read-only transactions and snapshot reads

A read-only transaction sees one consistent picture of the database at a single moment, even if you run many queries. It takes no locks and does not block writers, so it is cheaper and faster than a read-write transaction. Whenever your code only reads, use read-only mode. This is especially useful for reports that must show matching totals across several queries.

Stale reads

Stale reads can be served by any replica that is up to date enough, including read-only replicas near the user. This can cut read latency dramatically for global applications. Use them for content such as catalogues, profiles and dashboards, and keep strong reads for things like account balances and stock checks at purchase time.

Writing efficiently

Spanner gives you two ways to change data. Mutations are direct instructions such as “insert this row” or “update that row”, sent together in one commit. DML, short for data manipulation language, uses SQL statements such as insert, update and delete. Both are transactional. Mutations are often more efficient for plain inserts and updates, while DML shines when the change depends on a query. For huge changes, such as deleting millions of old rows, partitioned DML splits the work into many independent pieces that run in parallel, trading atomic all-or-nothing behaviour for speed and scale.

Scaling is Spanner’s headline feature. Here is what happens when you add capacity and when load grows.

To give your database more power, you increase the compute capacity of the instance, adding nodes or processing units. This can be done while the database is serving traffic, with no downtime. Spanner then spreads splits across the larger set of servers, so each server handles a smaller share. Storage capacity grows with the number of nodes as well, since each node supports a certain amount of data, so check current limits when planning large databases.

flowchart TD
  A["Split S receives heavy traffic or grows large"] --> B["Spanner detects load or size above threshold"]
  B --> C["Split S is divided into S1 and S2 at a key boundary"]
  C --> D["S2 is moved to a less busy server"]
  D --> E["Load is shared across more servers"]
  E --> F{"Is load still too high overall?"}
  F -- "Yes" --> G["Add nodes or processing units"]
  G --> B
  F -- "No" --> H["System stays balanced"]
    

How splitting works

Spanner watches each split for size and for traffic. When a split grows too big, or becomes too busy, Spanner cuts it in two at a key boundary and may move one half elsewhere. This is called load-based splitting. It happens automatically, and you do not have to plan it. However, splitting works only if the work is spread over many key ranges. If all traffic hits one key, no split can help, since a single row cannot be cut in half. That is why single-row hotspots, such as one global counter updated by everyone, are an anti-pattern.

Choosing capacity

The main measure to watch is CPU utilisation of your Spanner servers. Google’s guidance has recommended keeping high-priority CPU below roughly sixty-five percent for regional instances and around forty-five percent for multi-region instances, leaving headroom for traffic spikes and for failover. These numbers may change, so confirm them in the documentation. If utilisation stays above the guidance, add capacity. If it stays far below, you may be overpaying and can reduce capacity.

Autoscaling

Spanner offers an autoscaler option, which adjusts compute capacity automatically between a minimum and a maximum you choose, based on measured load. This saves money during quiet hours and protects performance during busy ones. You can set targets for CPU use and for storage use. Autoscaling helps most when traffic follows daily or weekly cycles. For sudden, extreme spikes, combine it with scheduled scaling before known events, because reactive scaling needs a little time to respond.

You use familiar SQL, but a few Spanner habits make queries faster and cheaper.

Spanner understands standard SQL features such as selecting, joining, filtering, grouping and sorting. It has a query optimizer, a built-in planner that decides how to run each query, for example which index to use and in what order to join tables. You can ask Spanner to show the query plan, which is the optimizer’s step-by-step approach, and read it to find expensive steps. In rare cases, you can guide the optimizer with hints, but it is wise to try better indexes and cleaner queries first.

Two dialects

Spanner supports GoogleSQL, the dialect shared with other Google data products such as BigQuery, and a PostgreSQL dialect for teams that prefer PostgreSQL syntax. You choose the dialect when creating the database. Both run on the same engine with the same guarantees. Not every PostgreSQL feature is available, so test your queries early.

Habits for fast queries

• Use query parameters. Send values separately from the SQL text. This helps Spanner reuse plans and also protects against injection attacks.
• Filter on key columns. Conditions on the primary key, or on an index, let Spanner read only a small range instead of scanning the whole table.
• Select only needed columns. Fetching fewer columns moves less data and may allow an index-only answer.
• Prefer direct reads for simple lookups. The read API fetches rows by key without the work of parsing and planning a query.
• Keep statistics fresh. Spanner collects statistics about your data to help the optimizer. Large changes may call for a refresh.
• Avoid full table scans on large tables. Scans are fine for small tables and analytics, but they are costly for busy transactional workloads.

Analytics without hurting the main workload

Large analytical queries, such as summing a year of sales, can consume a lot of compute and slow down your real-time traffic. Data Boost is an option that runs such queries on separate, on-demand compute, so they do not take capacity from your main nodes. It is billed separately for the resources used. Another approach is to connect BigQuery to Spanner so analysts can query live data through federated queries, or to stream changes into a warehouse for heavy analysis.

Change streams

A change stream records every insert, update and delete in chosen tables, so other systems can follow along. You can send these changes to a messaging system, a search index or a data warehouse. This lets you keep other systems in sync without writing triggers or polling, and it supports patterns such as event-driven architectures and audit trails.

Other modern features

Replication keeps you safe from hardware failure. Backups keep you safe from human error.

Spanner’s replicas protect against failures of machines, zones and regions. But replicas faithfully copy mistakes too. If someone drops a table, or an application bug writes wrong values, every replica agrees on the damage. To recover from such mistakes, you need backups and the ability to look back in time.

Three ways to protect and recover

The recovery goals

Two numbers define every recovery plan. The recovery point objective, or RPO, is how much recent data you can afford to lose. The recovery time objective, or RTO, is how long you can afford to be down. Point-in-time recovery gives a very small RPO for mistakes, because you can choose a moment just before the problem. Restores create a new database, and large restores take time, so measure how long yours takes and compare it with your RTO.

How a restore works

Protecting against accidental deletion

Spanner offers a deletion protection setting for databases, which blocks accidental deletion until the setting is turned off. Combine it with strict permissions, so only a few people can delete databases or backups, and with audit logging, so any such action is recorded.

What Spanner does when parts of the world go dark.

Spanner is designed so that failures are routine events, not emergencies. Google publishes availability targets, called a service level agreement, that are among the highest in the industry, commonly described as four nines for regional instances and five nines for multi-region instances. Those figures are targets and promises with conditions, so read the current agreement to understand exactly what is covered.

flowchart TD
  subgraph R1["Region 1: leader region"]
    L["Leader replica"]
    RW1["Read-write replica"]
  end
  subgraph R2["Region 2"]
    RW2["Read-write replica"]
  end
  subgraph R3["Region 3"]
    W["Witness replica"]
  end
  L |"Replicate"| RW2
  L |"Replicate"| W
  L -. "Region 1 fails" .-> X["Majority still alive in Regions 2 and 3"]
  X --> N["New leader elected in Region 2"]
  N --> S["Service continues, clients retry briefly"]
    

What happens in each failure

Why majority matters

The rule of majority explains most of Spanner’s behaviour. With three voting replicas, two are enough to continue. With five, three are enough. When failures take away the majority, the affected data becomes unavailable rather than risking two sides making conflicting changes. This is the consistency-first choice described earlier. Configurations are designed so that ordinary failures never remove a majority.

Designing your client to be resilient

Even with perfect server design, applications can fail badly if they do not handle brief interruptions. The client libraries already retry many transient errors, but you must also set sensible timeouts, handle aborted transactions, and avoid piling retries on top of a struggling system. A technique called exponential backoff, which waits a little longer after each failed attempt, prevents a flood of retries from deepening a problem.

Google secures the infrastructure. You decide who may see and change your data.

Cloud security follows a shared responsibility model. Google protects the data centres, the hardware, the network and the Spanner service itself. You are responsible for who can reach your databases, which permissions they hold, how you protect keys, and what data you choose to store. Both halves must be done well.

Identity and access

Identity and Access Management, called IAM, decides which people and programs can do what. A role is a bundle of permissions. You can grant roles at the project, instance or database level. Following the principle of least privilege, give each person or program only the roles they need. An application that only reads data should not hold a role that can delete tables. Create separate service accounts for each application, instead of sharing one powerful identity.

For finer control inside a database, Spanner offers fine-grained access control. You create database roles, grant them access to specific tables, columns or views, and then let users or services use those roles. This lets you hide sensitive columns, such as national identification numbers, from people who do not need them.

Encryption

Network protection

You can limit how traffic reaches Spanner by using private connectivity, so that applications in your private network connect without crossing the public internet. VPC Service Controls create a protective boundary around Google Cloud services, which helps prevent data from being copied out of your organisation, even by someone with valid credentials. For highly sensitive systems, combine private connectivity, service controls and strict identity rules.

Auditing and data lifecycle

• Audit logs. Cloud Audit Logs record administrative actions, and can record data access too, if you enable it. Keep them long enough for your compliance rules.
• Row deletion policies. Spanner can delete rows automatically after a time you set, such as removing sessions after thirty days. This reduces both storage cost and the amount of personal data you keep.
• Separation of environments. Keep development, testing and production in different projects, with different permissions.
• Sensitive data hygiene. Do not put secrets or unneeded personal data in the database. Collect only what you must keep.

Compliance

Google Cloud publishes compliance reports and certifications for many standards, and Spanner is covered by many of them. Certifications apply to the service, but your own configuration must also meet the rules. Check the current compliance documentation for the standards that matter to your industry, and ask your compliance team to review your design before launch.

A slow database rarely announces itself. You must watch the right signals to notice early.

Spanner sends metrics to Cloud Monitoring, where you can build dashboards and alerts. It also provides its own built-in tools designed specifically for finding database problems. Learning these tools is one of the most valuable skills for a Spanner user.

The signals worth watching

Spanner’s built-in diagnostic tools

Alerts that help

Good alerts describe problems that users feel: CPU above the recommended limit for several minutes, latency far above normal, storage nearing its limit, backups failing, or a sudden jump in errors. Weak alerts fire on brief spikes and train people to ignore the pager. Link each alert to a short guide that says what to check first and how to add capacity or find the offending query.

Small design and code habits that make Spanner feel fast and keep the bill low.

Performance in Spanner comes from three places: how you design keys and tables, how your application talks to the database, and how much capacity you provide. Money cannot fix a design problem, but a good design uses money far more efficiently.

Habits that pay off

Client-side matters

Many slowdowns are caused by the application, not by Spanner. Create the database client once and share it across your whole application, instead of creating a new client for each request, because creating clients is slow and wasteful. Size the session pool to match your concurrency. Set timeouts and retry policies on purpose. Be careful with object-relational mappers, which are tools that generate SQL for you, as they may produce many small queries or inefficient joins. Review the SQL they create, and replace the worst offenders with hand-written queries.

The measure-change-measure loop

Warm-up and ramping traffic

A brand-new or newly resized database needs a little time for Spanner to learn where load is and to split and move data accordingly. Jumping instantly from no traffic to full traffic can cause short-lived slowness. When you can, ramp traffic up over several minutes or hours before a big launch, and test with the same ramp pattern.

Spanner is a premium service. Knowing what you pay for lets you spend wisely.

Spanner billing has several parts. Prices change and vary by region, edition and configuration, so always check the official pricing page and use the pricing calculator before planning a budget. The parts below describe how the bill is built, rather than quoting numbers.

What drives the bill up

• Over-provisioned compute. Running at ten percent CPU all day means paying for much more than you use. Right-size, or use autoscaling.
• Multi-region where regional would do. Multi-region costs substantially more. Use it only where the availability or global read needs justify it.
• Too many indexes. Each index uses storage and slows writes, increasing both storage and compute needs.
• Long recovery retention. Keeping many days of older versions grows storage. Choose the shortest period that meets your recovery needs.
• Forgotten instances. Test and development instances left running quietly bill every hour.
• Heavy analytics on main nodes. Running big reports on production capacity forces you to buy more nodes than the transactions need.

A thought experiment

Consider two systems. The first is a small internal booking tool for a few hundred employees, with a few queries per second. A tiny instance of a few hundred processing units, in a single region, could serve it, and Spanner’s ability to start small makes this possible. The second is a payment ledger for millions of customers across several countries, with thousands of writes per second and a strict need for correct, always-available data. It needs many nodes, a multi-region configuration and careful design. Both systems can use Spanner, but their bills differ by large factors, and both are reasonable. The wise habit is to ask, for each system, whether the guarantees it pays for are guarantees it truly needs.

An honest look at what you gain and what you give up.

The big trade-offs in plain words

Consistency against latency. Spanner chooses to always be correct, and that means writes must reach a majority of replicas. In one region this costs a few milliseconds. Across continents, it costs tens or hundreds of milliseconds. You trade some speed for the peace of mind that comes from never seeing wrong data.

Power against price. The features that make Spanner special, such as global consistency and automatic scaling, require provisioned capacity and a premium service. If your data fits comfortably on a single machine and a single region, a simpler database is cheaper and perfectly adequate.

Freedom against responsibility. You never manage servers, but you must learn to design keys and transactions for a distributed system. Habits from single-machine databases, such as auto-increment keys, can hurt here.

Google Cloud offers many databases. Knowing the neighbours helps you pick the right home for each workload.

flowchart TD
  Q1{"Mainly large-scale analytics and reports?"}
  Q1 -- "Yes" --> BQ["BigQuery"]
  Q1 -- "No" --> Q2{"Need relational data with transactions?"}
  Q2 -- "No" --> Q3{"Huge key-based throughput or time series?"}
  Q3 -- "Yes" --> BT["Bigtable"]
  Q3 -- "No" --> FS["Firestore"]
  Q2 -- "Yes" --> Q4{"Need to scale writes beyond one machine, or span regions with strong consistency?"}
  Q4 -- "Yes" --> SP["Cloud Spanner"]
  Q4 -- "No" --> Q5{"Need top PostgreSQL performance inside one region?"}
  Q5 -- "Yes" --> AL["AlloyDB"]
  Q5 -- "No" --> CS["Cloud SQL"]
    

Comparing the relational options

The most common beginner mistake is reaching for Spanner by default because it sounds impressive. If your application is a typical web app with a single region and modest traffic, Cloud SQL or AlloyDB will probably be simpler and cheaper. Another common mistake is the reverse: forcing a single-machine database to cope with global users and massive write rates, and then spending years building sharding and failover by hand. Match the tool to the real need.

A pattern is a proven recipe for a common problem. These six work especially well on Spanner.

The outbox pattern in more detail

Suppose a customer places an order, and you must also tell the shipping system. If you save the order and then separately send a message, a crash between the two steps leaves the systems in disagreement. With the outbox pattern, you write the order and an “order placed” record in one transaction. A change stream watches the outbox and publishes each new record. Either both writes happen or neither does, and the message is eventually delivered. Consumers must tolerate seeing the same message twice, so make them safe to repeat.

Multi-tenant isolation

When one database serves many customers, you can keep tenant data separate by key design, by using different databases per large tenant, or by using fine-grained access control so each tenant’s service can only see its own rows. The best mix depends on how different your tenants are in size and in compliance needs. A very large tenant may deserve its own database or even its own instance, while thousands of small tenants share one.

An anti-pattern is a habit that looks sensible at first and causes pain later.

A checklist to read before your first production launch.

Best practices

Common mistakes

Where Spanner tends to be used, and why it fits.

Detailed architectures of private companies change often and are rarely published in full, so the examples below describe well-known origins and common industry patterns rather than guaranteed facts about any one named customer. Always verify specific claims with the company’s own case studies.

Moving an existing system to Spanner is a project, not a button. Here is a calm path.

Applications built for MySQL, PostgreSQL or other databases cannot simply be pointed at Spanner. Differences in keys, features and behaviour need attention. The good news is that Google provides tools and guidance, and that a careful migration can be done with little or no downtime.

A step-by-step path

Compatibility tools

Teams using PostgreSQL can take advantage of the PostgreSQL dialect and of a compatibility layer that lets many standard PostgreSQL drivers and tools connect to Spanner. This reduces code changes, but it does not remove the need to redesign keys and to test thoroughly. Always read the current list of supported and unsupported features before committing to a migration plan.

Keeping current

Spanner evolves quickly. New editions, features, limits and prices appear regularly. Make it a habit to read the release notes a few times a year, review your instance configurations and editions, and re-check recommendations such as CPU targets when you upgrade or change capacity. Subscribe to service announcements so you hear about changes before they affect you.

Quick answers to the questions beginners ask most often.

If you remember only one page of this guide, make it this one.

Cloud Spanner is a fully managed relational database that scales across machines and regions while keeping transactions strictly correct. It cuts tables into splits, copies each split to several replicas, agrees on every write by majority vote, and orders events across the planet using accurate clocks. You gain SQL, scale, availability and consistency together, and you pay with a premium price and a design style that takes care. Success comes from good primary keys, short transactions, headroom in capacity, tested backups, careful security and honest thinking about whether you need what Spanner offers.