neo4j

Implements the Bolt protocol (versions 4.4, 5.0-5.8, 6.0) for efficient binary communication with Neo4j graph databases, handling PackStream serialization/deserialization of queries and results. The driver uses a connection pool architecture that manages persistent TCP connections, with optional Rust-backed acceleration via neo4j-rust-ext for 40-60% faster serialization throughput. Protocol negotiation occurs at connection handshake to select the highest mutually-supported version.

Provides two parallel driver implementations (sync via _sync/driver.py and async via _async/driver.py) selected via GraphDatabase and AsyncGraphDatabase factory classes. URI scheme determines driver class instantiation: bolt:// and bolt+s:// route to BoltDriver or BoltAsyncDriver, while neo4j:// and neo4j+s:// route to RoutingDriver or RoutingAsyncDriver for cluster routing. Both APIs expose identical method signatures for session creation and configuration, enabling code portability between sync and async contexts.

Captures server-side notifications (warnings, deprecations, performance hints) returned with query results and exposes them via Result.summary().notifications. Notifications include severity levels (WARNING, INFORMATION) and codes (e.g., DEPRECATED_PROCEDURE, PERFORMANCE_HINT). The driver supports notification filtering via NotificationFilter to suppress or promote specific notification types. Notifications are useful for identifying deprecated Cypher syntax, performance issues, and server-side warnings without parsing error messages.

Provides fully asynchronous transaction and result APIs using Python's async/await syntax. AsyncDriver and AsyncSession implement the same transaction patterns as sync counterparts but return coroutines. Result streaming is asynchronous via async for loops, with lazy evaluation of records. The driver uses asyncio event loop for connection management and query execution, supporting concurrent queries across multiple sessions without thread overhead. Async transactions support the same retry logic and causal consistency as sync transactions.

Automatically deserializes Neo4j graph types (Node, Relationship, Path) to Python objects with attribute access and traversal methods. Nodes expose properties as dict-like attributes and support identity/label access. Relationships expose start/end node references and properties. Paths represent traversals as sequences of alternating nodes and relationships, supporting path length and segment iteration. Graph objects are immutable and support equality comparison. The driver handles circular references and nested graph structures transparently.

Supports Neo4j vector types for storing and retrieving embeddings (dense vectors of floats). Vectors are automatically serialized/deserialized as Python lists or numpy arrays. The driver integrates with Neo4j's vector index capabilities for similarity search without external vector databases. Vector operations (dot product, cosine similarity) are performed server-side via Cypher queries. The driver handles vector type validation and dimension checking.

Provides extensive driver configuration via GraphDatabase.driver() options including connection timeout, pool size, encryption, authentication, retry policy, and notification filtering. Configuration is immutable after driver instantiation. The driver supports environment variable overrides for sensitive settings (e.g., NEO4J_PASSWORD). Session-level configuration includes access mode, database selection, and bookmark passing. Advanced options include custom resolver for DNS resolution and custom trust store for certificate validation.

RoutingDriver and RoutingAsyncDriver implement Neo4j's routing protocol to automatically discover cluster topology and distribute queries across read replicas and write leaders. The driver maintains a routing table fetched from seed servers, caches it with TTL-based expiration, and routes READ transactions to any server, WRITE transactions to leaders, and SCHEMA transactions to leaders. Automatic failover occurs when a server becomes unavailable; the routing table is refreshed and the transaction is retried on a healthy server.

Provides explicit transaction control via session.begin_transaction() for fine-grained transaction lifecycle management, and implicit auto-commit transactions via session.run() for single-query execution. Transactions support three access modes (READ, WRITE, SCHEMA) and optional metadata. The driver implements ACID semantics with automatic rollback on exception, bookmark-based causal consistency across transactions, and configurable retry logic for transient failures (up to 30 seconds by default).

Executes queries and returns Result objects that implement lazy evaluation—records are fetched from the server on-demand as the application iterates, not all at once. Result objects expose record iteration, summary metadata (execution time, query plan, statistics), and result consumption patterns (fetch_all, single, next). The driver buffers records in a client-side queue to balance memory usage and network round-trips, with configurable fetch size. Summary objects provide query execution statistics, server info, and notification filtering.

Automatically maps Neo4j temporal types (Date, Time, DateTime, Duration) and spatial types (Point, CartesianPoint) to native Python objects with full arithmetic and comparison support. The driver implements ISO 8601 parsing for temporal strings and WGS84/Cartesian coordinate handling for spatial types. Temporal objects support timezone-aware operations, and spatial objects support distance calculations and coordinate transformations. Type conversion is transparent during result deserialization.

Supports multiple authentication schemes (BASIC, BEARER, KERBEROS, CUSTOM) via pluggable AuthManager interface. Built-in managers include BasicAuthManager (username/password), BearerAuthManager (JWT tokens), and CustomAuthManager for custom schemes. Authentication credentials are passed at driver instantiation and cached for connection reuse. The driver supports authentication token refresh for long-lived connections, and secure credential storage via environment variables or external secret managers.

Supports encrypted connections via bolt+s:// (TLS with certificate validation) and bolt+ssc:// (TLS with self-signed certificate bypass). The driver validates server certificates against system CA bundles by default, with options to disable validation or provide custom CA certificates. Certificate validation errors raise SecurityException. Secure connections use TLS 1.2+ with configurable cipher suites. The driver supports both encrypted and unencrypted connections in the same application via URI scheme selection.

Implements causal consistency via bookmarks—opaque tokens returned after each transaction that encode server-side transaction ordering. Bookmarks are passed to subsequent transactions via session.run(..., bookmarks=[...]) to ensure read-after-write consistency without distributed locks. The driver supports bookmark composition (combining multiple bookmarks) and bookmark filtering. Causal consistency is transparent to the application; the driver handles bookmark propagation automatically within a session.

Manages a pool of persistent TCP connections to Neo4j servers with configurable min/max pool size (default 1-100). The driver implements connection reuse for query execution, automatic connection eviction on idle timeout (default 30 minutes), and connection health checks via heartbeat pings. Pool exhaustion triggers backpressure (waiting for available connection) rather than connection creation. The driver supports per-session connection acquisition and release, with transparent connection recycling on server restart.