Sessions and Transactions

Sessions

Through the Driver, we open Sessions.

It is important to remember that sessions are not the same as database connections. When the Driver connects to the database, it opens up multiple TCP connections that can be borrowed by the session. A query may be sent over multiple connections, and results may be received by the driver over multiple connections.

Instead, sessions should be considered a client-side abstraction for grouping units of work, which also handle the underlying connections. The connections themselves are managed internally by the driver and are not directly exposed to the application.

To open a new session, call the session() method on the driver.

with driver.session() as session:

This session method takes an optional configuration argument, which can be used to set the database to run any queries against in a multi-database setup, and the default access mode for any queries run within the transaction.

with driver.session(database="people") as session:

If no database is supplied, the default database will be used. This is configured in the dbms.default_database in neo4j.conf, the default value is neo4j. You cannot create multiple databases in Neo4j Aura or in Neo4j Community Edition.

For more information on multi-database setup, see Managing Multiple Databases.

The default access mode is set to write, but this can be overwritten by explicitly calling the execute_read() or execute_write() functions.

Transactions

Through a Session, we can run one or more Transactions.

There are three types of transaction exposed by the driver:

session.run(
    "MATCH (p:Person {name: $name}) RETURN p", # Query
    name="Tom Hanks" # Named parameters referenced
)                    # in Cypher by prefixing with a $

# Define a Unit of work to run within a Transaction (`tx`)
def get_movies(tx, title):
    return tx.run("""
        MATCH (p:Person)-[:ACTED_IN]->(m:Movie)
        WHERE m.title = $title // (1)
        RETURN p.name AS name
        LIMIT 10
    """, title=title)

# Execute get_movies within a Read Transaction
session.execute_read(get_movies,
    title="Arthur" # (2)
)

# Call tx.run() to execute the query to create a Person node
def create_person(tx, name):
    return tx.run(
        "CREATE (p:Person {name: $name})",
        name=name
    )


# Execute the `create_person` "unit of work" within a write transaction
session.execute_write(create_person, name="Michael")

Manually Creating Transactions

It is also possible to explicitly create a transaction object by calling the begin_transaction() function on the session.

with session.begin_transaction() as tx:
    # Run queries by calling `tx.run()`

This returns a Transaction object identical to the one passed in to the unit of work function when calling execute_read() or execute_write().

This method differs from the execute_read and execute_write() functions, in that the transaction will have to be manually committed or rolled back depending on the outcome of the unit of work.

You can commit a transaction by calling the tx.commit() function, or roll back the transaction by calling tx.rollback().

try:
    # Run a query
    tx.run(query, **params)

    # Commit the transaction
    tx.commit()
except:
    # If something goes wrong in the try block,
    # then rollback the transaction
    tx.rollback()

Closing the Session

Once you are finished with your session, you call the close() method to release any database connections held by that session.

# Close the session
session.close()

A Working Example

def create_person_work(tx, name):
    return tx.run("CREATE (p:Person {name: $name}) RETURN p",
        name=name).single()

def create_person(name):
    # Create a Session for the `people` database
    session = driver.session(database="people")

    # Create a node within a write transaction
    record = session.execute_write(create_person_work,
                                    name=name)

    # Get the `p` value from the first record
    person = record["p"]

    # Close the session
    session.close()

    # Return the property from the node
    return person["name"]

Check your understanding