django-google-spanner 2.2.0a1

Format

DATABASES = {
    '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>',
        },
    },
}

Example

For example:

DATABASES = {
    '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()
>>> ExampleModel.pk
4229421414948291880

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 ...

Overall design

Internals