CockroachDB supports the PostgreSQL wire protocol, so most available PostgreSQL client drivers and ORMs should work with CockroachDB. Choose a language for supported clients and installation steps.
Applications may encounter incompatibilities when using advanced or obscure features of a driver or ORM with beta-level support. If you encounter problems, please open an issue with details to help us make progress toward full support.
Drivers
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 "Hello World" example app, see Build a Python App with CockroachDB and psycopg2.
ORMs
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
You can substitute psycopg2 for other alternatives that include the psycopg python package.
For other ways to install SQLAlchemy, see the official documentation.
For a simple but complete "Hello World" example app, see Build a Python App with CockroachDB and SQLAlchemy.
Django
Support level: Full
CockroachDB supports Django versions 2.2 and 3.0.
To install Django:
$ python -m pip install django==3.0.*
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:
$ python -m pip install django-cockroachdb==3.0.*
The major version of django-cockroachdb
must correspond to the major version of django
. The minor release numbers do not need to match.
For a simple but complete "Hello World" example app, see Build a Python App with CockroachDB and Django.
PonyORM
Support level: Full
To install PonyORM:
$ python -m pip install pony
For a simple but complete "Hello World" example app, see Build a Python App with CockroachDB and PonyORM.
peewee
Support level: Full
To install peewee:
$ python -m pip install peewee
For instructions on using peewee with CockroachDB, see the CockroachDatabase peewee extension documentation.
We recommend using Java versions 8+ with CockroachDB.
Drivers
JDBC
Support level: Full
Download and set up the Java JDBC driver as described in the official documentation. We recommend using the latest PostgreSQL JDBC 42.2.x driver.
For a simple but complete "Hello World" example app, see Build a Java App with CockroachDB and JDBC.
ORMs
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:5.4.19.Final'
implementation 'org.postgresql:postgresql:42.2.14'
If you are using Maven, add the following to your <dependencies>
:
<dependency>
<groupId>org.hibernate</groupId>
<artifactId>hibernate-core</artifactId>
<version>5.4.19.Final</version>
</dependency>
<dependency>
<groupId>org.postgresql</groupId>
<artifactId>postgresql</artifactId>
</dependency>
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 org.hibernate.dialect.CockroachDB192Dialect
corresponds to CockroachDB v19.2.
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.
For a simple but complete "Hello World" example app, see Build a Java App with CockroachDB and Hibernate.
jOOQ
Support level: Full
You can use Gradle or Maven to get all dependencies for your application, including jOOQ.
For a simple but complete "Hello World" example app that uses Maven for dependency management, see Build a Java App with CockroachDB and jOOQ.
Drivers
pq
Support level: Full
To install the Go pq driver:
$ go get -u github.com/lib/pq
For a simple but complete "Hello World" example app, see Build a Go App with CockroachDB and the Go pq Driver.
ORMs
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 "Hello World" example app, see Build a Go App with CockroachDB and GORM.
Drivers
pg
Support level: Beta
To install the Ruby pg driver:
$ gem install pg
For a simple but complete "Hello World" example app, see Build a Ruby App with CockroachDB and the Ruby pg Driver.
ORMs
ActiveRecord
Support level: Beta
To install ActiveRecord, 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
The exact command above will vary depending on the desired version of ActiveRecord. Specifically, version 4.2.x of ActiveRecord requires version 0.1.x of the adapter; version 5.1.x of ActiveRecord requires version 0.2.x of the adapter; version 5.2.x of ActiveRecord requires version 5.2.x of the adapter.
For a simple but complete "Hello World" example app, see Build a Ruby App with CockroachDB and ActiveRecord.
Drivers
pg
Support level: Beta
To install the Node.js pg driver:
$ npm install pg
Some apps might also requires async
:
$ npm install async
For a simple but complete "Hello World" example app, see Build a Node.js App with CockroachDB and the Node.js pg Driver.
ORMs
Sequelize
Support level: Beta
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 "Hello World" example app, see Build a Node.js App with CockroachDB and Sequelize.
Drivers
libpq
Support level: Beta
Install the C libpq driver as described in the official documentation.
Drivers
libpqxx
Support level: Beta
Install the C++ libpqxx driver as described in the official documentation.
If you are running macOS, you need to install version 4.0.1 or higher of the libpqxx driver.
For a simple but complete "Hello World" example app, see Build a C++ App with CockroachDB and libpqxx.
Drivers
Npgsql
Support level: Beta
Create a .NET project:
$ dotnet new console -o cockroachdb-test-app
$ cd cockroachdb-test-app
The
dotnet
command creates a new app of typeconsole
. The-o
parameter creates a directory namedcockroachdb-test-app
where your app will be stored and populates it with the required files. Thecd cockroachdb-test-app
command puts you into the newly created app directory.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 "Hello World" example app, see Build a C# App with CockroachDB and the .NET Npgsql Driver.
Drivers
leiningen
Support level: Beta
Install the Clojure lein
utility as described in its official documentation.
For a simple but complete "Hello World" example app, see Build a Closure App with CockroachDB and java.jdbc.
Drivers
php-pgsql
Support level: Beta
Install the php-pgsql driver as described in the official documentation.
For a simple but complete "Hello World" example app, see Build a PHP App with CockroachDB and the PHP pgsql Driver.
Drivers
postgres
Support level: Beta
Install the Rust Postgres driver as described in the official documentation.
For a simple but complete "Hello World" example app, see Build a Rust App with CockroachDB and the Rust Postgres Driver.
ORMs
TypeORM
Support level: Beta
Install TypeORM as described in the official documentation.