Endpoint: SPANNER_EMULATOR_HOST=localhost:24085.
Spanner agent testing
Spanner local testing for AI agents
Use LocalCloud when an agent needs to create, exercise, and reset Spanner resources without touching a real Google Cloud project. The same SDK shape points at localhost through SPANNER_EMULATOR_HOST=localhost:24085.
Endpoints: gRPC :24085 · HTTP/REST :24086.
Evidence state: partial; Local development coverage is partial. Known limits: 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..
Registry default: on; assembled default: on (verified); minimum tier: pro.
Persistence: service-data (release-unverified). Ordinary container stop/start retains state; a mounted /var/lib/localcloud volume is required to retain state across container removal or replacement
Route the SDK before writing code
Start LocalCloud, export SPANNER_EMULATOR_HOST=localhost:24085, and make the agent perform one Spanner operation before changing application logic. That catches accidental production routing early.
Prefer one representative behavior over broad smoke tests
A useful agent check creates local Spanner state, reads it back with the project SDK, and records which feature was covered. It should not require a GCP account, service-account key, or billing project.
Use only documented setup paths
Create deterministic state through a contract-documented seed registrar or through an operation listed on this page. Do not assume every service supports seed data, reset, or persistent state.
Copy-ready setup
Commands and prompts
Use these snippets as starting points, then keep the checks scoped to localhost until you intentionally validate against real Google Cloud.
Environment
eval "$(localcloud env)"
# Verify that the generated environment includes SPANNER_EMULATOR_HOST; do not replace a CLI-remapped value with a hard-coded port. Compatibility
Local check versus release validation
| Area | LocalCloud local check | Real GCP still needed for |
|---|---|---|
| SDK routing | SPANNER_EMULATOR_HOST=localhost:24085 points clients at localhost. | Production endpoint, auth, IAM, quota, and regional behavior. |
| Supported features | 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: unknown; Sessions, transactions, and batch DML: unknown; Partition query/read and batch write: unknown; Instance, configuration, and instance-partition administration: unknown; Database administration and DDL: unknown; Instance and database IAM policies: unknown; Backup, copy, restore, and backup schedules: unknown; Long-running operation lifecycle: unknown | |
| Agent safety | No default cloud account, credentials, or billing project required. | Final release validation in the target GCP project. |
Use the sandbox deliberately
- Permitted workflows use local endpoint values and should stop rather than fall back to real Google Cloud or real credentials. The Public Preview License permits individuals and organizations, including for-profit companies, to use LocalCloud for non-production internal development, testing, CI, evaluation, and pilots.
- LocalCloud emulates bounded local development workflows. Validate application behavior against real Google Cloud before production deployment.
- Before production deployment, unset LocalCloud emulator environment variables and validate behavior against real Google Cloud.
- Local development coverage is partial. Known limits: 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..
Keep the agent on the supported path
- Spanner service page — Service-specific supported and unsupported capability list.
- Compatibility matrix — Check current support boundaries before relying on a local-only test.
- Service catalog — Review every LocalCloud service, endpoint, and limitation.
- SDK examples — Use standard Google Cloud SDKs pointed at localhost.
- Seed data — Load deterministic fixtures for repeatable agent and CI runs.
Claims are tied to current sources
- LocalCloud service metadata — Reviewed 2026-08-26; implementation extended-official.
- LocalCloud agentic facts reviewed 2026-08-26.