Thegcloud CLI provides a local, in-memory emulator, whichyou can use to develop and test your applications. Because the emulatorstores data only in memory, all state, including data, schema, and configs, islost on restart. The emulator offers the same APIs as the Spannerproduction service and is intended for local development and testing, not forproduction deployments.

The emulator supports both the GoogleSQL and PostgreSQLdialects. It supports all languages of theclient libraries. You can also use the emulator with theGoogle Cloud CLI andREST APIs.

The emulator is also available as an open source project inGitHub.

Limitations and differences

The emulator doesn't support the following:

• TLS/HTTPS, authentication, Identity and Access Management, permissions, or roles.
• In thePLAN orPROFILEquery modes,the query plan that is returned is empty.
• TheANALYZE statement.The emulator accepts but ignores it.
• Any of theaudit logging and monitoring tools.

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

• Error messages might not be consistent between the emulator and the productionservice.
• Performance and scalability for the emulator is not comparable to theproduction service.
• Read-write transactions and schema changes lock the entire database forexclusive access until they are completed.
• Partitioned DML andpartitionQueryare supported, but the emulator doesn't check to ensure that statements arepartitionable. Thismeans that a partitioned DML orpartitionQuery statement might run in theemulator, but it might fail in the production service with thenon-partitionable statement error.

For a complete list of APIs and features that are supported, unsupported, andpartially supported, see theREADMEfile in GitHub.

Options for running the emulator

There are two common ways to run the emulator:

• gcloud CLI
• Docker

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

Set up the emulator for gcloud CLI

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

• Install thegcloud CLI components on yourworkstation:

  gcloudcomponentsinstallcloud-spanner-emulator

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

  gcloudcomponentsupdate

Create and configure the emulator using gcloud CLI

To use the emulator with gcloud CLI, you must disableauthentication and override the endpoint. We recommend creating a separategcloud CLI configuration so that youcan quickly switch back and forth between the emulator and the productionservice.

1. Create and activate an emulator configuration:

   gcloudconfigconfigurationscreateemulatorgcloudconfigsetauth/disable_credentialstruegcloudconfigsetprojectyour-project-idgcloudconfigsetapi_endpoint_overrides/spannerhttp://localhost:9020/

   Once configured, your gcloud CLI commands are sent to the emulatorinstead of the production service. You can verify this by creating an instancewith the emulator's instance config:

   gcloudspannerinstancescreatetest-instance\--config=emulator-config--description="Test Instance"--nodes=1

   To switch between the emulator and default configuration, run:

   gcloudconfigconfigurationsactivate[emulator|default]

2. Start the emulator usinggcloud CLI.

Install the emulator in Docker

1. InstallDocker on yoursystem and make it available on the system path.

2. Get the latest emulator image:

   dockerpullgcr.io/cloud-spanner-emulator/emulator

3. Run the emulator in Docker:

   dockerrun-p9010:9010-p9020:9020gcr.io/cloud-spanner-emulator/emulator

   This command runs the emulator and maps the ports in the container to thesame ports on your local host. The emulator uses two local endpoints:localhost:9010 for gRPC requests andlocalhost:9020 for REST requests.

4. Start the emulator usinggcloud CLI.

Start the emulator using gcloud CLI

Start the emulator using thegcloud emulators spannercommand:

gcloudemulatorsspannerstart

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 usesupported versions of the client librarieswith the emulator by setting theSPANNER_EMULATOR_HOST environment variable.There are many ways to do this. For example:

exportSPANNER_EMULATOR_HOST=localhost:9010

setSPANNER_EMULATOR_HOST=localhost:9010

Or withgcloud env-init:

$(gcloudemulatorsspannerenv-init)

gcloudemulatorsspannerenv-init >set_vars.cmd &&set_vars.cmd

When your application starts, the client library automatically checks forSPANNER_EMULATOR_HOST and connects to the emulator if it's running.

OnceSPANNER_EMULATOR_HOST is set, you can test the emulator by following theGetting Started guides. Ignore the instructions related to projectcreation, authentication, and credentials since these aren't needed to use theemulator.

• Getting Started in C++

• Getting Started in C#. You must set connection string options. Seeadditional instructions for C#.

• Getting Started in Go

• Getting Started in Java

• Getting Started in Node.js

• Getting Started in PHP

• Getting Started in Python

• Getting Started in Ruby

Supported versions

The following table lists the versions of theclient librariesthat support the emulator.

Additional instructions for C#

For the C# client library, you must also specify theemulatordetectionoption in theconnection string.Unlike the other client libraries, C# ignores theSPANNER_EMULATOR_HOSTenvironment variable by default. The following is an example for theconnection string:

varbuilder=newSpannerConnectionStringBuilder{DataSource=$"projects/{projectId}/instances/{instanceId}/databases/{databaseId}";EmulatorDetection="EmulatorOnly"};