Emulate Spanner locally

The gcloud CLI provides a local, in-memory emulator, which you can use to develop and test your applications with a free trial instance without creating a Google Cloud project or a billing account. Because 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 doesn't support the following:

  • TLS/HTTPS, authentication, Identity and Access Management, permissions, or roles.
  • In the PLAN or PROFILE query modes, the query plan that is returned is empty.
  • 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 might 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 lock the entire database for exclusive access until they are completed.
  • Partitioned DML and partitionQuery are supported, but the emulator doesn't check to ensure that statements are partitionable. This means that a partitioned DML or partitionQuery statement might run in the emulator, but it might fail in the production service with the 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.

Options for running the emulator

There are two common ways to run the emulator:

Choose the way that is appropriate for your application development and test workflow.

Set up the emulator for gcloud CLI

For Windows and macOS users, before installing the emulator, do the following:

  • Install the gcloud CLI components on your workstation:

    gcloud components install

    If gcloud CLI is already installed, run the following command to ensure all of its components are updated:

    gcloud components update

Create and configure the emulator using gcloud CLI

To use the emulator with gcloud CLI, you must disable authentication and override the endpoint. We recommend creating a separate gcloud CLI configuration so that you can quickly switch back and forth between the emulator and the production service.

  1. Create and activate an emulator configuration:

      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 CLI commands are 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]

  2. Start the emulator using gcloud CLI.

Install the emulator in Docker

  1. Install Docker on your system and make it available on the system path.

  2. Get the latest emulator image:

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

  3. Run the emulator in Docker:

    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. The emulator uses two local endpoints: localhost:9010 for gRPC requests and localhost:9020 for REST requests.

  4. Start the emulator using gcloud CLI.

Start the emulator using gcloud CLI

Start the emulator using the gcloud emulators spanner command:

gcloud emulators spanner start

The emulator uses two local endpoints:

  • localhost:9010 for gRPC requests
  • localhost:9020 for REST requests

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's running.

Once SPANNER_EMULATOR_HOST is set, you can test the emulator by following the Getting Started guides. Ignore the instructions related to project creation, authentication, and credentials since these aren't 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. The following is an example for the connection string:

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