Client applications

This section describes how to manage database connections within an application.

The Driver Object

Neo4j client applications require a Driver Object which, from a data access perspective, forms the backbone of the application. It is through this object that all Neo4j interaction is carried out, and it should therefore be made available to all parts of the application that require data access.

In languages where thread safety is an issue, the Driver Object can be considered thread-safe.

A note on lifecycle

Applications will typically construct a Driver Object on startup and destroy it on exit.

Destroying a Driver Object will immediately shut down any connections previously opened via that Driver Object, by closing the associated connection pool.

This will have the consequence of rolling back any open transactions, and closing any unconsumed results.

To construct a driver instance, a connection URI and authentication information must be supplied.

Additional configuration details can be supplied if required. The configuration details are immutable for the lifetime of the Driver Object. Therefore, if multiple configurations are required (such as when working with multiple database users) then multiple Driver Objects must be used.

Example 1. The driver lifecycle

import org.neo4j.driver.AuthTokens;
import org.neo4j.driver.Driver;
import org.neo4j.driver.GraphDatabase;

public class DriverLifecycleExample implements AutoCloseable {
    private final Driver driver;

    public DriverLifecycleExample(String uri, String user, String password) {
        driver = GraphDatabase.driver(uri, AuthTokens.basic(user, password));
    }

    @Override
    public void close() throws RuntimeException {
        driver.close();
    }
}

Connection URIs

A connection URI identifies a graph database and how to connect to it.

The encryption and trust settings provide detail to how that connection should be secured.

Starting with Neo4j 4.0, client-server communication uses only unencrypted local connections by default. This is a change from previous versions, which switched on encryption by default, but generated a self-signed certificate out of the box.

When a full certificate is installed, and encryption is enabled on the driver, full certificate checks are carried out (refer to Operations Manual → SSL framework). Full certificates provide better overall security than self-signed certificates as they include a complete chain of trust back to a root certificate authority.

Neo4j Aura is a secure hosted service backed by full certificates signed by a root certificate authority.

To connect to Neo4j Aura, driver users must enable encryption and the complete set of certificate checks (the latter of which are enabled by default).

For more information, see Examples below.

Initial address resolution

The address provided in a neo4j:// URI is used for initial and fallback communication only.

This communication occurs to bootstrap the routing table, through which all subsequent communication is carried out. Fallback occurs when the driver is unable to contact any of the addresses held in the routing table. The initial address is once again reused to bootstrap the system.

Several options are available for providing this initial logical-to-physical host resolution. These include regular DNS, custom middleware such as a load balancer, and the Driver Object resolver function, all of which are described in the following sections.

DNS resolution

DNS resolution is the default, and always-available option. As it is possible to configure DNS to resolve a single host name down to multiple IP addresses, this can be used to expose all core server IP addresses under a single host name.

Figure 1. Initial address resolution over DNS

Custom middleware

Middleware, such as a load balancer, can be used to group the core servers under a single public address.

Figure 2. Initial address resolution using custom middleware

Resolver function

Neo4j Drivers also present an address resolution intercept hook called the resolver function.

This takes the form of a callback function that accepts a single input address and returns multiple output addresses. The function may hard code the output addresses or may draw them from another configuration source, as required.

Figure 3. Initial address resolution using resolver function

The example below shows how to expand a single address into multiple (hard-coded) output addresses:

Example 2. Custom Address Resolver

public void addExampleNode() {
    var addresses = Set.of(
            ServerAddress.of("a.example.com", 7676),
            ServerAddress.of("b.example.com", 8787),
            ServerAddress.of("c.example.com", 9898)
    );
    addNode("neo4j://x.example.com", AuthTokens.basic("neo4j", "some password"), addresses, UUID.randomUUID().toString());
}

public void addNode(String virtualUri, AuthToken authToken, Set<ServerAddress> addresses, String id) {
    var config = Config.builder()
            .withResolver(address -> addresses)
            .build();
    try (var driver = GraphDatabase.driver(virtualUri, authToken, config)) {
        driver.executableQuery("CREATE ({id: $id})")
                .withParameters(Map.of("id", id))
                .execute();
    }
}

Routing table

The routing table acts like the glue between the driver connectivity layer and the database surface. This table contains a list of server addresses, grouped as readers and writers, and is refreshed automatically by the driver as required.

The driver does not expose any API to work directly with the routing table, but it can sometimes be useful to explore when troubleshooting a system.

Load balancing policies

A policy parameter can be included in the query string of a neo4j:// URI, to customize the routing table and take advantage of multi-data center routing settings.

A prerequisite for using load balancing policies with the driver is that the database is operated on a cluster, and that some server policies are set up.

Examples

Connection URIs are typically formed according to the following pattern:

neo4j://<HOST>:<PORT>[?policy=<POLICY-NAME>]

This targets a routed Neo4j service that may be fulfilled by either a cluster or a single instance. The HOST and PORT values contain a logical hostname and port number targeting the entry point to the Neo4j service (e.g. neo4j://graph.example.com:7687).

In a clustered environment, the URI address will resolve to one of more of the core members; for standalone installations, this will simply point to that server address. The policy parameter allows for customization of the routing table and is discussed in more detail in load balancing policies.

An alternative URI form, using the bolt URI scheme (e.g. bolt://graph.example.com:7687), can be used when a single point-to-point connection is required. This variant is useful for the subset client applications (such as admin tooling) that need to be aware of individual servers, as opposed to those which require a highly available database service.

bolt://<HOST>:<PORT>

Each of the neo4j and bolt URI schemes permit variants that contain extra encryption and trust information. The +s variants enable encryption with a full certificate check, and the +ssc variants enable encryption, but with no certificate check. This latter variant is designed specifically for use with self-signed certificates.

Table 1. Available URI schemes
URI scheme	Routing	Description
`neo4j`	Yes	Unsecured
`neo4j+s`	Yes	Secured with full certificate
`neo4j+ssc`	Yes	Secured with self-signed certificate
`bolt`	No	Unsecured
`bolt+s`	No	Secured with full certificate
`bolt+ssc`	No	Secured with self-signed certificate

Neo4j 3.x did not provide a routing table in single instance mode and therefore you should use a bolt:// URI if targeting an older, non-clustered server.

The table below provides example code snippets for different deployment configurations. Each snippet expects an auth variable to have been previously defined, containing the authentication details for that connection.

Connecting to a service

The tables below illustrate examples of how to connect to a service with routing:

Table 2. Neo4j Aura or Neo4j >= 4.x, secured with full certificate
Product	Neo4j Aura, Neo4j >= 4.x
Security	Secured with full certificate
Code snippet	`GraphDatabase.driver("neo4j+s://graph.example.com:7687", auth)`
Comments	This is the default (and only option) for Neo4j Aura

Table 3. Neo4j >= 4.x, unsecured
Product	Neo4j >= 4.x
Security	Unsecured
Code snippet	`GraphDatabase.driver("neo4j://graph.example.com:7687", auth)`
Comments	This is the default for Neo4j >= 4.x series

Table 4. Neo4j >= 4.x, secured with self-signed certificate
Product	Neo4j >= 4.x
Security	Secured with self-signed certificate
Code snippet	`GraphDatabase.driver("neo4j+ssc://graph.example.com:7687", auth)`

To connect to a service without routing, you can replace neo4j with bolt.

Authentication

Authentication details are provided as an auth token which contains the user names, passwords or other credentials required to access the database. Neo4j supports multiple authentication standards but uses basic authentication by default.

Basic authentication

The basic authentication scheme is backed by a password file stored within the server and requires applications to provide a user name and password. For this, use the basic auth helper:

Example 3. Basic authentication

import org.neo4j.driver.AuthTokens;
import org.neo4j.driver.Driver;
import org.neo4j.driver.GraphDatabase;

public BasicAuthExample(String uri, String user, String password) {
    driver = GraphDatabase.driver(uri, AuthTokens.basic(user, password));
}

The basic authentication scheme can also be used to authenticate against an LDAP server.

Kerberos authentication

The Kerberos authentication scheme provides a simple way to create a Kerberos authentication token with a base64 encoded server authentication ticket. The best way to create a Kerberos authentication token is shown below:

Example 4. Kerberos authentication

import org.neo4j.driver.AuthTokens;
import org.neo4j.driver.Driver;
import org.neo4j.driver.GraphDatabase;

public KerberosAuthExample(String uri, String ticket) {
    driver = GraphDatabase.driver(uri, AuthTokens.kerberos(ticket));
}

The Kerberos authentication token can only be understood by the server if the server has the Kerberos Add-on installed.

Custom authentication

For advanced deployments, where a custom security provider has been built, the custom authentication helper can be used.

Example 5. Custom authentication

import org.neo4j.driver.AuthTokens;
import org.neo4j.driver.Driver;
import org.neo4j.driver.GraphDatabase;

import java.util.Map;

public CustomAuthExample(
        String uri,
        String principal,
        String credentials,
        String realm,
        String scheme,
        Map<String, Object> parameters) {
    driver = GraphDatabase.driver(uri, AuthTokens.custom(principal, credentials, realm, scheme, parameters));
}

Configuration

ConnectionAcquisitionTimeout

The maximum amount of time a session will wait when requesting a connection from the connection pool. For connection pools where all connections are currently being used and the MaxConnectionPoolSize limit has been reached, a session will wait this duration for a connection to be made available. Since the process of acquiring a connection may involve creating a new connection, ensure that the value of this configuration is higher than the configured ConnectionTimeout.

Setting a low value will allow for transactions to fail fast when all connections in the pool have been acquired by other transactions. Setting a higher value will result in these transactions being queued, increasing the chances of eventually acquiring a connection at the cost of longer time to receive feedback on failure. Finding an optimal value may require an element of experimentation, taking into consideration the expected levels of parallelism within your application as well as the MaxConnectionPoolSize.

Default: 60 seconds

Example 6. Configure connection pool

public ConfigConnectionPoolExample(String uri, String user, String password) {
    var config = Config.builder()
            .withMaxConnectionLifetime(30, TimeUnit.MINUTES)
            .withMaxConnectionPoolSize(50)
            .withConnectionAcquisitionTimeout(2, TimeUnit.MINUTES)
            .build();

    driver = GraphDatabase.driver(uri, AuthTokens.basic(user, password), config);
}

ConnectionTimeout

The maximum amount of time to wait for a TCP connection to be established. Connections are only created when a session requires one unless there is an available connection in the connection pool. The driver maintains a pool of open connections which can be loaned to a session when one is available. If a connection is not available, then an attempt to create a new connection (provided the MaxConnectionPoolSize limit has not been reached) is made with this configuration option, providing the maximum amount of time to wait for the connection to be established.

In environments with high latency and high occurrences of connection timeouts it is recommended to configure a higher value. For lower latency environments and quicker feedback on potential network issues configure with a lower value.

Default: 30 seconds

Example 7. Configure connection timeout

import org.neo4j.driver.AuthTokens;
import org.neo4j.driver.Config;
import org.neo4j.driver.Driver;
import org.neo4j.driver.GraphDatabase;

import static java.util.concurrent.TimeUnit.SECONDS;

public ConfigConnectionTimeoutExample(String uri, String user, String password) {
    var config = Config.builder()
            .withConnectionTimeout(15, SECONDS)
            .build();

    driver = GraphDatabase.driver(uri, AuthTokens.basic(user, password), config);
}

CustomResolver

Specify a custom server address resolver used by the routing driver to resolve the initial address used to create the driver. See Resolver function for more details.

Encryption

Specify whether to use an encrypted connection between the driver and server.

Default: False

Example 8. Unencrypted configuration

import org.neo4j.driver.AuthTokens;
import org.neo4j.driver.Config;
import org.neo4j.driver.Driver;
import org.neo4j.driver.GraphDatabase;

public ConfigUnencryptedExample(String uri, String user, String password) {
    var config = Config.builder().withoutEncryption().build();

    driver = GraphDatabase.driver(uri, AuthTokens.basic(user, password), config);
}

MaxConnectionLifetime

The maximum duration the driver will keep a connection for before being removed from the pool. Note that while the driver will respect this value, it is possible that the network environment will close connections inside this lifetime. This is beyond the control of the driver. The check on the connection’s lifetime happens when a session requires a connection. If the available connection’s lifetime is over this limit it is closed and a new connection is created, added to the pool and returned to the requesting session. Changing this configuration value would be useful in environments where users don’t have full control over the network environment and wish to proactively ensure all connections are ready.

Setting this option to a low value will cause a high connection churn rate, and can result in a performance drop. It is recommended to pick a value smaller than the maximum lifetime exposed by the surrounding system infrastructure (such as operating system, router, load balancer, proxy and firewall). Negative values result in lifetime not being checked.

Default: 1 hour (3600 seconds)

MaxConnectionPoolSize

The maximum total number of connections allowed, per host (i.e. cluster nodes), to be managed by the connection pool. In other words, for a direct driver using the bolt:// scheme, this sets the maximum number of connections towards a single database server. For a driver connected to a cluster using the neo4j:// scheme, this sets the maximum amount of connections per cluster member. If a session or transaction tries to acquire a connection at a time when the pool size is at its full capacity, it must wait until a free connection is available in the pool or the request to acquire a new connection times out. The connection acquiring timeout is configured via ConnectionAcquisitionTimeout.

This configuration option allows you to manage the memory and I/O resources being used by the driver and tuning this option is dependent on these factors, in addition to number of cluster members.

Default: 100 connections

MaxTransactionRetryTime

The maximum amount of time that a managed transaction will retry for before failing. Queries that are executed within a managed transaction gain the benefit of being retried when a transient error occurs. When this happens the transaction is retired multiple times up to the MaxTransactionRetryTime.

Configure this option higher in high latency environments or if you are executing many large transactions which could limit the number of times that they are retired and therefore their chance to succeed. Configure lower in low latency environments and where your workload mainly consists of many smaller transactions. Failing transactions faster may highlight the reasons behind the transient errors making it easier to fix underlying issues.

Default: 30 seconds

Example 9. Configure maximum retry time

import org.neo4j.driver.AuthTokens;
import org.neo4j.driver.Config;
import org.neo4j.driver.Driver;
import org.neo4j.driver.GraphDatabase;

import static java.util.concurrent.TimeUnit.SECONDS;

public ConfigMaxRetryTimeExample(String uri, String user, String password) {
    var config = Config.builder()
            .withMaxTransactionRetryTime(15, SECONDS)
            .build();

    driver = GraphDatabase.driver(uri, AuthTokens.basic(user, password), config);
}

TrustedCertificates

Specify how to determine the authenticity of encryption certificates provided by the Neo4j instance that you are connecting to. If encryption is disabled, this option has no effect.

Possible values are:

Config.TrustStrategy.trustSystemCertificates() - [Default] Accept any certificate that can be verified against the system store.
Config.TrustStrategy.trustCustomCertificateSignedBy("/path/ca1.crt", "/path/ca2.crt", …) - Accept certificates at specified paths.
Config.TrustStrategy.trustAllCertificates() - Accept any certificate, including self-signed ones. Not recommended for production environments.

Example 10. Configure trusted certificates

import org.neo4j.driver.AuthTokens;
import org.neo4j.driver.Config;
import org.neo4j.driver.Driver;
import org.neo4j.driver.GraphDatabase;

public ConfigTrustExample(String uri, String user, String password) {
    var config = Config.builder()
            .withTrustStrategy(Config.TrustStrategy.trustSystemCertificates())
            .build();

    driver = GraphDatabase.driver(uri, AuthTokens.basic(user, password), config);
}

Logging

All official Neo4j Drivers log information to standard logging channels. This can typically be accessed in an ecosystem-specific way.

The code snippet below demonstrates how to redirect log messages to standard output:

ConfigBuilder.withLogging(Logging.console(Level.DEBUG))

Was this page helpful?