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.

// Open a new session
const session = driver.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 (either READ or WRITE).

import neo4j, { session } from 'neo4j-driver'

// ...

// Create a Session for the `people` database
const session = driver.session({
  // Run sessions in WRITE mode by default
  defaultAccessMode: session.WRITE,
  // Run all queries against the `people` database
  database: 'people',
})

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 executeRead() or executeWrite() methods.

Transactions

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

There are three types of transaction exposed by the driver:

// Run a query in an auto-commit transaction
const res = await session.run(query, params)

// Run a query within a Read Transaction
const res = await session.executeRead(tx => {
  return tx.run(
    `MATCH (p:Person)-[:ACTED_IN]->(m:Movie)
    WHERE m.title = $title // (1)
    RETURN p.name AS name
    LIMIT 10`,
    { title: 'Arthur' } // (2)
  )
})

const res = await session.executeWrite(tx => {
  return tx.run(
    'CREATE (p:Person {name: $name})',
    { name: 'Michael' }
  )
})

Manually Creating Transactions

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

import neo4j, { session } from 'neo4j-driver'

// ...

// Open a new session
const session = driver.session({
  defaultAccessMode: session.WRITE
})

// Manually create a transaction
const tx = session.beginTransaction()

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

This method differs from the executeRead and executeWrite() methods, 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() method, or roll back the transaction by calling tx.rollback().

try {
  // Perform an action
  await tx.run(query, params)

  // Commit the transaction
  await tx.commit()
}
catch (e) {
  // If something went wrong, rollback the transaction
  await tx.rollback()
}
finally {
  // Finally, close the session
  await session.close()
}

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
await session.close()

A Working Example

async function createPerson(name) {
  // Create a Session for the `people` database
  const session = driver.session({
    // Run sessions in WRITE mode by default
    defaultAccessMode: session.WRITE,
    // Run all queries against the `people` database
    database: 'people',
  })

  // Create a node within a write transaction
  const res = await session.executeWrite(tx => {
    return tx.run('CREATE (p:Person {name: $name}) RETURN p', { name })
  })

  // Get the `p` value from the first record
  const p = res.records[0].get('p')

  // Close the sesssion
  await session.close()

  // Return the properties of the node
  return p.properties
}

Check your understanding