Home

Awesome

Cloud Spanner Emulator

Cloud Spanner Emulator provides application developers with a locally-running, emulated instance of Cloud Spanner to enable local development and testing.

The main focus of the emulator is correctness - an application that runs against the emulator should be able to run against the Cloud Spanner service without any changes. It is not a goal of the emulator to be a performant standalone production database or to provide similar performance to Cloud Spanner. The emulator is specifically intended for local unit testing of applications targeting Cloud Spanner.

Quickstart

There are multiple ways to invoke the emulator.

Via devcontainers

To build, develop and test emulator, devcontainers can be used which installs all the emulator dependencies inside a docker container. Opening this repository in vscode will automatically use the devcontainer defined in .devcontainer directory. This requires docker to be installed on the local machine.

To work directly in the browser without installing docker, a github Codespace can be created and opened in vscode.dev in the browser.

Via gcloud

The emulator is included in the Google Cloud SDK and can be invoked via the gcloud emulators command group:

gcloud components update
gcloud emulators spanner start

Via pre-built docker image

The emulator is also provided as a pre-built docker image. You can run the latest version with:

docker pull gcr.io/cloud-spanner-emulator/emulator
docker run -p 9010:9010 -p 9020:9020 gcr.io/cloud-spanner-emulator/emulator

The first port is the gRPC port and the second port is the REST port. The docker images are also tagged with version numbers, so you can run a specific version with:

VERSION=1.5.6
docker run -p 9010:9010 -p 9020:9020 gcr.io/cloud-spanner-emulator/emulator:$VERSION

Works on x86 and arm64 architectures.

Via pre-built linux binaries

The emulator is also distributed as a standalone linux binary. Note that this binary is not fully static, but has been tested on Ubuntu 18.04+, CentOS 7+, RHEL 8+ and Debian 10+.

Set ARCHITECTURE to arm64 in following command if you are working on arm machine.

VERSION=1.5.6
ARCHITECTURE=amd64
wget https://storage.googleapis.com/cloud-spanner-emulator/releases/${VERSION}/cloud-spanner-emulator_linux_${ARCHITECTURE}-${VERSION}.tar.gz
tar xvf cloud-spanner-emulator_linux_${ARCHITECTURE}-${VERSION}.tar.gz
chmod u+x gateway_main emulator_main

emulator_main contains the gRPC server. If you do not need REST functionality, you can just use this binary. To override the default host/port at which the emulator runs:

./emulator_main --host_port localhost:1234

gateway_main is the REST gateway which will also start the emulator gRPC server as a subprocess. To override the default host/port for the gateway and emulator:

./gateway_main --hostname localhost --grpc_port 1234 --http_port 1235

Via bazel

Production releases of the emulator are built on Ubuntu 18.04 with bazel 5.4.0 and gcc 8.4. You may be able to compile on compatible systems with compatible toolchains. From the emulator source directory, you can build and run the emulator via bazel from the source root with:

bazel run binaries/gateway_main

Works on x86 and arm64 architectures.

Via custom docker image

You can build the emulator docker image from the source root with:

docker build . -t emulator -f build/docker/Dockerfile.ubuntu

You can then invoke the emulator with:

docker run -p 9010:9010 -p 9020:9020 emulator

The first port is the gRPC port and the second port is the REST port.

Works on x86 and arm64 architectures.

Technical Details

The Cloud Spanner Emulator is built using the ZetaSQL reference implementation and is divided into three layers (each in its own directory):

The core emulator codebase is in C++, and the REST wrapper is written in Go. SQL query execution, value/type classes, and SQL functions are provided by the ZetaSQL reference implementation. The API surface, DDL, transactional semantics, constraint enforcement, and in-memory storage are implemented in this codebase.

Features and Limitations

Notable supported features:

Notable limitations:

Frequently Asked Questions (FAQ)

Which client library versions are supported?

All Cloud Spanner client libraries support the emulator. Install the following version (or higher) to get emulator support:

Client LibraryVersion
C++v0.9.x
C#v3.1.0
Gov1.5.0
Javav1.51.0
Node.jsv4.5.0
PHPv1.25.0
Pythonv1.15.0
Rubyv1.13.0

How do I fix the client library error with "UNAUTHENTICATED: Credentials require .."?

Upgrade to the latest client library versions as listed above.

What is the recommended test setup?

Use a single emulator process and create a Cloud Spanner instance within it. Since creating databases is cheap in the emulator, we recommend that each test bring up and tear down its own database. This ensures hermetic testing and allows the test suite to run tests in parallel if needed.

Why is the order of rows returned by the emulator different across runs?

The emulator intentionally randomizes query results with no ORDER BY clause. You should not depend on ordering done by the Cloud Spanner service in the absence of an ORDER BY clause.

Why does the emulator fail with "Check failed: LoadTimeZone(...)"

The emulator relies on the absl library which in turns uses the tzdata library. The tzdata library must be installed on the system which emulator is running. This will need to be added to the docker build file if you are running through docker.

Contribute

We are currently not accepting external code contributions to this project.

Issues

Please file bugs and feature requests using GitHub's issue tracker or using the existing Cloud Spanner support channels.

Security

For information on reporting security vulnerabilities, see SECURITY.md.

License

Apache License 2.0