Spanner emulator

Spanner is a distributed database with SQL and transactional consistency. Use its relational model when application workflows need coordinated updates across related records.

When to use Spanner

Typical uses

Use when related records need transactional consistency and SQL queries, and your production architecture requires a database that can scale across nodes.

Examples

Transactional order and inventory systems
Relational applications using GoogleSQL or PostgreSQL

Databases

Hello world

Example usage

Install the CLI, start LocalCloud, and export its environment in the same shell. Generated endpoints account for remapped ports.

1. Install and start · shell

curl -fsSL https://local.cloud/install.sh | sh
localcloud start --local-only
# Export GOOGLE_CLOUD_PROJECT and SPANNER_EMULATOR_HOST
eval "$(localcloud env)"

Python

Create a database and query a row

2. Install SDK · shell

python3 -m venv .venv
source .venv/bin/activate
python -m pip install google-cloud-spanner

3. Save as hello.py

import os
from uuid import uuid4
from google.cloud import spanner

assert os.environ['SPANNER_EMULATOR_HOST']
client = spanner.Client(project=os.environ['GOOGLE_CLOUD_PROJECT'])
instance = client.instance('guide-' + uuid4().hex[:12], configuration_name='projects/' + client.project + '/instanceConfigs/emulator-config', display_name='Guide', node_count=1)
instance.create().result(timeout=60)
try:
    database = instance.database('messages', ddl_statements=['CREATE TABLE Messages (Id INT64 NOT NULL, Message STRING(100)) PRIMARY KEY (Id)'])
    database.create().result(timeout=60)
    with database.batch() as batch:
        batch.insert('Messages', columns=('Id', 'Message'), values=[(1, 'hello')])
    with database.snapshot() as snapshot:
        rows = list(snapshot.execute_sql('SELECT Message FROM Messages WHERE Id = 1'))
        assert rows == [['hello']]
        print(rows[0][0])
    database.drop()
finally:
    instance.delete()
    client.close()

4. Runpython hello.py

Full example guide

Documented workflows

GoogleSQL/PostgreSQL queries, UUIDs, and change streams
Full-text/vector search, property graphs, and graph algorithms
Sessions, serializable/repeatable-read transactions, and batch DML
Partitioned queries/reads and batch writes
Instance/database administration, DDL, and long-running operations
Database roles and fine-grained access control
Backup creation, copy, restore, and schedules

Service boundaries

Change streams require streaming SQL
Backups and durable stream recovery require a persistent data directory
Unauthenticated emulator connections bypass network IAM
No CMEK; Google TrueTime and regional infrastructure are cloud-only

Try it in your project

Code examples and integrations

Start with the local guides. Official Google Cloud samples may need endpoint changes and can cover features outside the workflows listed here.

Integration

Build an integration test loop

Start the runtime, verify readiness, exercise your SDK, and clean up test state.

Open guide

Google Cloud

Official SDK code samples

Browse language-specific samples. Adapt endpoints and use the local workflows listed above.

Browse official samples

Agent testing

Use Spanner with an AI agent

Before the agent changes application logic, have it create local Spanner state, read it back with the project SDK, and note which feature the check covered. That first local call catches accidental production routing and needs no GCP account, service-account key, or billing project.

Configure this repo

Set up this repository to use LocalCloud for local GCP development. First read https://local.cloud/ai/agents.md, then inspect this repo, identify the GCP services and SDK language, configure emulator environment variables, and run the narrowest integration test against localhost. Do not use real GCP credentials or production endpoints.

Production endpoints, auth, IAM, quotas, regional behavior, and final release validation still need the target Google Cloud project.

Agent resources has more prompts and the AGENTS.md template.