py2neo.client – Low-level client connections for Neo4j

class py2neo.client.Connection(profile, user_agent, on_bind=None, on_unbind=None, on_release=None)

A single point-to-point connection between a client and a server.

This base class is extended by both Bolt and HTTP implementations and contains interfaces for the basic operations provided by both.

Variables:

• Connection.profile – connection profile
• Connection.user_agent –

age

The age of this connection in seconds.

begin(graph_name, readonly=False)

Begin a transaction. This method may invoke network activity.

Parameters:

• graph_name –
• readonly –

Returns:

new Transaction object

Raises:

Failure – if a new transaction cannot be created

broken

True if the connection has been broken by the server or network.

closed

True if the connection has been closed by the client.

commit(tx)

Commit a transaction. This method will always invoke network activity.

Parameters:

tx – the transaction to commit

Returns:

bookmark

Raises:

• ValueError – if the supplied Transaction object is not valid for committing
• ConnectionBroken – if the transaction cannot be committed

get_cluster_overview(tx=None)

Fetch an overview of the cluster of which the server is a member. If the server is not part of a cluster, a TypeError is raised.

Parameters:tx – transaction in which this call should be carried out, if any Returns:dictionary of cluster membership, keyed by unique server ID Raises:TypeError if the server is not a member of a cluster

get_config(tx=None)

Fetch a dictionary of configuration for the server to which this connection is established.

Parameters:tx – transaction in which this call should be carried out, if any Returns:dictionary of name-value pairs for each setting

get_connections(tx=None)

Fetch a list of connections to the server to which this connection is established.

This method calls the dbms.listConnections procedure, which is available with the following versions of Neo4j:

• Community Edition - version 4.2 and above
• Enterprise Edition - all versions

Returns:list of ConnectionRecord objects Raises:TypeError – if the dbms.listConnections procedure is not supported by the underlying Neo4j installation

get_management_data(tx=None)

Fetch a dictionary of management data for the server to which this connection is established. This method calls the dbms.queryJmx procedure.

The structure and format of the data returned may vary depending on the underlying version and edition of Neo4j.

get_queries(tx=None)

Fetch a list of queries currently active on the server to which this connection is established.

This method calls the dbms.listQueries procedure, which is available with the following versions of Neo4j:

• Community Edition - version 4.2 and above
• Enterprise Edition - all versions

Returns:list of QueryRecord objects Raises:TypeError – if the dbms.listQueries procedure is not supported by the underlying Neo4j installation

get_transactions(tx=None)

Fetch a list of transactions currently active on the server to which this connection is established.

This method calls the dbms.listTransactions procedure, which is available with the following versions of Neo4j:

• Community Edition - version 4.2 and above
• Enterprise Edition - all versions

Returns:list of TransactionRecord objects Raises:TypeError – if the dbms.listTransactions procedure is not supported by the underlying Neo4j installation

neo4j_edition

The edition of Neo4j to which this connection is established.

neo4j_version

The version of Neo4j to which this connection is established.

classmethod open(profile=None, user_agent=None, on_bind=None, on_unbind=None, on_release=None, on_broken=None)

Open a connection to a server.

Parameters:

• profile – ConnectionProfile detailing how and where to connect
• user_agent –
• on_bind –
• on_unbind –
• on_release –
• on_broken –

Returns:

Bolt connection object

Raises:

ConnectionUnavailable if a connection cannot be opened

Raises:

ValueError if the profile references an unsupported scheme

release()

Signal that this connection is no longer in use.

rollback(tx)

Rollback a transaction. This method will always invoke network activity.

Parameters:

tx – the transaction to rollback

Returns:

bookmark

Raises:

• ValueError – if the supplied Transaction object is not valid for rolling back
• ConnectionBroken – if the transaction cannot be rolled back

route(graph_name=None, context=None)

Fetch the routing table for a given database.

Parameters:

• graph_name – the name of the graph database for which to retrieve a routing table; None references the default database
• context – an optional dictionary of routing context information

Returns:

4-tuple of router, reader, writer connection profiles, plus ttl

Raises:

TypeError – if routing is not supported

run_prog(graph_name, cypher, parameters=None, readonly=False)

Run a single query within an auto-commit transaction. This method may invoke network activity

Parameters:

• graph_name –
• cypher –
• parameters –
• readonly –

Returns:

supports_multi()

Detect whether or not this connection supports multi-database.

sync(result)

Perform network synchronisation required to make available a given result.

exception py2neo.client.ConnectionBroken

Raised when a connection breaks during use.

class py2neo.client.ConnectionPool(profile, user_agent=None, max_size=None, max_age=None, on_bind=None, on_unbind=None, on_broken=None)

A pool of connections targeting a single Neo4j server.

acquire(force_reset=False)

Acquire a connection from the pool.

In the simplest case, this will return an existing open connection, if one is free. If not, and the pool is not full, a new connection will be created. If the pool is full and no free connections are available, this will block until a connection is released, or until the acquire call is cancelled.

This method will raise ConnectionUnavailable if the maximum size of the pool is set to zero, if the pool is full and all connections are in use, or if a new connection attempt is made which fails.

Parameters:force_reset – if true, the connection will be forcibly reset before being returned; if false, this will only occur if the connection is not already in a clean state Returns:a Bolt connection object Raises:ConnectionUnavailable if no connection can be acquired

close()

Close all connections immediately.

This does not permanently disable the connection pool. Instead, it sets the maximum pool size to zero before shutting down all open connections, including those in use.

To reuse the pool, the maximum size will need to be set to a a value greater than zero before connections can once again be acquired.

To close gracefully, allowing work in progress to continue until connections are released, use the following sequence instead:

pool.max_size = 0 pool.prune()

This will force all future connection acquisitions to be rejected, and released connections will be closed instead of being returned to the pool.

connect()

Open a new connection, adding it to a list of opened connections in order to collect statistics. This method also collects stats from closed or broken connections into a pool-wide running total.

in_use

The number of connections in this pool that are currently in use.

max_age

The maximum permitted age, in seconds, for connections to be retained in this pool.

max_size

The maximum permitted number of simultaneous connections that may be owned by this pool, both in-use and free.

classmethod open(profile=None, user_agent=None, init_size=None, max_size=None, max_age=None, on_bind=None, on_unbind=None, on_broken=None)

Create a new connection pool, with an option to seed one or more initial connections.

Parameters:

• profile – a ConnectionProfile describing how to connect to the remote service for which this pool operates
• user_agent – a user agent string identifying the client software
• init_size – the number of seed connections to open
• max_size – the maximum permitted number of simultaneous connections that may be owned by this pool, both in-use and free
• max_age – the maximum permitted age, in seconds, for connections to be retained in this pool
• on_bind – callback to execute when binding a transaction to a connection; this must accept two arguments representing the transaction and the connection
• on_unbind – callback to execute when unbinding a transaction from a connection; this must accept an argument representing the transaction
• on_broken – callback to execute when a connection in the pool is broken; this must accept an argument representing the connection profile and a second with an error message

Raises:

ConnectionUnavailable if connections cannot be successfully made to seed the pool

Raises:

ValueError if the profile references an unsupported scheme

profile

The connection profile for which this pool operates.

prune()

Close all free connections.

release(cx, force_reset=False)

Release a Bolt connection, putting it back into the pool if the connection is healthy and the pool is not already at capacity.

Parameters:

• cx – the connection to release
• force_reset – if true, the connection will be forcibly reset before being released back into the pool; if false, this will only occur if the connection is not already in a clean state

Raises:

ValueError – if the connection does not belong to this pool

size

The total number of connections (both in-use and free) currently owned by this connection pool.

user_agent

The user agent for connections in this pool.

class py2neo.client.ConnectionRecord(cxid, since, client_address, server_profile, user_agent)

client_address

Alias for field number 2

cxid

Alias for field number 0

server_profile

Alias for field number 3

since

Alias for field number 1

user_agent

Alias for field number 4

exception py2neo.client.ConnectionUnavailable

Raised when a connection cannot be acquired.

class py2neo.client.Connector(profile, user_agent=None, init_size=None, max_size=None, max_age=None, routing=False)

A connection pool abstraction that uses an appropriate connection pool implementation and is coupled with a transaction manager.

Parameters:

• profile – a ConnectionProfile describing how to connect to the remote graph database service
• user_agent – a user agent string identifying the client software
• init_size – the number of seed connections to open in the initial pool
• max_size – the maximum permitted number of simultaneous connections that may be owned by pools held by this connector, both in-use and free
• max_age – the maximum permitted age, in seconds, for connections to be retained within pools held by this connector
• routing – flag to switch on client-side routing across a cluster

add_pools(*profiles)

Adds connection pools for one or more connection profiles. Pools that already exist will be skipped.

begin(graph_name, readonly=False)

Begin a new explicit transaction.

Parameters:

• graph_name –
• readonly –

Returns:

new Transaction object

Raises:

• ConnectionUnavailable – if a begin attempt cannot be made
• ConnectionBroken – if a begin attempt is made, but fails due to disconnection
• Failure – if the server signals a failure condition

close()

Close all connections immediately.

This does not permanently disable the connection pool. Instead, it sets the maximum pool size to zero before shutting down all open connections, including those in use.

To reuse the pool, the maximum size will need to be set to a a value greater than zero before connections can once again be acquired.

To close gracefully, allowing work in progress to continue until connections are released, use the following sequence instead:

pool.max_size = 0 pool.prune()

This will force all future connection acquisitions to be rejected, and released connections will be closed instead of being returned to the pool.

commit(tx)

Commit a transaction.

Parameters:

tx – the transaction to commit

Returns:

dictionary of transaction summary information

Raises:

• ValueError – if the transaction is not valid to be committed
• ConnectionUnavailable – if a commit attempt cannot be made
• ConnectionBroken – if a commit attempt is made, but fails due to disconnection
• Failure – if the server signals a failure condition

default_graph_name()

Fetch the default graph database name for the service.

get_pools(graph_name=None, readonly=False)

Obtain a list of connection pools for a particular graph database and read/write mode.

If, for any reason, the routing table is not valid, a RoutingTable.Invalid exception will be raised. Possible reasons are: - No routing table exists for the given graph database - The routing table has expired - No appropriate readonly or read-write servers are listed

graph_names()

Fetch a list of available graph database names.

in_use

A dictionary mapping each profile to the number of connections currently pooled for that profile that are currently in use.

profile

The initial connection profile for this connector.

prune(profile)

Close all free connections for the given profile.

rollback(tx)

Roll back a transaction.

Parameters:

tx – the transaction to rollback

Returns:

dictionary of transaction summary information

Raises:

• ValueError – if the transaction is not valid to be rolled back
• ConnectionUnavailable – if a rollback attempt cannot be made
• ConnectionBroken – if a rollback attempt is made, but fails due to disconnection
• Failure – if the server signals a failure condition

run_prog(graph_name, cypher, parameters=None, readonly=False)

Run a Cypher query within a new auto-commit transaction.

Parameters:

• graph_name –
• cypher –
• parameters –
• readonly –

Returns:

Result object

Raises:

• ConnectionUnavailable – if an attempt to run cannot be made
• ConnectionBroken – if an attempt to run is made, but fails due to disconnection
• Failure – if the server signals a failure condition

run_query(tx, cypher, parameters=None)

Run a Cypher query within an open explicit transaction.

Parameters:

• tx –
• cypher –
• parameters –

Returns:

Result object

Raises:

• ConnectionUnavailable – if an attempt to run cannot be made
• ConnectionBroken – if an attempt to run is made, but fails due to disconnection
• Failure – if the server signals a failure condition

user_agent

The user agent for connections attached to this connector.

exception py2neo.client.Failure(message, code)

exception py2neo.client.ProtocolError

Raised when a protocol violation or other unrecoverable protocol error occurs. These errors cannot be recovered from automatically, and may result from a bug in the driver or server software.

class py2neo.client.QueryRecord(qid, since, cxid, client_address, server_profile, metadata, database, query, parameters, planner, runtime, indexes, status, stats)

client_address

Alias for field number 3

cxid

Alias for field number 2

database

Alias for field number 6

indexes

Alias for field number 11

metadata

Alias for field number 5

parameters

Alias for field number 8

planner

Alias for field number 9

qid

Alias for field number 0

query

Alias for field number 7

runtime

Alias for field number 10

server_profile

Alias for field number 4

since

Alias for field number 1

stats

Alias for field number 13

status

Alias for field number 12

class py2neo.client.Result(graph_name)

Abstract base class representing the result of a Cypher query.

buffer()

Fetch the remainder of the result into memory. This method may carry out network activity.

Raises:ConnectionBroken if the transaction is broken by an unexpected network event.

fetch()

Fetch and return the next record in this result, or None if at the end of the result. This method may carry out network activity.

Returns:the next available record, or None Raises:ConnectionBroken if the transaction is broken by an unexpected network event.

fields()

Return the list of field names for records in this result. This method may carry out network activity.

Returns:list of field names Raises:ConnectionBroken if the transaction is broken by an unexpected network event.

graph_name

Return the name of the database from which this result originates.

Returns:database name

has_records()

Return True if this result contains buffered records, False otherwise. This method does not carry out any network activity.

Returns:boolean indicator

peek_records(limit)

Return up to limit records from the buffer if available. This method does not carry out any network activity.

Returns:list of records

protocol_version

Return the underlying protocol version used to transfer this result, or None if not applicable.

Returns:protocol version

query_id()

Return the ID of the query behind this result. This method may carry out network activity.

Returns:query ID or None Raises:ConnectionBroken if the transaction is broken by an unexpected network event.

records()

Iterate through the remaining records, yielding each one in turn. This method may carry out network activity.

Returns:record iterator Raises:ConnectionBroken if the transaction is broken by an unexpected network event.

summary()

Gather and return summary information as relates to the current progress of query execution and result retrieval. This method does not carry out any network activity.

Returns:summary information

take_record()

Return the next record from the buffer if one is available, None otherwise. This method does not carry out any network activity.

Returns:record or None

class py2neo.client.TransactionRecord(txid, since, cxid, client_address, server_profile, metadata, database, current_qid, current_query, status, stats)

client_address

Alias for field number 3

current_qid

Alias for field number 7

current_query

Alias for field number 8

cxid

Alias for field number 2

database

Alias for field number 6

metadata

Alias for field number 5

server_profile

Alias for field number 4

since

Alias for field number 1

stats

Alias for field number 10

status

Alias for field number 9

txid

Alias for field number 0

class py2neo.client.TransactionRef(graph_name, txid=None, readonly=False)

Reference to a protocol-level transaction.

broken

Flag indicating whether this transaction has been broken due to disconnection or remote failure.