Skip to main content
Join the official 2020 Python Developers SurveyStart the survey!

Bridge to enable using Django with Spanner.

Project description

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


To use this library you’ll need a Google Cloud Platform project with the Cloud Spanner API enabled. See the Cloud Spanner Python client docs for details.

Use the version of python-spanner-django that corresponds to your version of Django. For example, python-spanner-django 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 python-spanner-django. Use the latest minor release of each.

To install from PyPI:

pip3 install django-google-spanner

To install from source:

git clone
cd python-spanner-django
pip3 install -e .


After installattion, you’ll need to edit your Django file:

  • Add django_spanner as the very first entry in the INSTALLED_APPS setting

  • Edit the DATABASES setting to point to an EXISTING database


    'default': {
        'ENGINE': 'spanner_django',
        '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>',


For example:

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


Transaction management isn’t supported

python-spanner-django always works in autocommit mode, which is Django’s default behavior even for backends that support manual transaction management. Transactions cannot be controlled manually with calls like django.db.transaction.atomic().

AutoField generates random IDs

Spanner doesn’t have support for auto-generating primary key values. Therefore, python-spanner-django monkey-patches AutoField to generate a random UUID4. It generates a default using Field’s default option which means AutoFields will have a value when a model instance is created. For example:

>>> ExampleModel()

To avoid hotspotting, these IDs are not monotonically increasing. This means that sorting models by ID isn’t guaranteed to return them in the order in which they were created.

ForeignKey constraints aren’t created

Spanner doesn’t support ON DELETE CASCADE when creating foreign-key constraints so python-spanner-django doesn’t support foreign key constraints.

Check constraints aren’t supported

Spanner doesn’t support CHECK constraints so one isn’t created for PositiveIntegerField and CheckConstraint can’t be used.

DecimalField isn’t supported

Spanner doesn’t support a NUMERIC data type that allows storing high precision decimal values without the possibility of data loss.

Variance and StdDev database functions aren’t supported

Spanner doesn’t support these functions.

Meta.order_with_respect_to model option isn’t supported

This feature uses a column name that starts with an underscore (_order) which Spanner doesn’t allow.

Random QuerySet ordering isn’t supported

Spanner doesn’t support it. For example:

>>> ExampleModel.objects.order_by('?')
django.db.utils.ProgrammingError: 400 Function not found: RANDOM ... FROM
example_model ORDER BY RANDOM() ASC

Schema migrations

Spanner has some limitations on schema changes which you must respect:

  • Renaming tables and columns isn’t supported.
  • A column’s type can’t be changed.
  • A table’s primary key can’t be altered.
  • Migrations aren’t atomic since python-spanner-django doesn’t support transactions.

DurationField arithmetic doesn’t work with DateField values (#253)

Spanner requires using different functions for arithmetic depending on the column type:

  • TIMESTAMP columns (DateTimeField) require TIMESTAMP_ADD or TIMESTAMP_SUB
  • DATE columns (DateField) require DATE_ADD or DATE_SUB

Django doesn’t provide a way to determine which database function to use. DatabaseOperations.combine_duration_expression() arbitrary uses TIMESTAMP_ADD and TIMESTAMP_SUB. Therefore, if you use a DateField in a DurationField expression, you’ll see an error like: “No matching signature for function TIMESTAMP_ADD for argument types: DATE, INTERVAL INT64 DATE_TIME_PART.”

Computations that yield FLOAT64 values can’t be assigned to INT64 columns

Spanner doesn’t support this.

For example, if integer is IntegerField:

>>> ExampleModel.objects.update(integer=F('integer') / 2)
django.db.utils.ProgrammingError: 400 Value of type FLOAT64 cannot be
assigned to integer, which has type INT64 [at 1:46]\nUPDATE
example_model SET integer = (example_model.integer /...

Addition with null values crash

For example:

>>> Book.objects.annotate(adjusted_rating=F('rating') + None)
google.api_core.exceptions.InvalidArgument: 400 Operands of + cannot be literal
NULL ...

How it works

Overall design


Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for django-google-spanner, version 2.2.0a1
Filename, size File type Python version Upload date Hashes
Filename, size django_google_spanner-2.2.0a1-py3-none-any.whl (74.6 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size django-google-spanner-2.2.0a1.tar.gz (60.2 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page