Installation

The most common way to install gcloudc is to use it as part of Djangae.

You can also install it on its own with pip install django-gcloud-connectors.

However you install it, you will need to set your DATABASES configuration in your Django settings module to look something like this:

DATABASES = {
    "default": {
        'ENGINE': 'gcloudc.db.backends.datastore',
        'PROJECT': 'YOUR_GCP_PROJECT_NAME',  # You can use djangae.environment.project_id() here
        'INDEXES_FILE': 'PATH_TO_A_FILE_FOR_SPECICAL_INDEXES',
    }
}

The possible engines you can choose are:

  • gcloudc.db.backends.firestore
  • gcloudc.db.backends.datastore

INDEXES_FILE is an absolute path to a yaml file that will be automatically generated. See [special_indexes.md] for more information.

Enabling aggregation query emulation

Datastore emulator does not support aggregation quires, so when using gcloudc.db.backends.datastore engine, it requires count_mode option to be set to "emulated" to work correctly.

# settings.py
from djangae.environment import is_development_environment

DATABASES = {
    "default": {
        "ENGINE": 'gcloudc.db.backends.datastore',
        # ... other settings
        "OPTIONS": {
            "count_mode": "emulated" if is_development_environment() else "native"
        },
    }
}

You can also use "emulated" mode with non-emulated datastore, since native implementation has some limitations.

Note: gcloudc.db.backends.firestore doesn't require "count_mode" options, since emulator supports aggregation queries.

Multiple database support

By default gcloudc will use the default database from your GCP project. If you want to use multiple databases, you can do so by adding additional database configurations to your DATABASES setting. For example:

DATABASES = {
    "default": {
    'ENGINE': 'gcloudc.db.backends.datastore',
    'PROJECT': 'YOUR_GCP_PROJECT_NAME',
    'INDEXES_FILE': 'PATH_TO_A_FILE_FOR_SPECICAL_INDEXES',
    'DATABASE_ID': '(default)',
    },
    "other": {
    'ENGINE': 'gcloudc.db.backends.datastore',
    'PROJECT': 'YOUR_GCP_PROJECT_NAME',
    'INDEXES_FILE': 'PATH_TO_A_FILE_FOR_SPECICAL_INDEXES',
    'DATABASE_ID': 'my-other-database',
    }
}

Note that to refer to the default database explicitly you must use the string `(default)` inclusing the parenthesis or just omit the option. See [GCP documentation](https://cloud.google.com/datastore/docs/manage-databases) for more information on how to create multiple databases in a single project.

Automatic Cloud Datastore Emulator startup

gcloudc provides overrides for the runserver and test commands which start and stop a Cloud Datastore Emulator instance. To enable this functionality add gcloudc.commands at the beginning of your INSTALLED_APPS setting.