Driver Objects

Every Neo4j-backed application will require a Driver object. This object holds the details required to establish connections with a Neo4j database, including server URIs, credentials and other configuration. Driver objects hold a connection pool from which Session objects can borrow connections. Closing a driver will immediately shut down all connections in the pool.

Construction

Driver construction can either be carried out directly or via a classmethod on the GraphDatabase class.

class neo4j.GraphDatabase

Accessor for Driver construction.

classmethod driver(uri, **config)

Create a Driver object. Calling this method provides identical functionality to constructing a Driver or Driver subclass instance directly.

class neo4j.Driver(uri, **config)

Base class for all types of Driver, instances of which are used as the primary access point to Neo4j.

Parameters

• uri – URI for a graph database service

• config – configuration and authentication details (valid keys are listed below)

close()

Shut down, closing any open connections in the pool.

closed()

Return True if closed, False otherwise.

session(access_mode=None, **parameters)

Create a new Session object based on this Driver.

Parameters

• access_mode – default access mode (read or write) for transactions in this session

• parameters – custom session parameters (see Session for details)

Returns

new Session object

URI

On construction, the scheme of the URI determines the type of Driver object created. Each supported scheme maps to a particular Driver subclass that implements a specific behaviour. The remainder of the URI should be considered subclass-specific.

The alternative behaviours are described in the subsections below.

Bolt Direct

URI scheme:

bolt

Driver subclass:

DirectDriver

class neo4j.DirectDriver

A DirectDriver is created from a bolt URI and addresses a single database machine. This may be a standalone server or could be a specific member of a cluster.

Connections established by a DirectDriver are always made to the exact host and port detailed in the URI.

Bolt Routing

URI scheme:

bolt+routing

Driver subclass:

RoutingDriver

class neo4j.RoutingDriver

A RoutingDriver is created from a neo4j URI. The routing behaviour works in tandem with Neo4j’s Causal Clustering feature by directing read and write behaviour to appropriate cluster members.

Configuration

Additional configuration, including authentication details, can be provided via the Driver constructor.

auth

An authentication token for the server. For basic auth, this can be a simple tuple, for example ("neo4j", "password"). Alternatively, one of the auth token functions can be used.

neo4j.basic_auth(user, password, realm=None)

Generate a basic auth token for a given user and password.

Parameters

• user – user name

• password – current password

• realm – specifies the authentication provider

Returns

auth token for use with GraphDatabase.driver()

neo4j.custom_auth(principal, credentials, realm, scheme, **parameters)

Generate a basic auth token for a given user and password.

Parameters

• principal – specifies who is being authenticated

• credentials – authenticates the principal

• realm – specifies the authentication provider

• scheme – specifies the type of authentication

• parameters – parameters passed along to the authentication provider

Returns

auth token for use with GraphDatabase.driver()

encrypted

A boolean indicating whether or not TLS should be used for connections. Defaults to True if TLS is available.

trust

The trust level for certificates received from the server during TLS negotiation. This setting does not have any effect if encrypted is set to False.

neo4j.TRUST_ALL_CERTIFICATES

Trust any server certificate (default). This ensures that communication is encrypted but does not verify the server certificate against a certificate authority. This option is primarily intended for use with the default auto-generated server certificate.

neo4j.TRUST_SYSTEM_CA_SIGNED_CERTIFICATES

Trust server certificates that can be verified against the system certificate authority. This option is primarily intended for use with full certificates.

der_encoded_server_certificate

The server certificate in DER format, if required.

user_agent

A custom user agent string, if required. The driver will generate a user agent if none is supplied.

max_connection_lifetime

The maximum time for which a connection can exist before being closed on release, instead of returned to the pool.

max_connection_pool_size

The maximum number of connections managed by the connection pool

connection_acquisition_timeout

The maximum time to wait for a connection to be acquired from the pool.

connection_timeout

The maximum time to wait for a new connection to be established.

keep_alive

Flag to indicate whether or not the TCP KEEP_ALIVE setting should be used.

max_retry_time

The maximum time to allow for retries to be attempted when using transaction functions. After this time, no more retries will be attempted. This setting does not terminate running queries.

resolver

A custom resolver function to resolve host and port values ahead of DNS resolution. This function is called with a 2-tuple of (host, port) and should return an iterable of tuples as would be returned from getaddrinfo. If no custom resolver function is supplied, the internal resolver moves straight to regular DNS resolution.

For example:

def my_resolver(socket_address):
     if socket_address == ("foo", 9999):
        yield "::1", 7687
        yield "127.0.0.1", 7687
     else:
        from socket import gaierror
        raise gaierror("Unexpected socket address %r" % socket_address)

 driver = GraphDatabase.driver("bolt+routing://foo:9999", auth=("neo4j", "password"), resolver=my_resolver)

Object Lifetime

For general applications, it is recommended to create one top-level Driver object that lives for the lifetime of the application. For example:

from neo4j import GraphDatabase

class Application(object):

    def __init__(self, uri, user, password)
        self.driver = GraphDatabase.driver(uri, auth=(user, password))

    def close(self):
        self.driver.close()

Connection details held by the Driver are immutable. Therefore if, for example, a password is changed, a replacement Driver object must be created. More than one Driver may be required if connections to multiple databases, or connections as multiple users, are required.

Driver objects are thread-safe but cannot be shared across processes. Therefore, multithreading should generally be preferred over multiprocessing for parallel database access. If using multiprocessing however, each process will require its own Driver object.