Amazon Neptune JDBC connectivity
Amazon Neptune has released an open-source
JDBC driver
The driver is compatible with JDBC 4.2, and requires at least Java 8. See the
JDBC
API documentation
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 hereneptune-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
neptune-example.com
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.taco
file).
To connect to Tableau for Neptune on a Mac
Place the Neptune JDBC driver JAR file in the
/Users/
folder.(your user name)
/Library/Tableau/DriversPlace the Neptune Tableau connector
.taco
file in the/Users/
folder.(your user name)
/Documents/My Tableau Repository/Connectors-
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/
file.(your user name)
/.aws/credentialsAn 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.
-
To get environment variables to load into a GUI on the Mac, enter this command on a terminal:
/Applications/Tableau/Desktop/2021.1.app/Contents/MacOS/Tableau
To connect to Tableau for Neptune on a Windows machine
Place the Neptune JDBC driver JAR file in the
C:\Program Files\Tableau\Drivers
folder.Place the Neptune Tableau connector
.taco
file in theC:\Users\
folder.(your user name)
\Documents\My Tableau Repository\Connectors-
If you have IAM authentication enabled, set up the environment for it.
This can be as simple as setting user
ACCESS_KEY
,SECRET_KEY
, andSERVICE_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:
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
response from the (connection
string)
DriverManager.getConnection
call, there is likely an issue at the beginning of your connection string.
Make sure that your connection string starts like this:
jdbc:neptune:
opencypher
://...
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.