Sessions and transactions

Neogma provides instance methods for managing Neo4j sessions and transactions. These handle lifecycle, cleanup, and error handling automatically.

Sessions

Use neogma.getSession to acquire a session that is automatically closed when the callback completes:

await neogma.getSession(async (session) => {
  const user = await Users.createOne({ id: '1', name: 'Alice' }, { session });
  console.log(user.name);
});
// session is closed automatically

Transactions

Use neogma.getTransaction for operations that should be atomic. If the callback throws, the transaction is rolled back:

await neogma.getTransaction(async (tx) => {
  await Users.createOne({ id: '1', name: 'Alice' }, { session: tx });
  await Orders.createOne({ id: 'order-1', status: 'pending' }, { session: tx });
  // Both operations commit together, or both roll back on error
});

Rollback on error

try {
  await neogma.getTransaction(async (tx) => {
    await Users.createOne({ id: '1', name: 'Alice' }, { session: tx });
    throw new Error('Something went wrong');
    // Transaction is automatically rolled back
  });
} catch (error) {
  console.log('Transaction rolled back:', error.message);
}

Runnables

neogma.getRunnable returns either a session or transaction depending on what was passed:

async function createUser(
  data: { id: string; name: string },
  sessionOrTx?: any,
) {
  return neogma.getRunnable(
    sessionOrTx,
    async (runnable) => {
      return Users.createOne(data, { session: runnable });
    },
  );
}

// Works with or without a transaction
await createUser({ id: '1', name: 'Alice' }); // uses its own session
await neogma.getTransaction(async (tx) => {
  await createUser({ id: '2', name: 'Bob' }, tx); // uses the transaction
});

Passing sessions to model operations

Most model methods accept an optional session parameter:

await neogma.getSession(async (session) => {
  // Create
  await Users.createOne({ id: '1', name: 'Alice' }, { session });

  // Find
  const users = await Users.findMany({ where: { name: 'Alice' }, session });

  // Update
  await Users.update({ name: 'Alicia' }, { where: { id: '1' }, session });

  // Delete
  await Users.delete({ where: { id: '1' }, detach: true, session });
});

Database selection

Specify a database when creating the Neogma instance:

const neogma = new Neogma({
  url: 'bolt://localhost:7687',
  username: 'neo4j',
  password: 'password',
  database: 'my-database',
});

Sessions and Transactions