Configuration
Driver class name
The Neo4j JDBC Driver is org.neo4j.jdbc.Neo4jDriver
.
With modern Java tools, you should not need to touch this class directly, but there are some connection pools and front-ends that will ask you for this.
The class is public API.
We also provide org.neo4j.jdbc.Neo4jDataSource
as javax.sql.DataSource
.
Causal clustering and bookmarks
The Neo4j JDBC Driver uses bookmarks by default to provide causal consistency in all Neo4j deployments.
Bookmarks are managed on the driver level itself, not on the connections spawned by an instance of the driver, so all connections spawned by one instance will partake in the same causal chain of transactions.
Connections from different driver instances will not use the same set of bookmarks and there is no built-in machinery that would enable this.
If you want or need this, you can directly access the Neo4jDriver
type to retrieve the current set of known bookmarks and pass them to another driver instance.
Neo4j transactional metadata
Neo4j supports attaching metadata to transactions, see SHOW TRANSACTIONS
.
As there is no explicit transaction object in the JDBC specification, the Neo4j JDBC driver needs another mechanism to make these configurable.
The JDBC driver provides the extension interface Neo4jMetadataWriter
.
Our driver, the connection implementation, and all statement variants can be unwrapped accordingly.
The configuration is additive: metadata configured for a driver instance will be used for all connections spawned from that driver, connections can add further metadata, and statements can also add their own metadata.
Metadata added on a statement has precedence over connection metadata which in turn has precedence over driver metadata:
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;
import java.sql.Statement;
import java.util.Map;
import java.util.Properties;
import java.util.logging.Level;
import java.util.logging.Logger;
import org.neo4j.jdbc.Neo4jDriver;
import org.neo4j.jdbc.Neo4jMetadataWriter;
public final class TransactionMetadata {
private static final Logger LOGGER = Logger.getLogger(TransactionMetadata.class.getPackageName());
public static void main(String... args) throws SQLException {
var url = "jdbc:neo4j://localhost:7687";
var driver = (Neo4jDriver) DriverManager.getDriver(url);
driver.withMetadata(Map.of("md_from_driver", "v1", "will_be_overwritten", "irrelevant"));
var properties = new Properties();
properties.put("user", "neo4j");
properties.put("password", "verysecret");
try (
var con = driver.connect(url, properties)
.unwrap(Neo4jMetadataWriter.class)
.withMetadata(Map.of("md_from_connection", "v2", "will_be_overwritten", "xxx"))
.unwrap(Connection.class);
var statement = con.createStatement()
.unwrap(Neo4jMetadataWriter.class)
.withMetadata(Map.of("md_from_stmt", "v3", "will_be_overwritten", "v4"))
.unwrap(Statement.class)
) {
try (var result = statement.executeQuery("SHOW TRANSACTIONS YIELD metaData")) {
while (result.next()) {
var metaData = result.getObject("metaData", Map.class);
LOGGER.log(Level.INFO, "{0}", metaData);
}
}
}
}
}
The output will be similar to this:
Juli 17, 2024 1:18:16 PM org.neo4j.jdbc.docs.TransactionMetadata main
INFORMATION: {md_from_driver=v1, md_from_connection=v2, md_from_stmt=v3, will_be_overwritten=v4}
URL and connection properties
The canonical URL format for the Neo4j JDBC Driver is
jdbc:neo4j://<host>:<port>/<database>?param1=value1¶m2=value2
The database name and all query parameters are optional and can be omitted.
All configuration arguments can be passed either as query parameters or via a java.util.Properties
object.
The latter is sometimes defined by tooling for you.
With regard to authentication, we recommend to follow the JDBC specification, which discourages using any form of URL authentication.
All query parameters must be percent-encoded if they contain special characters, e.g. …?param1=space%20separated
.
The driver supports the following URI schemes, which tweak the security configuration:
|
The driver accepts the following configuration arguments, either as properties or as URL query parameters:
Name | Type | Meaning | Default |
---|---|---|---|
|
|
Timeout for connection acquisition in milliseconds |
|
|
|
User agent |
|
|
|
Flag that enables automatic translation from SQL-to-Cypher (requires a translator on the classpath) |
|
|
|
Flag that enables caching of translations. SQL translations are not "free": parsing of SQL costs a bit of time, and so does Cypher® rendering. In addition, we might up look up metadata to be able to project individual properties. If this takes too long, translations may be cached. |
|
|
|
Flag that allows you to use |
|
|
|
Optional flag, alternative to |
|
|
|
Optional configuration for fine-grained control over SSL configuration. Allowed values are |
|
|
|
The username (principal) to use for authentication. NOT RECOMMENDED as URL query parameter for security reasons. |
|
|
|
The password (credentials) to use for authentication. NOT RECOMMENDED as URL query parameter for security reasons. |
|
|
|
The realm to use for authentication. NOT RECOMMENDED as URL query parameter for security reasons. |
|
|
|
The authentication scheme to use. NOT RECOMMENDED as URL query parameter for security reasons. Currently supported values are:
|
|
|
|
Enables bookmark management for full causal cluster support. This is enabled by default and the recommended setting for all scenarios that use a connection pool. If you disable it, it will only be disabled for the specific connection. Other connections retrieved from the driver instance to the same or to other databases are not affected, and the individual connections will still manage their bookmarks. |
|
Getting a driver or a connection instance
This section likely only applies if you use the Neo4j JDBC Driver as part of application development in contrast to using it as part of front-end tool such as DBeaver, DataGrip or UI-based ETL tools. |
The easiest way to acquire a connection is directly through the java.sql.DriverManager
.
import java.sql.DriverManager;
import java.sql.SQLException;
import java.util.Properties;
class Configuration {
void obtainConnection() throws SQLException {
var url = "jdbc:neo4j://localhost:7687";
var username = "neo4j";
var password = "verysecret";
var connection = DriverManager.getConnection(url, username, password);
}
}
While our connection implementation is thread-safe, it allows only one concurrent transaction per connection (as dictated by the JDBC specification). For a multi-thread application, use a connection pool. There’s HikariCP, but usually application server and containers/frameworks bring their own. It’s safe to use any of them, as the Neo4j JDBC Driver does no internal pooling.
If you need access to an instance of the Neo4j driver itself, you can use the following approach:
import java.sql.DriverManager;
import java.sql.SQLException;
import java.util.Properties;
class Configuration {
void obtainDriverAndConnection() throws SQLException {
var url = "jdbc:neo4j://localhost:7687";
var driver = DriverManager.getDriver(url);
var properties = new Properties();
properties.put("username", "neo4j");
properties.put("password", "verysecret");
var connection = driver.connect(url, properties);
}
}
Securing your connection by using SSL
The Neo4j JDBC Driver supports the same SSL option of the common Java driver, with the same URL protocols, using +s
or +ssc
as additional indicators for the required level of security.
The same configuration can also be achieved with a URL query parameter or an entry in the properties passed to the DriverManager
or driver instance when asking for a connection.
As long as you don’t specify contradicting values, it’s fine to combine both approaches.
Understanding the SSL mode
The following list is ordered by ascending security:
-
disable
— (default), "I don’t care about security and don’t want to pay the overhead for encryption." -
require
— "I want my data to be encrypted, and I accept the overhead. I trust that the network will make sure I always connect to the server I want." (Server must support encryption, no hostname/CA validation is done. This saves the hassle of proper certificates and is only secure on private networks; it should not really be used over public networks.) -
verify-full
— "I want my data encrypted, and I accept the overhead. I want to be sure that I connect to a server I trust, and that it’s the one I specify."
The Neo4j JDBC Driver does not include revocation checks. |
The most secure option can also be enabled by setting ssl=true
either as query parameter or as property entry passed to the DriverManager
.
This option corresponds to neo4j+s
.
On the other hand, require
corresponds to neo4j+ssc
.
The additional enum allows us to possibly support additional modes in the future, such as letting the service decide about SSL, or being able to express a preference towards SSL without requiring it.
Neo4j servers can offer both plain Bolt connections and encrypted SSL connection, or just one of them. The fact that you can connect using neo4j+s does not mean that you cannot connect using just neo4j , or viceversa. This is dependent on the server setup. Neo4j Aura, Neo4j’s managed cloud service, only supports encrypted connections, so you must use +s , ssl=true , or sslMode=verify-full .
|
Valid URLs
The following URLs are all valid:
neo4j+s://xyz.databases.neo4j.io
-
Use full verification with the
xzy
instance at AuraDB neo4j://xyz.databases.neo4j.io?ssl=true
-
The same, but using the shorthand URL parameter
neo4j://xyz.databases.neo4j.io?sslMode=verfiy-full
-
The same, but using the explicit mode
neo4j+s://xyz.databases.neo4j.io?ssl=true&sslMode=verify-full
-
Not more secure, but does not fail on you
neo4j+ssc://this.is.a.trustworthy.instance.for.sure.com
-
Trust whatever certificate and hostname there is, but do use SSL
neo4j://my-testing-instance.local
-
Use a plain connection.
The driver only refuses contradicting configurations, such as:
-
+s
withssl=false
, orsslMode
set todisable
-
+ssc
withssl=false
, or anysslmode
not equal torequire
Basically, you cannot ask to use SSL and not use it at the same time. The driver offers several mechanism so that you can use a fixed URL with dynamic query parameters, or dynamic URLs, or whatever way of configuring you prefer in a programmatic way.
Using .dotenv files
When you create a Neo4j Aura instance, you will be asked to download a text-file named similar to Neo4j-9df57663-Created-2023-06-12.txt
.
This is essentially a .dotenv file containing the information required to connect to the database.
These files can be directly used via Neo4jDriver.fromEnv()
(see Getting a connection via environment variables).
This method exists in several overloads, which let you configure both filename and directory.
Additionally, the builder lets you configure options that are not contained in the files from Aura.