Emulate Spanner locally

The gcloud CLI provides a local, in-memory emulator, which you can use to develop and test your applications for free without creating a Google Cloud project or a billing account. As the emulator stores data only in memory, all state, including data, schema, and configs, is lost on restart. The emulator offers the same APIs as the Spanner production service and is intended for local development and testing, not for production deployments.

The emulator supports both the GoogleSQL and PostgreSQL dialects. It supports all languages of the client libraries. You can also use the emulator with the Google Cloud CLI and REST APIs.

The emulator is also available as an open source project in GitHub.

Limitations and differences

The emulator does not support the following:

  • TLS/HTTPS, authentication, IAM, permissions, or roles.
  • PLAN or PROFILE query modes. It only supports NORMAL.
  • The ANALYZE statement. The emulator accepts but ignores it.
  • Any of the audit logging and monitoring tools.

The emulator also differs from the Spanner production service in the following ways:

  • Error messages may not be consistent between the emulator and the production service.
  • Performance and scalability for the emulator is not comparable to the production service.
  • Read-write transactions and schema changes will lock the entire database for exclusive access until they are completed.
  • Partitioned DML and Partition Query are supported, but the emulator does not check to ensure that statements are partitionable. This means that a Partitioned DML or Partition Query statement might run in the emulator, but may fail in the production service with non-partitionable statement error.

For a complete list of APIs and features that are supported, unsupported, and partially supported, see the README file in GitHub.

Install and run the emulator

The two most common ways to run the emulator are by using gcloud CLI and Docker. You may choose the way that is appropriate for your application development and test workflow.

gcloud CLI

  1. Install the gcloud CLI.

  2. For Windows and MacOS users, the emulator requires Docker to be installed on your system and available on the system path.

  3. Update gcloud to get the latest version:

    gcloud components update

  4. Start the emulator:

    gcloud emulators spanner start

    If the emulator is not installed already, you will be prompted to download and install the binary for the emulator.

    By default, the emulator hosts two local endpoints: localhost:9010 for gRPC requests and localhost:9020 for REST requests.

    For more details about this command, see gcloud emulators spanner.

Docker

  1. Make sure Docker is installed on your system and available on the system path.

  2. Get the latest emulator image:

    docker pull gcr.io/cloud-spanner-emulator/emulator

  3. Start the emulator:

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

    This command runs the emulator and maps the ports in the container to the same ports on your local host. You will have two local endpoints: localhost:9010 for gRPC requests and localhost:9020 for REST requests.

Use the gcloud CLI with the emulator

To use the emulator with gcloud, you must disable authentication and override the endpoint.

We recommend creating a separate gcloud configuration, so that you can quickly switch back and forth between the emulator and the production service. To create and activate an emulator configuration, run:

gcloud config configurations create emulator
  gcloud config set auth/disable_credentials true
  gcloud config set project your-project-id
  gcloud config set api_endpoint_overrides/spanner http://localhost:9020/

Once configured, your gcloud commands will be sent to the emulator instead of the production service. You can verify this by creating an instance with the emulator's instance config:

gcloud spanner instances create test-instance \
   --config=emulator-config --description="Test Instance" --nodes=1

To switch between the emulator and default configuration, run:

gcloud config configurations activate [emulator | default]

Use the client libraries with the emulator

You can use supported versions of the client libraries with the emulator by setting the SPANNER_EMULATOR_HOST environment variable. There are many ways to do this. For example:

Linux / macOS

export SPANNER_EMULATOR_HOST=localhost:9010

Windows

set SPANNER_EMULATOR_HOST=localhost:9010

Or with gcloud env-init:

Linux / macOS

$(gcloud emulators spanner env-init)

Windows

gcloud emulators spanner env-init > set_vars.cmd && set_vars.cmd

When your application starts, the client library automatically checks for SPANNER_EMULATOR_HOST and connects to the emulator if it is running.

Once SPANNER_EMULATOR_HOST is set, you can test the emulator by following the Getting Started guides below. You can ignore the instructions related to project creation, authentication, and credentials since these are not needed to use the emulator.

Supported versions

The following table lists the versions of the client libraries that support the emulator.

Client library Minimum version
C++ v0.9.x+
C# v3.1.0+
Go v1.5.0+
Java v1.51.0+
Node.js v4.5.0+
PHP v1.25.0+
Python v1.15.0+
Ruby v1.13.0+

Additional instructions for C#

For the C# client library, you must also specify the emulatordetection option in the connection string. Unlike the other client libraries, C# ignores the SPANNER_EMULATOR_HOST environment variable by default. Here's how to do it:

var builder = new SpannerConnectionStringBuilder
{
    DataSource = $"projects/{projectId}/instances/{instanceId}/databases/{databaseId}";
    EmulatorDetection = "EmulatorOnly"
};