django-google-spanner 2.2.1b4

Mac/Linux

pip install virtualenv
virtualenv <your-env>
source <your-env>/bin/activate
<your-env>/bin/pip install python-spanner-django
<your-env>/bin/pip install google-cloud-spanner

Windows

pip install virtualenv
virtualenv <your-env>
<your-env>\Scripts\activate
<your-env>\Scripts\pip.exe install python-spanner-django
<your-env>\Scripts\pip.exe install google-cloud-spanner

Supported versions

At the moment, this library only supports Django 2.2. It also requires Python version 3.6 or later.

This package follows a common versioning convention for Django plugins: the major and minor version components of this package should match the installed version of Django. That is, django-google-spanner~=2.2 works with Django~=2.2.

Installing the package

To install from PyPI:

pip3 install django-google-spanner

To install from source:

git clone git@github.com:googleapis/python-spanner-django.git
cd python-spanner-django
pip3 install -e .

Creating a Cloud Spanner instance and database

If you don’t already have a Cloud Spanner database, or want to start from scratch for a new Django application, you can create a new instance and database using the Google Cloud SDK:

gcloud spanner instances create $INSTANCE --config=regional-us-central1 --description="New Django Instance" --nodes=1
gcloud spanner databases create $DB --instance $INSTANCE

Configuring settings.py

This package provides a Django application named django_spanner. To use the Cloud Spanner database backend, the application needs to installed and configured:

• Add django_spanner as the first entry in INSTALLED_APPS:

  INSTALLED_APPS = [
      'django_spanner',
      ...
  ]

• Edit the DATABASES setting to point to an existing Cloud Spanner database:

  DATABASES = {
      'default': {
          'ENGINE': 'django_spanner',
          'PROJECT': '$PROJECT',
          'INSTANCE': '$INSTANCE',
          'NAME': '$DATABASE',
      }
  }

Set credentials and project environment variables

You’ll need to download a service account JSON key file and point to it using an environment variable:

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/keyfile.json
export GOOGLE_CLOUD_PROJECT=gcloud_project

Apply the migrations

Please run:

$ python3 manage.py migrate

and that’ll take a while to run. After this you should be able to see the tables and indices created in your Cloud Spanner console.

Now run your server

After those migrations are completed, that will be all. Please continue on with the guides.

Create an Django admin user

First you’ll need to create a user who can login to the admin site. Run the following command:

$ python3 manage.py createsuperuser

which will then produce a prompt which will allow you to create your super user

Username: admin
Email address: admin@example.com
Password: **********
Password (again): **********
Superuser created successfully.

Login as admin

Let’s run the server

python3 manage.py runserver

Then visit http://127.0.0.1:8000/admin/

Create and register your first model

Please follow the guides in https://docs.djangoproject.com/en/2.2/intro/tutorial02/#creating-models to create and register the model to the Django’s automatically-generated admin site.

Overall design

Internals

Executing a query

Here is an example of how to add a row for Model Author, save it and later query it using Django

>>> author_kent = Author( first_name="Arthur", last_name="Kent", rating=Decimal("4.1"),)
>>> author_kent.save()
>>> qs1 = Author.objects.all().values("first_name", "last_name")