How to setup and use Cockroachdb in Django projects

Hey guys, welcome to the DevMaesters website. In this article, I am going to guide you through the steps of setting up CockroachDB in Django projects. 

Please make sure you have watched the previous videos on my CockroachDB database setup and usage guide and have read my previous article on How to create a free CockroachDB database on CockroachLabs .This will help you learn how to set up an account and create a free cluster containing a CockroachDB database on CockroachLabs.

Now, let's move on to the main part of the article. Integrating and using CockroachDB in Django projects is very easy and straightforward. By following the steps listed below, you will be able to accomplish this successfully and quickly.

Step 1: Installing required packages

Before you can use CockroachDB in Django projects, you need to download the following pip packages to help you use the CockroachDB connection string (if you followed the previous videos or article, you should already have this saved somewhere).

  • pysopg2-binary: This is a PostgreSQL database adapter for the Python programming language. Install it using the command below:
pip install psycopg2-binary
  • django-cockroachdb:  This provides the database engine for connecting to the CockroachDB database. Please use the version that corresponds to your project. You can read more here. Install it using the command below: 

pip install django-cockroachdb
  • python-dotenv: This package is optional, as it allows us to set up environment variables in our Django project. I'll be using it so I can specify the connection string as an environment variable. Go to this link to learn how to install and use the python-dotenv package to set up environment variables in Django: 
pip install python-dotenv
  • dj_database_url: This simple Django utility allows you to utilize the 12factor inspired DATABASE_URL environment variable to configure your Django application. Install using the command below:
pip install dj-database-url


Step 2: Import dj_database_url in your project's file

Add the following lines to your file:

import dotenv
import dj_database_url

If you followed the link in Step 1, you should already have the dotnev import, and you'll only need to add the dj_database_url import below it.


Step 3: Add the connection string to your .env 

Please note that when you create the CockroachDB cluster and obtain the connection string for the database, the sslmode is set to verify-full by default. To successfully use this connection string in Django, you would need to download a certificate and add it to your project. However, for the purpose of this article, I will use a different sslmode to avoid this requirement.

To use the alternative sslmode, simply modify the verify-full value in your connection string to require. An example connection string is provided below:

DATABASE_URL = "postgresql://"


Step 4: Update Database Configuration

Comment out the previous database connection and add the dj_database_url configuration as shown below:

#     'default': {
#         'ENGINE': 'django.db.backends.sqlite3',
#         'NAME': BASE_DIR / 'db.sqlite3',
#     }
# }

DATABASES = {'default': dj_database_url.config(default=os.environ['DATABASE_URL'], engine='django_cockroachdb')}

In the above code snippet, we are using the configuration string by accessing the DATABASE_URL key in our .env file.


Step 5: Migrate Your Database

Run the following commands to migrate your database:

python makemigrations


python migrate

Wait for the migration to complete successfully, and that's it! You now have a CockroachDB database connected to your project, and you can use it in production.


As always than you for reading and if you have any questions or run into any errors then feel free to leave a comment down in the description below.


Hello, my name is Abubakar Zakari. Am a budding fullstack developer from Nigeria who loves developing softwares and learning new frameworks and langauges.


Select image

No comment yet




Frontend Development |Backend Development |Full Website Development |Bootstrap Website upgrades | Website Debbugging | Website Hosting & deployment


Interested in hiring me or collaborating with me on a project, click on any of the links below to get my social media handle

Or contact me via Tel: (+234)-806-225-7480 | Email:
Privacy Policy

By using our website,
you agree that devmaesters can store cookies on your device and disclose information in accordance with our privacy policy.