Runtime details
- Endpoints
- gRPC :24085 · HTTP/REST :24086
- Minimum tier
- pro
- Persistence
- service-data
- Documented workflows
- 0
0 documented workflows
Run Spanner workflows locally
Spanner data and administration workflows over gRPC and REST.
Documented workflows
Service boundaries
- Pinned extended Spanner emulator image; the exact image and immutable digest come from `SPANNER_EMULATOR_IMAGE` in the root Dockerfile.
- Change-stream support matrix — native gRPC/REST ExecuteStreamingSql supported; official SDK clients through SPANNER_EMULATOR_HOST supported; LocalCloud SQL Editor through managed run APIs or cancellable /query/stream NDJSON supported; gcloud spanner databases execute-sql unsupported for change streams because it uses unary ExecuteSql.
- Native SQL, read, and streaming read: Local support is not documented. Change-stream reads use native ExecuteStreamingSql. Unary ExecuteSql intentionally retains the emulator's rejection of change-stream queries.
- Sessions, transactions, and batch DML: Local support is not documented. Existing native transaction and session behavior remains authoritative.
- Partition query/read and batch write: Local support is not documented. Existing native partition and batch-write behavior remains authoritative.
- Instance, configuration, and instance-partition administration: Local support is not documented. Existing native instance-admin behavior remains authoritative.
- Database administration and DDL: Local support is not documented. Existing native database-admin behavior remains authoritative.
- Instance and database IAM policies: Local support is not documented. Policies are stored durably and returned through native endpoints. Authorization remains intentionally permissive and TestIamPermissions returns requested permissions.
- Backup, copy, restore, and backup schedules: Local support is not documented. Backups and schedules use LevelDB-backed metadata and compatible long-running operations.
- Long-running operation lifecycle: Local support is not documented. Native operation polling and lifecycle behavior is shared by instance, database, backup, copy, and restore calls.
- Ordinary container stop/start retains state; a mounted /var/lib/localcloud volume is required to retain state across container removal or replacement
- Rows use LevelDB and metadata uses JSON files.
- Known corruption/recovery risk; internal safety snapshots are not Cloud Spanner Backup API.
FAQ
Common questions
How do I run Spanner locally?
Install the LocalCloud host CLI, start the runtime, and load the generated environment values into your application process. Spanner is then reachable at the endpoints the CLI reports, and standard Google Cloud clients resolve to localhost instead of googleapis.com.
Which environment variable points the SDK at the local Spanner?
LocalCloud exports SPANNER_EMULATOR_HOST=localhost:24085. Read the value from the generated environment rather than assuming a fixed port, because occupied ports are remapped at startup.
What Spanner workflows are documented locally?
0 Spanner workflows are documented with operation-level status: . The compatibility matrix lists the status of every operation.
Does the local Spanner behave exactly like Google Cloud?
No. LocalCloud implements documented local workflows with published boundaries, and compatibility is narrower than managed Google Cloud. Validate behavior against real Spanner before production deployment.
Can an AI coding agent use the local Spanner?
Yes. Because no cloud credentials or billing project are required by default, agent-written Spanner code can run against localhost without creating real cloud resources or charges.