Advanced connection information

Connection protocols and security

Communication between the driver and the server is mediated by Bolt. The scheme of the server URI determines whether the connection is encrypted and, if so, what type of certificates are accepted.

URL scheme	Encryption	Comment
neo4j		Default for local setups
neo4j+s	(only CA-signed certificates)	Default for Aura
neo4j+ssc	(CA- and self-signed certificates)

URL scheme

Encryption

Comment

neo4j

Default for local setups

neo4j+s

(only CA-signed certificates)

Default for Aura

neo4j+ssc

(CA- and self-signed certificates)

The driver receives a routing table from the server upon successful connection, regardless of whether the instance is a proper cluster environment or a single-machine environment. The driver’s routing behavior works in tandem with Neo4j’s clustering by directing read/write transactions to appropriate cluster members. If you want to target a specific machine, use a BoltDriver object and bolt, bolt+s, or bolt+ssc URI schemes instead.

The connection scheme to use is not your choice, but is rather determined by the server requirements. You must know the right server scheme upfront, as no metadata is exposed prior to connection. If you are unsure, ask the database administrator.

Authentication methods

Basic authentication (default)

The basic authentication scheme relies on traditional username and password. These can either be the credentials for your local installation, or the ones provided with an Aura instance.

from neo4j import GraphDatabase

driver = GraphDatabase.driver(uri, auth=(user, password))

The basic authentication scheme can also be used to authenticate against an LDAP server (Enterprise Edition only).

Kerberos authentication

The Kerberos authentication scheme requires a base64-encoded ticket. It can only be used if the server has the Kerberos Add-on installed.

from neo4j import GraphDatabase, kerberos_auth

driver = GraphDatabase.driver(uri, auth=kerberos_auth(ticket))

Bearer authentication

The bearer authentication scheme requires a base64-encoded token provided by an Identity Provider through Neo4j’s Single Sign-On feature.

from neo4j import GraphDatabase, bearer_auth

driver = GraphDatabase.driver(uri, auth=bearer_auth(token))

The bearer authentication scheme requires configuring Single Sign-On on the server. Once configured, clients can discover Neo4j’s configuration through the Discovery API.

Custom authentication

Use the function custom_auth to log into a server having a custom authentication scheme.

If authentication is disabled on the server, the auth parameter can be omitted entirely.

Custom address resolver

When creating a Driver object, you can specify a resolver function to resolve any addresses the driver receives ahead of DNS resolution. Your resolver function is called with an Address object and should return an iterable of Address objects (or values that can be used to construct Address objects)

In the following example, the connection to example.com on port 9999 is resolved to localhost on port 7687:

import neo4j


def custom_resolver(socket_address):
    # assert isinstance(socket_address, neo4j.Address)
    if socket_address != ("example.com", 9999):
        raise OSError(f"Unexpected socket address {socket_address!r}")

    # You can return any neo4j.Address object
    yield neo4j.Address(("localhost", 7687))  # IPv4
    yield neo4j.Address(("::1", 7687, 0, 0))  # IPv6
    yield neo4j.Address.parse("localhost:7687")
    yield neo4j.Address.parse("[::1]:7687")

    # or any tuple that can be passed to neo4j.Address(...).
    # This will initially be interpreted as IPv4, but DNS resolution
    # will turn it into IPv6 if appropriate.
    yield "::1", 7687
    # This will be interpreted as IPv6 directly, but DNS resolution will
    # still happen.
    yield "::1", 7687, 0, 0
    yield "127.0.0.1", 7687


driver = neo4j.GraphDatabase.driver("neo4j://example.com:9999",
                                    auth=(user, password),
                                    resolver=custom_resolver)

Further connection parameters

You can find all Driver configuration parameters in the API documentation.

Glossary

LTS: A Long Term Support release is one guaranteed to be supported for a number of years. Neo4j 4.4 is LTS, and Neo4j 5 will also have an LTS version.
Aura: Aura is Neo4j’s fully managed cloud service. It comes with both free and paid plans. Every Neo4j-backed application requires a Driver object.
Cypher: Cypher is Neo4j’s graph query language that lets you retrieve data from the graph. It is like SQL, but for graphs.
APOC: Awesome Procedures On Cypher (APOC) is a library of (many) functions that can not be easily expressed in Cypher itself.
Bolt: Bolt is the protocol used for interaction between Neo4j instances and drivers. It listens on port 7687 by default.
ACID: Atomicity, Consistency, Isolation, Durability (ACID) are properties guaranteeing that database transactions are processed reliably. An ACID-compliant DBMS ensures that the data in the database remains accurate and consistent despite failures.
eventual consistency: A database is eventually consistent if it provides the guarantee that all cluster members will, at some point in time, store the latest version of the data.
causal consistency: A database is causally consistent if read and write queries are seen by every member of the cluster in the same order. This is stronger than eventual consistency.
null: The null marker is not a type but a placeholder for absence of value. For more information, see Cypher Manual — Working with null.
transaction: A transaction is a unit of work that is either committed in its entirety or rolled back on failure. An example is a bank transfer: it involves multiple steps, but they must all succeed or be reverted, to avoid money being subtracted from one account but not added to the other.
backpressure: Backpressure is a force opposing the flow of data. It ensures that the client is not being overwhelmed by data faster than it can handle.
transaction function: A transaction function is a callback executed by an execute_read or execute_write call. The driver automatically re-executes the callback in case of server failure.
Driver: A Driver object holds the details required to establish connections with a Neo4j database.

Was this page helpful?