Datastore Emulator

To develop and test your application locally, you need to use the Google Cloud Datastore emulator, which provides local emulation of the production Cloud Datastore environment. You can start the Cloud Datastore emulator using the gcloud tool. However, you'll need to do a small amount of configuration before running your application against the emulator, such as starting the emulator and setting environment variables.

For a walkthrough of how to use the Cloud Datastore emulator with your application, see Using the gcloud tool.

Prerequisites

Emulator versions

There are two versions of the Cloud Datastore emulator:

  • the legacy version, which supports Cloud Datastore API v1beta2
  • the gRPC version, which supports Cloud Datastore API v1beta3 via gRPC

The following table shows which version of the Cloud Datastore emulator to use with the Google Cloud Client Libraries:

Language Library Emulator version
Go Google Cloud Client Library for Go gRPC
Java Google Cloud Client Library for Java legacy
Node.js Google Cloud Client Library for Node.js gRPC
Python Google Cloud Client Library for Python legacy
Ruby Google Cloud Client Library for Ruby gRPC

You specify which version to use when you start the emulator, using the --legacy or --no-legacy options.

Starting the emulator

You start the emulator by invoking datastore start from a command prompt:

gcloud beta emulators datastore start [options]

where [options] are command line arguments supplied to the gcloud tool.

One of the options you can supply is --project=<project-id>, where <project-id> is the ID of the project that you want to use. If you omit the --project option, the project ID that gcloud considers current is used. You can control which project gcloud considers current by using the gcloud config set command.

Another option you can supply is --data-dir=<directory>, where <directory> is the directory you want to use. The first time you invoke the datastore start command for a given data directory, that directory is associated with the same project ID for all future Cloud Datastore emulator runs.

The --store-on-disk=<True|False> option controls whether data is persisted to local disk during emulator sessions. The default is True. The emulator persists data in the project directory as described in Emulator project directories.

The --legacy and --no-legacy options control which version of the Cloud Datastore emulator to start. The neither option is specified, the default is the legacy emulator. Use the --no-legacy flag to start the gRPC emulator.

After you start the emulator, you can confirm it is running by seeing a message similar to:

gRPC emulator

...
[datastore] Dev App Server is now running.

legacy emulator

...
[datastore] INFO: Dev App Server is now running

Emulator project directories

When you start the emulator and make requests against it, data is persisted in the project directory. You can think of each project directory as a separate, local Cloud Datastore instance. The emulator simulates Cloud Datastore by storing data in a file located at <project-directory>/WEB-INF/appengine-generated/local_db.bin. By default, the data directory that contains WEB-INF/appengine-generated/local_db.bin is ~/.config/gcloud/emulators/datastore/.

Note that the data file persists between sessions of the emulator unless the --store-on-disk option is False, so the data you stored is available to your application each time you start the emulator using the same Cloud Datastore instance. To clear the contents of a data file, stop the emulator and manually delete the data file at the location mentioned above.

Setting environment variables

Run the env-init command to determine and set the environment variables that enable your application to use the emulator. These environment variables rely on a running instance of the emulator, so ensure that you have already started the emulator.

Automatically setting the variables

Linux / Mac OS X

Run env-init using command substitution:

$(gcloud beta emulators datastore env-init)

Windows

Create and run a batch file using output from env-init:

gcloud beta emulators datastore env-init > set_vars.cmd && set_vars.cmd

Manually setting the variables

Run the env-init command:

gcloud beta emulators datastore env-init

and then create the environment variables and values as directed by the output of the env-init command. For example (values may be different based on your environment):

Linux / Mac OS X

export DATASTORE_DATASET=my-project-id
export DATASTORE_EMULATOR_HOST_PATH=localhost:8432/datastore
export DATASTORE_HOST=http://localhost:8432
export DATASTORE_EMULATOR_HOST=localhost:8432
export DATASTORE_PROJECT_ID=my-project-id

Windows

set DATASTORE_DATASET=my-project-id
set DATASTORE_EMULATOR_HOST_PATH=localhost:8432/datastore
set DATASTORE_HOST=http://localhost:8432
set DATASTORE_EMULATOR_HOST=localhost:8432
set DATASTORE_PROJECT_ID=my-project-id

You can now run your application with the Cloud Datastore emulator providing local emulation of the production Cloud Datastore environment.

Removing environment variables

After you are done using the emulator, you remove environment variables to enable your application to use your production Cloud Datastore instance.

Automatically removing the variables

Linux / Mac OS X

Run env-unset using command substitution:

$(gcloud beta emulators datastore env-unset)

Windows

Create and run a batch file using output from env-unset:

gcloud beta emulators datastore env-unset > remove_vars.cmd && remove_vars.cmd

Manually removing the variables

Run the env-unset command:

gcloud beta emulators datastore env-unset

and then remove the environment variables as directed by the output of the env-unset command. For example (values may be different based on your environment):

Linux / Mac OS X

unset DATASTORE_DATASET
unset DATASTORE_EMULATOR_HOST_PATH
unset DATASTORE_HOST
unset DATASTORE_EMULATOR_HOST
unset DATASTORE_PROJECT_ID

Windows

set DATASTORE_DATASET=
set DATASTORE_EMULATOR_HOST_PATH=
set DATASTORE_HOST=
set DATASTORE_EMULATOR_HOST=
set DATASTORE_PROJECT_ID=

You can now run your application with the production Cloud Datastore environment.

Stopping the emulator

To stop the emulator, press Ctrl+C.

Emulator command-line arguments

For details on command-line arguments for the Cloud Datastore emulator, see gcloud beta emulators datastore start.

Emulator console

The legacy emulator can display a web-based console that allows you to browse the contents of the local Cloud Datastore instance.

To access the console, visit the URL /_ah/admin on a running instance of the legacy emulator. For example, if the emulator is running on port 8432, you visit http://localhost:8432/_ah/admin. The output from the emulators datastore start command displays your project's local admin console URL in a line similar to:

...
[datastore] INFO: The admin console is running at http://localhost:8432/_ah/admin

Updating and deleting indexes

By running your application using the emulator, you can generate indexes for your production Cloud Datastore instance, as well as delete unneeded indexes. Learn more at Using the gcloud tool.

Send feedback about...

Cloud Datastore