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:

Listing 1. Configuring transactional 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&param2=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:

  • neo4j - No encryption.

  • neo4j+s - Enables encryption and only accepts SSL certificates from the server that are signed by a known Certificate Authority.

  • neo4j+ssc - Enables encryption and accepts self-signed certificates (which must be added to the certificate store).

bolt URI schemes are not supported.

The driver accepts the following configuration arguments, either as properties or as URL query parameters:

Table 1. Configuration arguments
Name Type Meaning Default

timeout

Integer

Timeout for connection acquisition in milliseconds

1000

agent

String

User agent

neo4j-jdbc

enableSQLTranslation

Boolean

Flag that enables automatic translation from SQL-to-Cypher (requires a translator on the classpath)

false

cacheSQLTranslations

Boolean

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.

false

rewritePlaceholders

Boolean

Flag that allows you to use ? as placeholder in Cypher statements (as required by JDBC). These will automatically be rewritten into $1, $2 … $n, starting at 1, so that the numbering matches the 1-based JDBC index.

true when enableSQLTranslation is false, false otherwise

ssl

Boolean

Optional flag, alternative to neo4j+s. It can be used for example to programmatically enable the full SSL chain.

null

sslMode

Enum<SSLMode>

Optional configuration for fine-grained control over SSL configuration. Allowed values are disable, require, verify-full. See <ssl_mode, Understanding the SSL mode>>.

null

user

String

The username (principal) to use for authentication. NOT RECOMMENDED as URL query parameter for security reasons.

neo4j

password

String

The password (credentials) to use for authentication. NOT RECOMMENDED as URL query parameter for security reasons.

password

authRealm

String

The realm to use for authentication. NOT RECOMMENDED as URL query parameter for security reasons.

null

authScheme

String

The authentication scheme to use. NOT RECOMMENDED as URL query parameter for security reasons. Currently supported values are:

  • basic (default) for basic authentication.

  • bearer for bearer authentication (SSO). password should be set to the bearer token; user and authRealm have no effect.

  • kerberos for kerberos authentication. Requires password to be set to the kerberos ticket; user and authRealm have no effect.

  • none if authentication is disabled on the server. The properties user, password, authRealm have no effect.

basic

useBookmarks

boolean

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.

true

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.

Listing 2. Acquiring a JDBC connection to a Neo4j server
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:

Listing 3. Acquiring an instance of the Neo4j JDBC Driver
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 with ssl=false, or sslMode set to disable

  • +ssc with ssl=false, or any sslmode not equal to require

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.

Logging

Via standard Java settings

To generate a useful and detailed log, you must configure java.util.logging. This can be done either through a configuration file or programmatically. The following section includes an example configuration that sets the global logging level to INFO, Neo4j JDBC Driver itself to DEBUG and everything that is network related to WARN:

Listing 4. Logging configuration for the Neo4j JDBC Driver that logs all informations
.level = INFO
handlers=java.util.logging.ConsoleHandler

# The handler must be configured for the lowest level it should catch
java.util.logging.ConsoleHandler.level=FINEST

# Enables all Logging for the JDBC Driver
org.neo4j.jdbc.level=ALL
# But reduces the noise on the network and the result set
org.neo4j.jdbc.result-set.level=WARNING
org.neo4j.jdbc.network.level=WARNING
# This is an example how to configure the outbound and inbound messages
org.neo4j.jdbc.network.OutboundMessageHandler.level=FINE
org.neo4j.jdbc.network.InboundMessageHandler.level=FINE

# This produces a date, followed by the level, 3 dashes, the message and the source of the log if available
java.util.logging.SimpleFormatter.format = %1$tFT%1$tk:%1$tM:%1$tS.%1$tL%1$tz %4$-15s --- %5$s [%2$s]%n

Such a file must be passed to the running Java program as a system property to Java itself with:

java -Djava.util.logging.config.file=docs/src/main/resources/logging-to-console.properties <your program>

Capturing logs to a file requires to change the handler:

Listing 5. Logging configuration for the Neo4j JDBC Driver that writes all JDBC logs to a file
.level = INFO
handlers=java.util.logging.ConsoleHandler

# Keep everything by default at INFO
java.util.logging.ConsoleHandler.level=INFO

# The handler must be configured for the lowest level it should catch
java.util.logging.FileHandler.level=FINEST
java.util.logging.FileHandler.pattern=jdbc.log
# XML Format by default
# java.util.logging.FileHandler.formatter=java.util.logging.SimpleFormatter

# Change the handler for JDBC
org.neo4j.jdbc.handlers=java.util.logging.FileHandler
# Keep the rest as above
org.neo4j.jdbc.level=ALL
org.neo4j.jdbc.result-set.level=WARNING
org.neo4j.jdbc.network.level=WARNING
org.neo4j.jdbc.network.OutboundMessageHandler.level=FINE
org.neo4j.jdbc.network.InboundMessageHandler.level=FINE

java.util.logging.SimpleFormatter.format = %1$tFT%1$tk:%1$tM:%1$tS.%1$tL%1$tz %4$-15s --- %5$s [%2$s]%n
The diagnosability features of the JDBC driver are based on the standard java.util.logging framework. Configuration of that framework itself is out of scope for this documentation. For a complete overview you might want to start at "Java Logging Overview". The formatter Java uses is the java.util.Formatter.

Inside a Spring Boot application

The Neo4j JDBC Driver will integrate itself into the Spring Boot logging configuration and take all relevant format and other settings from there. The levels can be configured with the levels Spring does understand. The following configuration is equivalent to the one above:

Listing 6. Logging configuration for the Neo4j JDBC Driver in a Spring Boot configuration file
logging.level.org.neo4j.jdbc=trace
logging.level.org.neo4j.jdbc.result-set=warn
logging.level.org.neo4j.jdbc.network=warn
logging.level.org.neo4j.jdbc.network.OutboundMessageHandler=debug
logging.level.org.neo4j.jdbc.network.InboundMessageHandler=debug

Inside a Quarkus application

The Neo4j JDBC Driver will integrate itself into the Quarkus logging configuration and take all relevant format and other settings from there. The levels can be configured with the levels Quarkus does understand. The following configuration is equivalent to the ones above:

Listing 7. Logging configuration for the Neo4j JDBC Driver in a Quarkus configuration file
quarkus.log.category."org.neo4j.jdbc".min-level=TRACE
quarkus.log.category."org.neo4j.jdbc".level=TRACE
quarkus.log.category."org.neo4j.jdbc.result-set".level=DEBUG
quarkus.log.category."org.neo4j.jdbc.network".level=WARNING
quarkus.log.category."org.neo4j.jdbc.network.OutboundMessageHandler".level=DEBUG
quarkus.log.category."org.neo4j.jdbc.network.InboundMessageHandler".level=DEBUG

SQL Translations

The SQL translators use the logger org.neo4j.jdbc.translator.