Neo4j Rust Extensions

Common errors

• IOError: Broken pipe

  cause This error often occurs during large data transfers or extensive write operations between the Python driver and the Neo4j database, indicating a communication breakdown.
  fix For very large datasets, consider optimizing your Cypher queries, batching operations, or using Neo4j's native data import tools (e.g., `LOAD CSV`) or `.cypher` scripts instead of streaming directly from Python.

• neo4j.exceptions.AuthError: The client is unauthorized to access the database. Please check your credentials.

  cause Incorrect username, password, or an authentication mechanism mismatch when connecting to the Neo4j database.
  fix Verify that the `username` and `password` passed to `GraphDatabase.driver` are correct for your Neo4j instance. Also, ensure the URI is correct (e.g., `bolt://localhost:7687` for local connections).

• neo4j.exceptions.ServiceUnavailable: Failed to establish connection to 'bolt://<host>:<port>': [Errno 111] Connection refused

  cause The Neo4j database server is not running, is inaccessible from the client machine, or the specified host/port is incorrect.
  fix Ensure your Neo4j database is running and reachable from where your Python application is executed. Check firewall settings and the Neo4j configuration for the correct Bolt port (default is 7687).

• Failed to build neo4j-rust-ext

  cause Pre-built wheels for your specific operating system or Python version are not available on PyPI, and your environment lacks the necessary Rust toolchain or C build tools to compile the extension from source.
  fix Install the Rust toolchain (version 1.65.0 or newer) and platform-specific C build tools (e.g., `sudo apt install gcc` on Ubuntu, or Visual Studio Build Tools on Windows). Refer to `PyO3` and `Maturin` documentation for detailed build environment setup.

Warnings

• breaking The version of `neo4j-rust-ext` (excluding its last segment for patches) *must* match the major.minor.patch version of the `neo4j` driver it enhances for compatibility.
  Fix: Ensure your `requirements.txt` or `pyproject.toml` specifies matching versions, e.g., `neo4j-rust-ext == X.Y.Z.*` if `neo4j == X.Y.Z` is used.
• gotcha For pre-release versions of the `neo4j` driver (e.g., `X.Y.ZaA`), the `neo4j-rust-ext` versioning requires an explicit `N` instead of `*` (e.g., `X.Y.Z.NaA`).
  Fix: Explicitly define the `N` segment for pre-release driver versions: `neo4j-rust-ext == X.Y.Z.NaA`.
• gotcha When troubleshooting issues, consider temporarily uninstalling `neo4j-rust-ext` to isolate whether the problem lies with the base `neo4j` driver or the Rust extensions.
  Fix: Run `pip uninstall neo4j-rust-ext` and then `pip install neo4j` (if you removed `neo4j` to simplify versioning) to revert to the pure Python driver.
• gotcha Reliance on internal APIs of the `neo4j` driver might lead to breakage in minor or patch releases, even with the Rust extension enabled.
  Fix: Stick to documented public APIs of the `neo4j` driver. Be aware that stack traces might appear differently when Rust code is executing.

Install

• pip install neo4j-rust-ext Install latest stable version

Imports

• GraphDatabase

  from neo4j import GraphDatabase

  neo4j-rust-ext is a drop-in replacement, so imports remain the same as the base 'neo4j' driver.

Quickstart

This quickstart demonstrates connecting to a Neo4j database and performing basic Cypher queries using the `neo4j` driver, which `neo4j-rust-ext` transparently enhances for performance. Ensure `NEO4J_URI`, `NEO4J_USERNAME`, and `NEO4J_PASSWORD` environment variables are set or modify the default values.

import os
from neo4j import GraphDatabase, RoutingControl

URI = os.environ.get('NEO4J_URI', 'bolt://localhost:7687')
USERNAME = os.environ.get('NEO4J_USERNAME', 'neo4j')
PASSWORD = os.environ.get('NEO4J_PASSWORD', 'password')
DATABASE = os.environ.get('NEO4J_DATABASE', 'neo4j')


class Neo4jApp:
    def __init__(self, uri, username, password):
        self.driver = GraphDatabase.driver(uri, auth=(username, password))
        self.driver.verify_connectivity()

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

    def add_friend(self, name, friend_name):
        # Queries are run against the default database unless specified.
        # Explicitly setting database_='neo4j' for clarity, adjust as needed.
        self.driver.execute_query(
            "MERGE (a:Person {name: $name}) "
            "MERGE (friend:Person {name: $friend_name}) "
            "MERGE (a)-[:KNOWS]->(friend)",
            name=name,
            friend_name=friend_name,
            database_=DATABASE,
        )

    def print_friends(self, name):
        records, _, _ = self.driver.execute_query(
            "MATCH (a:Person)-[:KNOWS]->(friend) WHERE a.name = $name "
            "RETURN friend.name ORDER BY friend.name",
            name=name,
            database_=DATABASE,
            routing_=RoutingControl.READ,
        )
        for record in records:
            print(record["friend.name"])


if __name__ == "__main__":
    app = Neo4jApp(URI, USERNAME, PASSWORD)
    print("Adding friends...")
    app.add_friend("Arthur", "Guinevere")
    app.add_friend("Arthur", "Lancelot")
    app.add_friend("Arthur", "Merlin")

    print("Arthur's friends:")
    app.print_friends("Arthur")
    app.close()