python-spanner-django

django-spanner

ORM plugin for using Cloud Spanner as a database for Django.

🚨THIS CODE IS STILL UNDER DEVELOPMENT🚨

Table of contents

• Installing it
• Using it
  • Format
  • Example
• Functional tests
• Django integration tests
  • django_test_suite.sh
    • Environment variables
    • Example run
  • Parallelization script
    • Environment variables
    • Example run
• Limitations
• How it works
  • Overall design
  • Internals

Installing it

Use the version of django-spanner that corresponds to your version of Django. For example, django-spanner 2.2.x works with Django 2.2.y. (This is the only supported version at this time.)

The minor release number of Django doesn't correspond to the minor release number of django-spanner. Use the latest minor release of each.

pip3 install --user .

Using it

After installing it, you'll need to edit your Django settings.py file and particularly the DATABASES section to point to an EXISTING database, of the format:

Format

DATABASES = {
    'default': {
        'ENGINE': 'django_spanner',
        'PROJECT': '<project_id>',
        'INSTANCE': '<instance_id>',
        'NAME': '<database_name>',
        # Only include this if you need to specify where to retrieve the
        # service account JSON for the credentials to connect to Cloud Spanner.
        'OPTIONS': {
            'credentials_uri': '<credentials_uri>',
        },
    },
}

Example

For example:

DATABASES = {
    'default': {
        'ENGINE': 'django_spanner',
        'PROJECT': 'appdev-soda-spanner-staging', # Or the GCP project-id
        'INSTANCE': 'django-dev1', # Or the Cloud Spanner instance
        'DATABASE': 'db1', # Or the Cloud Spanner database to use
    }
}

Functional tests

We have functional tests for individual components that can be run by

tox

Django integration tests

We run full integration tests with continuous integration on Google Cloud Build with Kokoro.

The tests to be run are specified in file django_test_apps.txt

There are 2 ways to run the tests:

django_test_suite.sh

This method requires an already existing Cloud Spanner instance. Expected environment variables:

Environment variables

Example run

GOOGLE_APPLICATION_CREDENTIALS=~/Downloads/creds.json \
PROJECT_ID=appdev-soda DJANGO_TEST_APPS="expressions i18n" \
SPANNER_TEST_INSTANCE=django-tests ./django_tests_suite.sh

Parallelization script

This method shards tests over multiple builds, and over available cores.

Environment variables

To run the tests locally, you'll need the following environment variables.

Example run

GOOGLE_APPLICATION_CREDENTIALS=~/Downloads/creds.json \
PROJECT_ID=appdev-soda DJANGO_TEST_APPS="expressions i18n" \
DJANGO_WORKER_COUNT=1 DJANGO_WORKER_INDEX=0SPANNER_TEST_INSTANCE=django-tests ./bin/parallelize_tests_linux

Limitations

How it works

Overall design

Internals

🚨THIS CODE IS STILL UNDER DEVELOPMENT🚨