Services Spanner emulator features

Spanner emulator feature reference

LocalCloud integrates an extended Cloud Spanner emulator. GoogleSQL and PostgreSQL dialects run through the Spanner API; dialect support does not imply complete SQL, transaction, graph, search, authorization, backup, or change-stream parity.

Connections and persistence

Surface	Canonical value	Boundary
gRPC API	`SPANNER_EMULATOR_HOST=localhost:5386`	Use generated host ports and test the selected SDK/version.
REST gateway	`http://localhost:5387`	REST / grpc-gateway, not PostgreSQL wire.
PostgreSQL dialect	Queries through the Spanner API	LocalCloud does not package PGAdapter; `psql` and pgJDBC need a separately configured adapter.
State	LevelDB rows and JSON metadata under `/var/lib/localcloud/spanner-data`	Mounted storage is required for retained state; see the recovery limits below.

Use localcloud env for the actual mapped endpoints. Provision the instance, database, and schema before querying; a code example that refers to an uncreated database is not a complete quick start.

Current operation contract

Operation area	Status	Boundary
Native SQL, read, and streaming read	Supported	Native ExecuteSql and ExecuteStreamingSql in both GoogleSQL and PostgreSQL dialects. StreamingRead and ExecuteStreamingSql stream whole rows with resume tokens at row boundaries. Unary ExecuteSql intentionally retains the emulator's rejection of change-stream queries. Full-text search (TOKENIZE_, SEARCH, SNIPPET, SCORE), vector search (APPROX_ / ScaNN), and 13 graph algorithms (PageRank, ShortestPath, etc.) compute locally.
Sessions, transactions, and batch DML	Supported	Sessions (including batch create and multiplexed), read-write, read-only and single-use transactions. SERIALIZABLE (default) and REPEATABLE_READ isolation. Conflicts follow wound-wait lock waits (--lock_wait_timeout_ms). Exclusive locks via SELECT ... FOR UPDATE and LOCK_SCANNED_RANGES=exclusive. Commit timestamps (PENDING_COMMIT_TIMESTAMP) and commit stats (mutation count). Deadlock aborts exactly one transaction. Unique indexes are re-checked at commit.
Partition query/read and batch write	Supported	PartitionRead, PartitionQuery, partitioned DML (including parameterized PostgreSQL statements), and BatchWrite are supported.
Instance, configuration, and instance-partition administration	Supported	Instance and instance-partition administration, custom instance configurations, and MoveInstance (metadata). List operations and instances support AIP-160 filter expressions.
Database administration and DDL	Supported	Database creation, DDL execution for both GoogleSQL and PostgreSQL, drop protection (UpdateDatabase), ListDatabaseOperations, split points (AddSplitPoints persisted to SPANNER_SYS.USER_SPLIT_POINTS), and fine-grained access control database roles (CREATE/DROP ROLE, GRANT/REVOKE, ListDatabaseRoles).
Instance and database IAM policies	Supported	IAM policies are stored durably in LevelDB and returned through native endpoints with etags guarded. Fine-grained access control (FGAC) is enforced for sessions created with a creator_role on queries, DML, reads, mutations, and change stream reads. Unauthenticated emulator connections bypass network IAM.
Backup, copy, restore, and backup schedules	Supported	With --data_dir, CreateBackup, CopyBackup, GetBackup, ListBackups (with AIP-160 filter precedence), UpdateBackup, DeleteBackup, RestoreDatabase, and ListBackupOperations are supported. version_time backups and full/incremental backup schedules persist cursors across restarts.
Long-running operation lifecycle	Supported	Native long-running operations lifecycle across instance, database, backup, copy, and restore calls, with AIP-160 filter support.

Features that need scoped checks

GoogleSQL and PostgreSQL dialect types, DDL, query syntax, and metadata.
Transaction isolation, wound-wait conflict handling, retries, locking, and commit metadata.
Graph, vector, and full-text query behavior beyond parser or catalog acceptance.
Fine-grained database roles, caller identity, and enforcement through every required API path.
Backup, restore, point-in-time reads, schedules, change streams, and resume behavior.

A declaration or registered method alone does not establish these semantics. Keep any broader standalone dependency evidence separate from the current LocalCloud operation contract.

Runtime and recovery limits

Extended Spanner emulator image supports 140 features. Public-endpoint client matrix is 100% verified against native builds and packaged Docker image with Python (3.71.0), Go (1.95.1), Node.js (9.0.0), Java (6.123.0), JDBC (2.45.0), and PGAdapter (0.55.3 with pgJDBC and psql).
Database roles and fine-grained access control (FGAC) are enforced for sessions created with a creator_role. Unauthenticated emulator connections bypass IAM principal identity checks; stored IAM policies do not enforce network identity.
Change streams require ExecuteStreamingSql; unary ExecuteSql rejects change-stream queries. With --data_dir, stream definitions, records, partition history, and resume tokens survive restarts.
Backups require --data_dir; each backup is a full database copy. Customer-managed encryption keys (CMEK) are not implemented (data is plaintext).
Cloud-only infrastructure (Google TrueTime hardware clock, multi-region Paxos quorum switching, physical split points and tablet distribution, physical cross-region migration, multi-tenant compute slicing) does not apply to local development.
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.

Verify production IAM, managed replication, regional availability, performance, and required functional behavior in Google Cloud before release.

Was this page helpful?