CrateDB legacy JDBC driver

Table of contents

Introduction

A JDBC driver for CrateDB, based on the PostgreSQL JDBC Driver. It can be used with CrateDB version 0.38.0 and newer.

This is a JDBC Type 4 driver, adhering to the JDBC 4.1 specification. It is written in pure Java, and communicates with the database using the PostgreSQL Wire Protocol.

JDBC is a standard Java API that provides common interfaces for accessing databases in Java.

Synopsis

Connect to CrateDB instance running on localhost.

import java.sql.Connection;
import java.sql.DriverManager;

Connection conn = DriverManager.getConnection("jdbc:crate://localhost:5432/");

Connect to CrateDB Cloud.

import java.sql.Connection;
import java.sql.DriverManager;
import java.util.Properties;

Properties connectionProps = new Properties();
connectionProps.put("user", "admin");
connectionProps.put("password", "<PASSWORD>");
connectionProps.put("tcpKeepAlive", true);

Connection conn = DriverManager.getConnection("jdbc:crate://example.aks1.westeurope.azure.cratedb.net:5432/?user=crate", connectionProps);

Details

Overview

For general purpose use, we recommend to use the official PostgreSQL JDBC Driver.

This JDBC driver is needed in certain scenarios like the one outlined at Apache Kafka, Apache Flink, and CrateDB. The background is that, when using the postgresql:// JDBC driver prefix, the Apache Flink JDBC Connector will implicitly select the corresponding dialect implementation for PostgreSQL.

In turn, this will employ a few behaviours that strictly expect a PostgreSQL server on the other end, so that some operations will fail on databases offering wire-compatibility with PostgreSQL, but do not provide certain features like the hstore or jsonb extensions. Also, tools like Dataiku need this driver to implement transaction commands like ROLLBACK as a no-op.

Differences

The driver is based upon a fork of the PostgreSQL JDBC Driver, see pgjdbc driver fork. On a high-level perspective, this list enumerates a few behavioral differences.

  • The CrateDB driver deserializes objects to a Map, the official one treats them as JSON.

  • A few metadata functions have been adjusted to better support CrateDB’s type system.

Read up on further details at the Internals section.

Documentation

For general help about JDBC, please consult the JDBC tutorial and the JDBC API documentation.

Examples

Project information

Contributions

The CrateDB legacy JDBC driver library is an open source project, and is managed on GitHub. Every kind of contribution, feedback, or patch, is much welcome. Create an issue or submit a patch if you think we should include a new feature, or to report or fix a bug.

Development

In order to setup a development environment on your workstation, please head over to the development sandbox documentation. When you see the software tests succeed, you should be ready to start hacking.

License

The project is licensed under the terms of the Apache 2.0 license, like CrateDB itself, see LICENSE.