Amazon Neptune JDBC connectivity - Amazon Neptune

Amazon Neptune JDBC connectivity

Amazon Neptune has released an open-source JDBC driver that supports openCypher, Gremlin, SQL-Gremlin, and SPARQL queries. JDBC connectivity makes it easy to connect to Neptune with business intelligence (BI) tools such as Tableau. There is no additional cost to using the JDBC driver with Neptune — you still pay only for the Neptune resources that are consumed.

The driver is compatible with JDBC 4.2, and requires at least Java 8. See the JDBC API documentation for information about how to use a JDBC driver.

The GitHub project, where you can file issues and open feature requests, contains detailed documentation for the driver:

Getting started with the Neptune JDBC driver

To use the Neptune JDBC driver to connect to a Neptune instance, either the JDBC driver must be deployed on an Amazon EC2 instance in the same VPC as your Neptune DB cluster, or the instance must be available through an SSH tunnel or load balancer. An SSH tunnel can be set up in the driver internally, or it can be set up externally.

You can download the driver here. The driver comes packaged as a single JAR file with a name like neptune-jdbc-1.0.0-all.jar. To use it, place the JAR file in the classpath of your application. Or, if your application uses Maven or Gradle, you can use the appropriate Maven or Gradle commands to install the driver from the JAR.

The driver needs a JDBC connection URL to connect with Neptune, in a form like this:

jdbc:neptune:(connection type)://(host);property=value;property=value;...;property=value

The sections for each query language in the GitHub project describe the properties that you can set in the JDBC connection URL for that query language.

If the JAR file is in your application's classpath, no other configuration is necessary. You can connect the driver using the JDBC DriverManager interface and a Neptune connection string. For example, if your Neptune DB cluster is accessible through the endpoint on port 8182, you would be able to connect with openCypher like this:

import java.sql.Connection; import java.sql.DriverManager; import java.sql.Statement; void example() { String url = "jdbc:neptune:opencypher://bolt://neptune-example:8182"; Connection connection = DriverManager.getConnection(url); Statement statement = connection.createStatement(); connection.close(); }

The documentation sections in the GitHub project for each query language describe how to construct the connection string when using that query language.

Using Tableau with the Neptune JDBC driver

To use Tableau with the Neptune JDBC driver, start by downloading and installing the most recent version of Tableau Desktop. Download the JAR file for the Neptune JDBC driver, and also the Neptune Tableau connector file (a .taco file).

To connect to Tableau for Neptune on a Mac
  1. Place the Neptune JDBC driver JAR file in the /Users/(your user name)/Library/Tableau/Drivers folder.

  2. Place the Neptune Tableau connector .taco file in the /Users/(your user name)/Documents/My Tableau Repository/Connectors folder.

  3. If you have IAM authentication enabled, set up the environment for it. Note that environment variables set in .zprofile/, .zshenv/, .bash_profile, and so forth, will not work. The environment variables must be set so that they can be loaded by a GUI application.

    One way to set your credentials is by placing your access key and secret key in the /Users/(your user name)/.aws/credentials file.

    An easy way to set the service region is to open a terminal and enter the following command, using your application's region (for example, us-east-1):

    launchctl setenv SERVICE_REGION region name

    There are other ways to set environment variables that persist after a restart, but whatever technique you use must set variables that are accessible to a GUI application.

  4. To get environment variables to load into a GUI on the Mac, enter this command on a terminal:

To connect to Tableau for Neptune on a Windows machine
  1. Place the Neptune JDBC driver JAR file in the C:\Program Files\Tableau\Drivers folder.

  2. Place the Neptune Tableau connector .taco file in the C:\Users\(your user name)\Documents\My Tableau Repository\Connectors folder.

  3. If you have IAM authentication enabled, set up the environment for it.

    This can be as simple as setting user ACCESS_KEY, SECRET_KEY, and SERVICE_REGION environment variables.

With Tableau open, select More on the left side of the window. If the Tableau connector file is properly located, you can select Amazon Neptune by AWS in the list that appears:

Choosing SQL in Tableau

You should not have to edit the port, or add any connection options. Enter your Neptune endpoint and set your IAM and SSL configuration (you must enable SSL if you are using IAM).

When you select Sign In, it may take more than 30 seconds to connect if your graph is large. Tableau is collecting vertex and edge tables and join vertices on edges, as well as creating visualizations.

Troubleshooting a JDBC driver connection

If the driver fails to connect to the server, use the isValid function of the JDBC Connection object to check whether the connection is valid. If the function returns false, meaning that the connection is invalid, check that the endpoint being connected to is correct and that you are in the VPC of your Neptune DB cluster or that you have a valid SSH tunnel to the cluster.

If you get a No suitable driver found for (connection string) response from the DriverManager.getConnection call, there is likely an issue at the beginning of your connection string. Make sure that your connection string starts like this:


To gather more information about the connection, you can add a LogLevel to your connection string like this:

jdbc:neptune:opencypher://(JDBC URL):(port);logLevel=trace

Alternatively, you can add properties.put("logLevel", "trace") in your input properties to log trace information.