Supported versions

The library supports Django 5.2 and Django 6.0. The minimum required Python version is 3.10.

pip3 install "django>=5.2,<6.1"

Installing the package

To install from PyPI:

pip3 install django-google-spanner

To install from source:

git clone git@github.com:googleapis/google-cloud-python.git
cd packages/django-google-spanner
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',
      }
  }

Configuring primary key generation

The Spanner Django engine by default uses random int64 values that are generated by the client as primary key values. This default is applied to all databases that are configured, including databases that use a different engine than Spanner. You can disable this behavior with the RANDOM_ID_GENERATION_ENABLED setting:

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

Transaction support in autocommit mode

Django supports transactions in autocommit mode by default. A transaction is automatically started if you define an atomic block.

To disable transactions in autocommit mode, set the flag ALLOW_TRANSACTIONS_IN_AUTO_COMMIT to False in your settings.py file.

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

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

Create a 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

Now, 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/5.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")

How to contribute

Contributions to this library are always welcome and highly encouraged.

See CONTRIBUTING for more information on how to get started.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms. See the Code of Conduct for more information.

DML RETURNING Behavior

Starting with Django 6.0 compatibility, can_return_columns_from_insert = True is enabled. Django will generate THEN RETURN clauses for insert statements that create model instances with database-generated defaults or GeneratedField columns.

If your application relies on the previous behavior (where returned columns were not queried automatically upon insert), you can disable it in your Django AppConfig:

from django.apps import AppConfig

class MyAppConfig(AppConfig):
    name = "myapp"

    def ready(self):
        from django_spanner.features import DatabaseFeatures

        DatabaseFeatures.can_return_columns_from_insert = False

Limitations

Spanner has certain limitations of its own. The full set of limitations is documented here. It is recommended that you go through that list.

Django spanner has a set of limitations as well, which you can find here.

Features from spanner that are not supported in Django-spanner are listed here.