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.
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.
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:
-
class
neo4j.
DirectDriver
¶ A
DirectDriver
is created from abolt
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:
-
class
neo4j.
RoutingDriver
¶ A
RoutingDriver
is created from aneo4j
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.