Connect to a CrateDB cluster¶

This documentation section is about connecting your applications to CrateDB and CrateDB Cloud, using database drivers, and compatibility-adapters and -dialects.

Protocol Support¶

CrateDB supports both the HTTP protocol and the PostgreSQL wire protocol, which ensures that many clients that work with PostgreSQL, will also work with CrateDB. Through corresponding drivers, CrateDB is compatible with ODBC, JDBC, and other database API specifications.

While we generally recommend the PostgreSQL interface (PG) for maximum compatibility in PostgreSQL environments, the HTTP interface supports CrateDB bulk operations and CrateDB BLOBs, which are not supported by the PostgreSQL protocol.

The HTTP protocol can also be used to connect from environments where PostgreSQL-based communication is not applicable.

Configure¶

In order to connect to CrateDB, your application or driver needs to be configured with corresponding connection properties. Please note that different applications and drivers may obtain connection properties in different formats.

CrateDB and CrateDB Cloud

Connection properties

Host:: <cluster>.cratedb.net
Port:: 5432 (PostgreSQL) or
4200 (HTTP)
User:: <user>
Pass:: <password>

Connection-string examples

Native PostgreSQL, psql

postgresql://<user>:<password>@<cluster>.cratedb.net:5432/doc

JDBC: PostgreSQL pgJDBC

jdbc:postgresql://<user>:<password>@<cluster>.cratedb.net:5432/doc

JDBC: CrateDB JDBC, e.g. Apache Flink

jdbc:crate://<user>:<password>@<cluster>.cratedb.net:5432/doc

HTTP: Admin UI, CLI, CrateDB drivers

https://<user>:<password>@<cluster>.cratedb.net:4200/

SQLAlchemy

crate://<user>:<password>@<cluster>.cratedb.net:4200/?schema=doc&ssl=true

CrateDB on localhost

Connection properties

Host:: localhost
Port:: 5432 (PostgreSQL) or
4200 (HTTP)
User:: crate
Pass:: (empty)

Connection-string examples

Native PostgreSQL, psql

postgresql://crate@localhost:5432/doc

JDBC: PostgreSQL pgJDBC

jdbc:crate://crate@localhost:5432/doc

JDBC: CrateDB JDBC, e.g. Apache Flink

jdbc:crate://<user>:<password>@localhost:5432/doc

HTTP: Admin UI, CLI, CrateDB drivers

http://crate@localhost:4200/

SQLAlchemy

crate://crate@localhost:4200/?schema=doc

Tip

CrateDB’s fixed catalog name is crate, the default schema name is doc.
CrateDB does not implement the notion of a database, however tables can be created in different schemas.
When asked for a database name, specifying a schema name (any), or the fixed catalog name crate may be applicable.
If a database-/schema-name is omitted while connecting, the PostgreSQL drivers may default to the “username”.
The predefined superuser on an unconfigured CrateDB cluster is called crate, defined without a password.
For authenticating properly, please learn about the available authentication options.

Client Libraries¶

This section lists drivers and adapters for relevant programming languages, frameworks, and environments.

PostgreSQL¶

The drivers listed in this section all use the CrateDB PostgreSQL interface.

Driver/Adapter

Description

Info

PostgreSQL ODBC

The official PostgreSQL ODBC Driver. For connecting to CrateDB from any environment that supports it.

.NET

Npgsql

An open source ADO.NET Data Provider for PostgreSQL, for program written in C#, Visual Basic, and F#.

.NET

CrateDB Npgsql fork

This fork of the official driver was needed prior to CrateDB 4.2.

Golang

pgx

A pure Go driver and toolkit for PostgreSQL.

Java

PostgreSQL JDBC

The official PostgreSQL JDBC Driver. For connecting to CrateDB from any environment that supports it.

Java

CrateDB PgJDBC fork

For connecting to CrateDB with specialized type system support and other tweaks. Ignores the ROLLBACK statement and the hstore and jsonb extensions.

Node.js

node-postgres

A collection of Node.js modules for interfacing with a PostgreSQL database using JavaScript or TypeScript.

Has support for callbacks, promises, async/await, connection pooling, prepared statements, cursors, streaming results, C/C++ bindings, rich type parsing, and more.

PHP

PDO_PGSQL

For connecting to CrateDB from PHP, supporting its PDO interface.

PHP

AMPHP

For connecting to CrateDB using AMPHP, an Async PostgreSQL client for PHP. AMPHP is a collection of high-quality, event-driven libraries for PHP designed with fibers and concurrency in mind.