Install a Driver or ORM Framework

JavaScript Drivers

pg

Support level: Full

To install the Node.js pg driver:

$ npm install pg

For a simple but complete example app, see Build a Node.js App with CockroachDB and the Node.js pg Driver.

JavaScript/TypeScript ORM frameworks

Sequelize

Support level: Full

To install Sequelize and a CockroachDB Node.js package that accounts for some minor differences between CockroachDB and PostgreSQL:

$ npm install sequelize sequelize-cockroachdb

For a simple but complete example app, see Build a Node.js App with CockroachDB and Sequelize.

Knex.js

Support level: Full

Install Knex.js as described in the official documentation.

For a simple but complete example app, see Build a Simple CRUD Node.js App with CockroachDB and Knex.js.

TypeORM

Support level: Full

Install TypeORM as described in the official documentation.

For a simple but complete example app, see Build a TypeScript App with CockroachDB and TypeORM.

Prisma

Support level: Full

To install the Prisma ORM:

$ npm install prisma

For a simple but complete example app, see Build a Simple CRUD Node.js App with CockroachDB and Prisma.

Python Drivers

psycopg3

Support level: Full

To install the Python psycopg3 driver:

$ pip3 install "psycopg[binary]"

For other ways to install psycopg3, see the official documentation.

For a simple but complete example app, see Build a Python App with CockroachDB and psycopg3.

psycopg2

Support level: Full

To install the Python psycopg2 driver:

$ pip install psycopg2

For other ways to install psycopg2, see the official documentation.

For a simple but complete example app, see Build a Python App with CockroachDB and psycopg2.

Python ORM frameworks

SQLAlchemy

Support level: Full

To install SQLAlchemy and a CockroachDB Python package that accounts for some differences between CockroachDB and PostgreSQL:

$ pip install sqlalchemy sqlalchemy-cockroachdb psycopg2

For other ways to install SQLAlchemy, see the official documentation.

For a simple but complete example app, see Build a Python App with CockroachDB and SQLAlchemy.

Django

Support level: Full

CockroachDB supports Django versions 3.1+.

To install Django:

$ pip install django==3.1.*

Before installing the CockroachDB backend for Django, you must install one of the following psycopg2 prerequisites:

• psycopg2, which has some prerequisites of its own. This package is recommended for production environments.

• psycopg2-binary. This package is recommended for development and testing.

After you install the psycopg2 prerequisite, you can install the CockroachDB Django backend:

$ pip install django-cockroachdb==3.1.*

For a simple but complete example app, see Build a Python App with CockroachDB and Django.

peewee

Support level: Full

To install peewee:

$ pip install peewee

For instructions on using peewee with CockroachDB, see the CockroachDatabase peewee extension documentation.

Go Drivers

pgx

Support level: Full

To install the Go pgx driver:

$ go get -u github.com/jackc/pgx

For a simple but complete example app, see Build a Go App with CockroachDB and the Go pgx Driver.

pq

Support level: Full

To install the Go pq driver:

$ go get -u github.com/lib/pq

For a simple but complete example app, see Build a Go App with CockroachDB and the Go pq Driver.

Go ORM frameworks

GORM

Support level: Full

To install GORM:

$ go get -u github.com/lib/pq # dependency

$ go get -u github.com/jinzhu/gorm

For a simple but complete example app, see Build a Go App with CockroachDB and GORM.

CockroachDB supports TLS 1.2 and 1.3, and uses 1.3 by default.

A bug in the TLS 1.3 implementation in Java 11 versions lower than 11.0.7 and Java 13 versions lower than 13.0.3 makes the versions incompatible with CockroachDB.

If an incompatible version is used, the client may throw the following exception:

javax.net.ssl.SSLHandshakeException: extension (5) should not be presented in certificate_request

For applications running Java 11 or 13, make sure that you have version 11.0.7 or higher, or 13.0.3 or higher.

If you cannot upgrade to a version higher than 11.0.7 or 13.0.3, you must configure the application to use TLS 1.2. For example, when starting your app, use: $ java -Djdk.tls.client.protocols=TLSv1.2 appName

Java Drivers

JDBC

Support level: Full

Download and set up the latest Java JDBC driver as described in the official documentation.

For a simple but complete example app, see Build a Java App with CockroachDB and JDBC.

Java ORM frameworks

Hibernate

Support level: Full

You can use Gradle or Maven to get all dependencies for your application, including Hibernate. Only Hibernate versions 5.4.19 and later support the Hibernate CockroachDB dialect.

If you are using Gradle, add the following to your dependencies:

implementation 'org.hibernate:hibernate-core:{version}.Final'
implementation 'org.postgresql:postgresql:{version}'

Where {version} is the latest stable version.

For a simple but complete example app that uses Gradle for dependency management, see Build a Java App with CockroachDB and Hibernate.

If you are using Maven, add the following to your <dependencies>:

<dependency>
    <groupId>org.hibernate</groupId>
    <artifactId>hibernate-core</artifactId>
    <version>{version}.Final</version>
</dependency>
<dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>postgresql</artifactId>
</dependency>

Where {version} is the latest stable version.

For a complete example app that uses Maven for dependency management, see Build a Spring App with CockroachDB and Spring Data JPA (Hibernate).

You will also need to specify the CockroachDB dialect in your Hibernate configuration file.

Versions of the Hibernate CockroachDB dialect correspond to the version of CockroachDB installed on your machine. For example, org.hibernate.dialect.CockroachDB201Dialect corresponds to CockroachDB v20.1 and later, and org.hibernate.dialect.CockroachDB192Dialect corresponds to CockroachDB v19.2 and later.

All dialect versions are forward-compatible (e.g., CockroachDB v20.1 is compatible with CockroachDB192Dialect), as long as your application is not affected by any backward-incompatible changes listed in your CockroachDB version's release notes. In the event of a CockroachDB version upgrade, using a previous version of the CockroachDB dialect will not break an application, but, to enable all features available in your version of CockroachDB, we recommend keeping the dialect version in sync with the installed version of CockroachDB.

Not all versions of CockroachDB have a corresponding dialect yet. Use the dialect number that is closest to your installed version of CockroachDB. For example, use CockroachDB201Dialect when using CockroachDB v21.1 and later.

jOOQ

Support level: Full

You can use Gradle or Maven to get all dependencies for your application, including jOOQ.

For a simple but complete example app that uses Maven for dependency management, see Build a Java App with CockroachDB and jOOQ.

Ruby Drivers

pg

Support level: Full

To install the Ruby pg driver:

$ gem install pg

For a simple but complete example app, see Build a Ruby App with CockroachDB and the Ruby pg Driver.

Ruby ORM frameworks

Active Record

Support level: Full

To install Active Record, the pg driver, and a CockroachDB Ruby package that accounts for some minor differences between CockroachDB and PostgreSQL:

$ gem install activerecord pg activerecord-cockroachdb-adapter

For a simple but complete example app, see Build a Ruby App with CockroachDB and Active Record.

C Drivers

libpq

Support level: Partial

Install the C libpq driver as described in the official documentation.

C# Drivers

Npgsql

Support level: Partial

1. Create a .NET project:

   $ dotnet new console -o cockroachdb-test-app
   

   $ cd cockroachdb-test-app
   

   The dotnet command creates a new app of type console. The -o parameter creates a directory named cockroachdb-test-app where your app will be stored and populates it with the required files. The cd cockroachdb-test-app command puts you into the newly created app directory.

2. Install the latest version of the Npgsql driver into the .NET project using the built-in nuget package manager:

   $ dotnet add package Npgsql
   

For a simple but complete example app, see Build a C# App with CockroachDB and the .NET Npgsql Driver.

Rust Drivers

rust-postgres

Support level: Partial

Install the Rust-Postgres driver as described in the official documentation.

For a simple but complete example app, see Build a Rust App with CockroachDB and the Rust-Postgres Driver.