Skip to content

Latest commit

 

History

History
412 lines (254 loc) · 13.5 KB

install-client-drivers.md

File metadata and controls

412 lines (254 loc) · 13.5 KB
title summary toc docs_area
Install a Driver or ORM Framework
CockroachDB supports both native drivers and the PostgreSQL wire protocol, so you can use most available PostgreSQL client drivers and ORM frameworks.
true
develop

CockroachDB supports both native drivers and the PostgreSQL wire protocol, so most available PostgreSQL client drivers and ORM frameworks should work with CockroachDB. Choose a language for supported clients, and follow the installation steps. After you install a client library, you can connect to the database.

{{site.data.alerts.callout_info}} Applications may encounter incompatibilities when using advanced or obscure features of a driver or ORM framework with beta-level support. If you encounter problems, please open an issue with details to help us make progress toward full support. {{site.data.alerts.end}}

JavaScript/TypeScript Python Go Java Ruby C C# (.NET) Rust

JavaScript Drivers

pg

Support level: Full

To install the Node.js pg driver:

{% include_cached copy-clipboard.html %}

$ 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:

{% include_cached copy-clipboard.html %}

$ 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:

{% include_cached copy-clipboard.html %}

$ npm install prisma

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

Python Drivers

psycopg2

Support level: Full

To install the Python psycopg2 driver:

{% include_cached copy-clipboard.html %}

$ 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:

{% include_cached copy-clipboard.html %}

$ pip install sqlalchemy sqlalchemy-cockroachdb psycopg2

{{site.data.alerts.callout_success}} You can substitute psycopg2 for other alternatives that include the psycopg python package. {{site.data.alerts.end}}

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:

{% include_cached copy-clipboard.html %}

$ 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:

{% include_cached copy-clipboard.html %}

$ pip install django-cockroachdb==3.1.*

{{site.data.alerts.callout_info}} The major version of django-cockroachdb must correspond to the major version of django. The minor release numbers do not need to match. {{site.data.alerts.end}}

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

PonyORM

Support level: Full

To install PonyORM:

{% include_cached copy-clipboard.html %}

$ pip install pony

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

peewee

Support level: Full

To install peewee:

{% include_cached copy-clipboard.html %}

$ 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:

{% include_cached copy-clipboard.html %}

$ 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:

{% include_cached copy-clipboard.html %}

$ 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:

{% include_cached copy-clipboard.html %}

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

{% include_cached copy-clipboard.html %}

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

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

{% include {{page.version.version}}/app/java-version-note.md %}

{% include {{page.version.version}}/app/java-tls-note.md %}

Java Drivers

JDBC

Support level: Full

Download and set up the Java JDBC driver as described in the official documentation. We recommend using the PostgreSQL JDBC 42.2.9 driver.

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:5.4.19.Final'
implementation 'org.postgresql:postgresql:42.2.9'

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>5.4.19.Final</version>
</dependency>
<dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>postgresql</artifactId>
</dependency>

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.

{% include {{page.version.version}}/app/hibernate-dialects-note.md %}

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:

{% include_cached copy-clipboard.html %}

$ 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:

{% include_cached copy-clipboard.html %}

$ gem install activerecord pg activerecord-cockroachdb-adapter

{{site.data.alerts.callout_info}} The exact command above will vary depending on the desired version of Active Record. Specifically, version 5.1.x of Active Record requires version 0.2.x of the adapter; version 5.2.x of Active Record requires version 5.2.x of the adapter; version 6.0.x of Active Record requires version 6.0.x of the adapter; version 7.0.x of Active Record requires version 7.0.x of the adapter. {{site.data.alerts.end}}

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

C Drivers

libpq

Support level: Beta

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

C# Drivers

Npgsql

Support level: Beta

  1. Create a .NET project:

    {% include_cached copy-clipboard.html %}

    $ dotnet new console -o cockroachdb-test-app

    {% include_cached copy-clipboard.html %}

    $ 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:

    {% include_cached copy-clipboard.html %}

    $ 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: Beta

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.

What's next?

You might also be interested in the following pages: