Running the Cloud Datastore Emulator

The Google Cloud Datastore emulator provides local emulation of the production Cloud Datastore environment. You can use the emulator to develop and test your application locally. In addition, the emulator can help you generate indexes for your production Cloud Datastore instance and delete unneeded indexes. This page guides you through installing the emulator, starting the emulator, and setting environment variables to connect your application to the emulator.

Before you begin

To use the Cloud Datastore emulator you need:

Installing the emulator

The Cloud Datastore emulator is a component of the Google Cloud SDK's gcloud tool. Use the gcloud components install command to install the Cloud Datastore emulator:

gcloud components install gcd-emulator

Emulator data directories

The emulator simulates Cloud Datastore by creating /WEB-INF/appengine-generated/local_db.bin in a specified data directory and storing data in local_db.bin. By default, the emulator uses the data directory ~/.config/gcloud/emulators/datastore/. The local_db.bin file persists between sessions of the emulator. You can set up multiple data directories and think of each as a separate, local Cloud Datastore instance. To clear the contents of a local_db.bin file, stop the emulator and manually delete the file.

Starting the emulator

Start the emulator by executing datastore start from a command prompt:

gcloud beta emulators datastore start [flags]

where [flags] are optional command-line arguments supplied to the gcloud tool. For example:

  • --data-dir=[DATA_DIR] changes the emulator's data directory. The emulator creates the /WEB-INF/appengine-generated/local_db.bin file inside [DATA_DIR] or, if available, uses an existing file.

  • --no-store-on-disk configures the emulator not to persist any data to disk for the emulator session.

See the gcloud beta emulators datastore start reference for the full list of optional flags.

After you start the emulator, you should see a message similar to the following:

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

To stop the emulator, type Control-C at the command prompt.

Setting environment variables

After you start the emulator, you need to set environment variables so that your application connects to the emulator instead of the production Cloud Datastore environment. Set these environment variables on the same machine that you use to run your application.

You need to set the environment variables each time you start the emulator. The environment variables depend on dynamically assigned port numbers that could change when you restart the emulator.

Automatically setting the variables

If your application and the emulator run on the same machine, you can set the environment variables automatically:

Linux / macOS

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

Your application will now connect to the Cloud Datastore emulator.

Manually setting the variables

If your application and the emulator run on different machines, set the environment variables manually:

  1. Run the env-init command:

    gcloud beta emulators datastore env-init
  2. On the machine that runs your application, set the environment variables and values as directed by the output of the env-init command. For example:

    Linux / macOS
    export DATASTORE_EMULATOR_HOST=localhost:8432
    export DATASTORE_PROJECT_ID=my-project-id
    Windows
    set DATASTORE_EMULATOR_HOST=localhost:8432
    set DATASTORE_PROJECT_ID=my-project-id

Your application will now connect to the Cloud Datastore emulator.

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.

Removing environment variables

After you finish using the emulator, stop the emulator (Control-C) and remove the environment variables so your application will connect to your production Cloud Datastore instance.

Automatically removing the variables

If your application and the emulator run on the same machine, you can remove the environment variables automatically:

Linux / macOS

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

Your application will now connect to your production Cloud Datastore instance.

Manually removing the variables

If your application and the emulator run on different machines, remove the environment variables manually:

  1. Run the env-unset command:

    gcloud beta emulators datastore env-unset
  2. On the machine that runs your application, remove the environment variables as directed by the output of the env-unset command. For example:

    Linux / macOS
    unset DATASTORE_EMULATOR_HOST
    unset DATASTORE_PROJECT_ID
    Windows
    set DATASTORE_EMULATOR_HOST=
    set DATASTORE_PROJECT_ID=

Your application will now connect to your production Cloud Datastore instance.

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

Cloud Datastore Documentation