Legacy Neo4j JDBC driver

This is the JDBC driver for the graph database Neo4j (version 2.x). While Neo4j is a graph database, and JDBC is based on the relational paradigm, this driver provides a way to bridge this gap.

For the official Neo4j v2 driver, please see the original community JDBC driver that this project builds upon.

For Neo4j v3 (supports also REST API of Neo4j v2), please use the new JDBC driver.

Why a fork?

This project is a minimal fork mainly aiming for easy maintenance. It is build with Travis CI, is backwards compatible with Neo4j 2.0.x and define a single branch of development. It includes all the fixes that have been implemented in the official legacy driver, for ALL versions of Neo4j down to 2.0.x.

The dependency is available as:

    <dependency>
        <groupId>net.biville.florent</groupId>
        <artifactId>legacy-neo4j-jdbc</artifactId>
        <version>2.3.0</version>
    </dependency>

Legacy vs current Neo4j JDBC driver matrix

1. Choice matrix

Deployment type	Supported by legacy?	Supported by new?
Embedded 2.x	Y	N
Embedded 3.x	N	Planned
HTTP	Y	Y
Bolt	N	Y

Paradigm

The textual representation of declarative queries in the Cypher query language which returns tabular results make it possible to use the JDBC concepts and APIs.

The driver can be used in conjunction with

• a Neo4j Server

• a on disk Neo4j database

• an existing Neo4j GraphDatabaseService instance passed to the driver

• an temporary in-memory instance of Neo4j

Minimum Viable Snippet

// Make sure Neo4j Driver is registered
Class.forName("org.neo4j.jdbc.Driver");

// Connect
Connection con = DriverManager.getConnection("jdbc:neo4j://localhost:7474/");

// Querying
try(Statement stmt = con.createStatement())
{
    ResultSet rs = stmt.executeQuery("MATCH (n:User) RETURN n.name");
    while(rs.next())
    {
        System.out.println(rs.getString("n.name"));
    }
}

Maven dependency

The example features Neo4j v2.3.6, but it could be any version down to 2.0.x.

<project>

  [..]

  <dependencies>
    <dependency>
      <groupId>net.biville.florent</groupId>
      <artifactId>legacy-neo4j-jdbc</artifactId>
      <version>2.3.0</version>
    </dependency>
    <!-- For file and in-memory support, add these others as well -->
    <dependency>
      <groupId>org.neo4j</groupId>
      <artifactId>neo4j</artifactId>
      <version>2.3.6</version>
    </dependency>
    <dependency>
      <groupId>org.neo4j</groupId>
      <artifactId>neo4j-kernel</artifactId>
      <version>2.3.6</version>
      <type>test-jar</type>
    </dependency>
    <dependency><!-- only for Neo4j versions >= 2.2.x -->
      <groupId>org.neo4j</groupId>
      <artifactId>neo4j-io</artifactId>
      <version>2.3.6</version>
      <type>test-jar</type>
    </dependency>
  </dependencies>

Usage

• Add the JDBC driver jar file to your applications classpath

• Load the driver with the class org.neo4j.jdbc.Driver

• Execute queries using the Cypher graph query language

• Use the according JDBC-url (see below)

To debug the driver, add ?debug=true to the URL. This will log all calls to the driver to the Java Util Logging framework.

Server

• Install a Neo4j server, and start it with the REST API enabled.

• Connect with URLs on the form jdbc:neo4j://<host>:<port>/, e.g. jdbc:neo4j://localhost:7474/

Graph Database on disk

• create or use and existing graph database on disk

• Connect with URLs on the form jdbc:neo4j:file:/path/to/db, e.g. jdbc:neo4j:file:/home/user/neo/graph.db

In-Memory Graph Database

• Connect with URLs on the form jdbc:neo4j:mem or jdbc:neo4j:mem:name, e.g. jdbc:neo4j:mem:mydb

• The passed in name allows for a database that is reusable across connections

Existing Graph Database Instance

• Connect with URLs on the form jdbc:neo4j:instance:name, e.g. jdbc:neo4j:mem:mydb and put the GraphDatabaseService object instance under the same name into the properties provided to the driver

Server-Authentication

The driver supports authentication. You can provide the JDBC connection properties "user" and "password", and these will then be used to perform BASIC AUTH authentication while performing the REST API calls.

(optional) Database/Table-MetaData

This can be done by introducing type nodes in the graph, which are directly related to the root node by the relationship TYPE. Each type node has a property "type" with its name (i.e. "tablename), and HAS_PROPERTY relationships to nodes that represent the properties that the node can have (i.e. "columns"). For each instance of this type (i.e. "row") there is a relationship from the instance to the type node via the IS_A relationship. By using this structure the JDBC driver can mimic tables of a relational database.

MetaData-Setup

• Add as many TYPE nodes as you want

• For each type node, add as many HAS_PROPERTY nodes as you want

• For each property node, set property "name" and "type". "type" should be "String" for now

• Add as many instance nodes as you want, with the defined properties, and relate them to their type node with the IS_A relationship

Quirks modes

Many of the tools below issue SQL statements in order to browse tables. For these tools to work the driver detects whether it is running in any of those environments, and if so starts a "quirks mode", whereby those standard SQL statements are replaced on the fly with the Cypher equivalents.

Using with DbVisualizer

One of the first tests I did with the driver was to connect to Neo4j using the DbVisualizer tool (www.dbvis.com/).

Here is how you can try it out:

• Download and install DbVisualizer

• Add the JDBC driver jar as a Neo4j driver in the Driver Manager.

• Add a connection to your database

• Under "Connection properties", change "SQL Statements" as follows:

  • SELECT ALL: start n=node(0) match (n)-[:TYPE]->(type)<-[:IS_A]-(instance) return * .

  • SELECT COUNT: start n=node(0) match (n)-[:TYPE]->(type)<-[:IS_A]-(instance) return count(instance)

Now you should be able to browse the type nodes as tables and the nodes of those types as rows. Use the "SQL Commander" to issue arbitrary Cypher queries to the Neo4j server.

Using with LibreOffice

To use the driver with LibreOffice (should be similar with OpenOffice, not tested though), follow these steps:

• Add the driver jar to the classpath in the Java settings in LibreOffice

• Create a new Database and select JDBC.

• Enter the JDBC URL and set org.neo4j.jdbc.Driver as driver

• Optionally enter authentication settings

• Click Finish

Now you can browse the "tables" and the data, as well as create Queries that perform Cypher queries, and view the results.

Using with IntelliJ

To use the driver with IntelliJ 11, do as follows:

• Open up the Data Sources tab

• Click +, select the JDBC driver jar, and enter the JDBC settings for the connection

• Switch to the SQL Console, select Properties and go to the Text Mode tab. As "Parameter pattern", enter (\{[\w]*\}). This will allow you to replace Cypher parameters with values before executing a query

Now you can browse "tables" and execute Cypher queries from within IntelliJ.

Using with ODBC on Windows

To use the driver as an ODBC data source in Windows, do as follows:

• Download and install "ODBC-JDBC Gateway" from Easysoft: http://www.easysoft.com/products/data_access/odbc_jdbc_gateway/

• Set up an ODBC data source by following the guide provided with the above software

Now you can browse "tables" and execute Cypher queries from any ODBC-compliant tool.