Skip to main content

Django backend for CockroachDB

Project description

CockroachDB backend for Django

Prerequisites

You must install either:

The binary package is a practical choice for development and testing but in production it is advised to use the package built from sources.

Install and usage

Use the version of django-cockroachdb that corresponds to your version of Django. For example, to get the latest compatible release for Django 3.2.x:

pip install django-cockroachdb==3.2.*

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

Configure the Django DATABASES setting similar to this:

DATABASES = {
    'default': {
        'ENGINE': 'django_cockroachdb',
        'NAME': 'django',
        'USER': 'myprojectuser',
        'PASSWORD': '',
        'HOST': 'localhost',
        'PORT': '26257',
        # If connecting with SSL, include the section below, replacing the
        # file paths as appropriate.
        'OPTIONS': {
            'sslmode': 'verify-full',
            'sslrootcert': '/certs/ca.crt',
            # Either sslcert and sslkey (below) or PASSWORD (above) is
            # required.
            'sslcert': '/certs/client.myprojectuser.crt',
            'sslkey': '/certs/client.myprojectuser.key',
        },
    },
}

If using Kerberos authentication, you can specify a custom service name in 'OPTIONS' using the key 'krbsrvname'.

Notes on Django fields

  • IntegerField uses the same storage as BigIntegerField so IntegerField is introspected by inspectdb as BigIntegerField.

  • AutoField and BigAutoField are both stored as integer (64-bit) with DEFAULT unique_rowid().

Notes on Django QuerySets

  • QuerySet.explain() accepts verbose, types, opt, vec, and distsql options which correspond to CockroachDB's parameters. For example:

    >>> Choice.objects.explain(opt=True, verbose=True)
    'scan polls_choice\n ├── columns: id:1 question_id:4 choice_text:2 votes:3\n ├── stats: [rows=1]\n ├── cost: 1.1\n ├── key: (1)\n ├── fd: (1)-->(2-4)\n └── prune: (1-4)'
    

FAQ

Why do I get the error psycopg2.errors.InvalidName: no database specified?

You may need to create the database. You can use cockroach sql --insecure on the command line to get a SQL prompt.

GIS support

To use django.contrib.gis with CockroachDB, use 'ENGINE': 'django_cockroachdb_gis' in Django's DATABASES setting.

Disabling CockroachDB telemetry

By default, CockroachDB 21.1 and later will send the version of Django you are using back to Cockroach Labs. To disable this, set DISABLE_COCKROACHDB_TELEMETRY = True in your Django settings.

Known issues and limitations (as of CockroachDB 21.1.0)

Known issues and limitations in CockroachDB 20.2.x and earlier

  • Changing a column's type isn't supported.

  • [Timezones after 2038 use incorrect DST settings](https://github.com/cockr oachdb/django-cockroachdb/issues/124).

  • The SHA224 and SHA384 database functions aren't supported.

  • The BoundingCircle, LineLocatePoint, and MemSize GIS database functions aren't supported.

  • You can't use the libgeos_c.so bundled with CockroachDB. If you try this Django setting:

    `GEOS_LIBRARY_PATH = '/usr/local/lib/cockroach/libgeos_c.so'`
    

    It will fail with OSError: libgeos.so.3.8.1: cannot open shared object file: No such file or directory.

Project details


Download files

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

Source Distribution

django-cockroachdb-3.2.1.tar.gz (20.4 kB view hashes)

Uploaded Source

Built Distribution

django_cockroachdb-3.2.1-py3-none-any.whl (26.3 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page