CockroachDB backend for Django

Prerequisites

You must install either:

psycopg2, which has some prerequisites of its own.

psycopg2-binary

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.0.x:

pip install django-cockroachdb==3.0.*

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' : 'root' , 'PASSWORD' : '' , 'HOST' : 'localhost' , 'PORT' : '26257' , # If connecting with SSL, remove the PASSWORD entry above and include # the section below, replacing the file paths as appropriate. 'OPTIONS' : { 'sslmode' : 'require' , 'sslrootcert' : '/certs/ca.crt' , 'sslcert' : '/certs/client.myprojectuser.crt' , 'sslkey' : '/certs/client.myprojectuser.key' , }, }, }

Notes on Django fields

CharField 's max_length is ignored. It uses the same storage as TextField so CharField is introspected by inspectdb as TextField . 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

├── columns: id:1 question_id:4 choice_text:2 votes:3

├── stats: [rows=1]

├── cost: 1.1

├── key: (1)

├── fd: (1)-->(2-4)

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

Known issues and limitations (as of CockroachDB 20.1.4)

Additional issues and limitations in CockroachDB 19.2.x (as of 19.2.9)