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.
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.
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.
To use the local development server for your app, you need to do the following:
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
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>
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();
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>
To stop the local development server, press Control+C.
The
gcd
start
command supports the following command-line
arguments:
--port=...
--host=...
--testing
--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=...
--store_on_disk=true|false
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
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
http://localhost:8080/_ah/admin/quit
. Remote shutdown does not work in
production.
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