Neo4j Python Driver

Warnings

• breaking The way to access records and iterate through `Result` objects significantly changed when migrating from version 4.x to 5.x. Direct iteration over `Result` might behave differently or raise errors. Methods like `single()`, `data()`, and explicit iteration are now the standard.
  Fix: Adopt the new `Result` object API. Use `result.single()` for expected single records, `result.data()` for list of dictionaries, or iterate explicitly: `[record for record in result]`.
• breaking The transaction API was revamped in 5.x. Functions like `session.read_transaction()` and `session.write_transaction()` now pass a `Transaction` object (`tx`) to the user-defined callback, rather than the `Session` object directly. Direct `session.run()` without an explicit transaction context often auto-commits.
  Fix: Update transaction callbacks to accept a `tx` object (e.g., `def my_tx_func(tx, param): tx.run(...)`). For manual transactions, use `session.begin_transaction()`, then `tx.run()`, `tx.commit()`, and `tx.rollback()`.
• gotcha It is crucial to properly close `Driver` and `Session` objects to prevent connection leaks and ensure resource release. Drivers are designed to be long-lived, while sessions should be short-lived.
  Fix: Always use `with driver.session() as session:` for session management. Call `driver.close()` when your application is shutting down or the driver is no longer needed.
• gotcha Authentication token handling changed in 5.x. The `AuthTokens` module (e.g., `AuthTokens.basic`) is the recommended way to provide credentials, replacing simpler tuple-based authentication methods from older versions.
  Fix: Use `auth=AuthTokens.basic("username", "password")` when creating a `GraphDatabase.driver()` instance.

Install

• pip install neo4j Install stable version

Imports

• GraphDatabase

  from neo4j import GraphDatabase

• AuthTokens

  from neo4j import AuthTokens

  AuthTokens module for authentication was introduced in 5.x, replacing direct usage of tuples or basic_auth function from older versions.

Quickstart

This quickstart demonstrates how to connect to a Neo4j database using environment variables, create and manage a driver, use `AuthTokens` for authentication, and execute Cypher queries within read/write transactions. It showcases creating and finding nodes, emphasizing proper session and driver resource management.

import os
from neo4j import GraphDatabase, AuthTokens

# Configure connection details using environment variables
NEO4J_URI = os.environ.get("NEO4J_URI", "bolt://localhost:7687")
NEO4J_USERNAME = os.environ.get("NEO4J_USERNAME", "neo4j")
NEO4J_PASSWORD = os.environ.get("NEO4J_PASSWORD", "password") # Use a strong password in production

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

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

    def create_person(self, name):
        with self.driver.session() as session:
            greeting = session.execute_write(self._create_and_return_person, name)
            print(f"Created person: {greeting}")

    @staticmethod
    def _create_and_return_person(tx, name):
        query = (
            "CREATE (p:Person {name: $name}) "
            "RETURN p.name AS name"
        )
        result = tx.run(query, name=name)
        return result.single()["name"]

    def find_person(self, name):
        with self.driver.session() as session:
            person_name = session.execute_read(self._find_and_return_person, name)
            print(f"Found person: {person_name}")

    @staticmethod
    def _find_and_return_person(tx, name):
        query = (
            "MATCH (p:Person {name: $name}) "
            "RETURN p.name AS name"
        )
        result = tx.run(query, name=name)
        record = result.single()
        return record["name"] if record else None

if __name__ == "__main__":
    # Example usage (ensure Neo4j is running and accessible)
    # To run this, you'd typically set NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD
    # in your environment or update the defaults.
    app = Neo4jApp(NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD)
    try:
        app.create_person("Alice")
        app.find_person("Alice")
        app.create_person("Bob")
        app.find_person("Bob")
    finally:
        app.close()