Sign in

1. Products
2. Google Cloud Platform
3. Google Cloud Datastore

Google Cloud Datastore

Feedback on this document

Using the Local Development Server

To develop and test your app locally, you need to use the local development server, which provides local emulation of the production Cloud Datastore environment. (You start the development server using the gcd tool.) However, you'll need to do a small amount of configuration before running your app against the development server, such as setting environment variables and adding a couple of lines of code to your app.

System requirements

To use the gcd tool, you must have Java 7 installed on your computer.

Once you have the necessary software installed, you need to download the gcd tool.

Local development server datasets

You can think of each dataset-directory as a separate, local Cloud Datastore instance. The local development server simulates Cloud Datastore by storing data in a file located at dataset-directory/WEB-INF/appengine-generated/local_db.bin . The dataset directory and required files are created by the create action as shown in this example:

 gcd-v1beta2-rev1-2.1.1/gcd.sh create [options] <dataset-directory>

where options are command line arguments supplied to the gcd tool. Typically, one of the options you supply is the dataset ID; if you omit this, the directory name is used for the dataset ID.

After creating the dataset, you can start it in the development server using this command:

 gcd-v1beta2-rev1-2.1.1/gcd.sh start [options] <dataset-directory>

Note that the dataset file persists between sessions of the local development server, so the data you stored is available to your app each time you start the local development server using the same dataset. To clear the contents of a dataset, stop the local development server and manually delete the dataset file at the location mentioned above.

Required configuration

To use the local development server for your app, you need to do the following:

• Set environment variables.
• Add or modify your app's Datastore connection code.

Setting environment variables

1. Create an environment variable DATASTORE_HOST and set it to the host and port on which the local development server is listening. The default host and port is http://localhost:8080 . ( Note: If you use the port and/or host command line arguments to change these defaults, be sure to adjust DATASTORE_HOST accordingly.) The following bash shell example shows how to set this variable:

   export DATASTORE_HOST=http://localhost:8080
   

2. Create an environment variable named DATASTORE_DATASET and set it to your dataset ID, as shown in the following bash shell example:

   export DATASTORE_DATASET=<dataset_id>
   

Adding or modifying Datastore connection code

Whether your application already has datastore connection code, or you are just adding it now, make sure the connection code connects to the development server using the environment settings above. The following snippet shows this:

# uses the DATASTORE_HOST and DATASTORE_DATASET env variables
import googledatastore as datastore

import com.google.api.services.datastore.client.Datastore;
import com.google.api.services.datastore.client.DatastoreHelper;

// uses the DATASTORE_HOST and DATASTORE_DATASET env variables
Datastore datastore = DatastoreHelper.getDatastoreFromEnv();

Starting the local development server

Once you have set the expected environment variables, and modified or added connection code to your app, you can start the local development server and run your app against it.

You start the local development server by invoking gcd from a command prompt. You do this by executing a script that lives in the top level directory of the gcd tool distribution:

gcd-v1beta2-rev1-2.1.1/gcd.sh start [options] <dataset-directory>

Stopping the local development server

To stop the local development server, press Control+C.

Local development server command-line arguments

The gcd start command supports the following command-line arguments:

--port=...

The port number to listen to on the local machine. Defaults to 8080.

--host=...

The address of the interface on the local machine to bind to. Default is localhost. Address 0.0.0.0 supports all interfaces; for example, it allows both localhost access and hostname access`.

--testing

Start the local Cloud Datastore in testing mode. Equivalent to passing --store_on_disk=false and --consistency=1.0 and --auto_generate_indexes=false . Note that the testing option may mask incorrect assumptions about the consistency of non-ancestor queries; non-ancestor queries are eventually consistent.

--consistency=...

The fraction of job application attempts that will succeed, with 0.0 resulting in no attempts succeeding, and 1.0 resulting in all attempts succeeding. Defaults to 0.9. Note that setting this to 1.0 may mask incorrect assumptions about the consistency of non-ancestor queries; non-ancestor queries are eventually consistent.

--store_on_disk=true|false

Indicates whether data should stored on disk. When set to false , data is stored in memory only. By default, data is stored on disk in <directory>/WEB-INF/appengine-generated/local_db.bin .

--auto_generate_indexes=true|false

If this option is not specified, the value of the autoGenerate attribute in <directory>/WEB-INF/datastore-indexes.xml determines whether an index configuration will be automatically generated. If that file does not exist (such as in new projects created by this tool), an index configuration will be automatically generated. Setting this option to true results in automatic index configuration, regardless of settings in <directory>/WEB-INF/datastore-indexes.xml . Setting it to false suppresses automatic index configuration, regardless of settings in <directory>/WEB-INF/datastore-indexes.xml .

--allow_remote_shutdown

Enables remote shutdown of the local Cloud Datastore instance. To shut down the Cloud Datastore instance, send a POST request with an empty payload to http://localhost:8080/_ah/admin/quit . Remote shutdown does not work in production.

Local development console

The local development server can display a web-based console that allows you to browse the contents of the local Datastore.

To access the console, visit the URL /_ah/admin on a running instance of the local development server. For example, if the development server is running on the default port, you visit http://localhost:8080/_ah/admin