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¶
The Basic example for connecting to CrateDB and CrateDB Cloud using JDBC demonstrates CrateDB’s PostgreSQL wire protocol compatibility by exercising a basic example using both the vanilla pgJDBC Driver and the CrateDB JDBC Driver.
The sample application and the corresponding sample application documentation demonstrate the use of the driver on behalf of an example “guestbook” application, using Spring Data JDBC.
The article Build a data ingestion pipeline using Kafka, Flink, and CrateDB, and the accompanying repositories Apache Kafka, Apache Flink, and CrateDB and Flink example jobs for CrateDB.
Project information¶
Resources¶
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.