Transactions

A transaction groups writes so they commit together or not at all. The high-level API wraps this in transaction() and batch(); the low-level Database API exposes begin, commit, and rollback directly.

High-level transactions (Kite)

The high-level Kite API supports explicit transactions for batching multiple operations into a single commit. When the callback completes, the transaction commits; on error it rolls back.

1import { kite } from '@kitedb/core';23const db = await kite('./my.kitedb', { nodes: [User], edges: [follows] });45await db.transaction(async (ctx) => {6  const alice = ctx.insert('user').values('alice', { name: 'Alice' }).returning();7  const bob = ctx.insert('user').values('bob', { name: 'Bob' }).returning();8  ctx.link(alice.id, 'follows', bob.id, { since: 2024 });9});

Batch operations

A batch runs its operations in a single transaction, so it is atomic and pays the commit cost once. Use it for ingestion, such as indexing a codebase.

1// Batch with builder/executor operations (sync)2db.batch([3  db.insert('user').values('alice', { name: 'Alice' }),4  db.insert('user').values('bob', { name: 'Bob' }),5  () => db.link(aliceId, 'follows', bobId, { since: 2024 }),6]);

Isolation and conflicts

Transactions are snapshot-isolated (MVCC, on by default since 0.3.0): a transaction reads the database as of its begin, plus its own writes, and never sees a later commit. Reads outside a transaction see the latest committed state.

Write transactions on different threads run at the same time. A commit fails with a conflict if a key the transaction read or wrote was changed by a commit since the transaction began. Nothing from the failed transaction is applied and the transaction has ended, so run it again. Rust returns KiteError::Conflict, Python raises ConflictError, and JavaScript throws an Error whose message contains conflict on keys. Writers that touch different nodes and edges don't conflict. In Node.js, JS on the main thread runs one transaction at a time per handle, so its commits can only conflict with work on other threads, such as importFromJsonAsync().

1function isConflict(e: unknown): boolean {2  return e instanceof Error && e.message.includes('conflict on keys');3}45for (let attempt = 1; ; attempt++) {6  try {7    db.transaction((ctx) => {8      const update = ctx.update('user', 'alice');9      update.set('status', 'active');10      update.execute();11    });12    break;13  } catch (e) {14    // Nothing was applied; run the transaction again15    if (!isConflict(e) || attempt === 5) throw e;16  }17}

Opening with mvcc: false (Rust .mvcc(false), Python OpenOptions(mvcc=False)) is deprecated and will be removed in a later release. In that mode write transactions run one at a time, a second writer's begin waits for the first to finish, and transactions read the latest committed state instead of a snapshot. See Concurrency.

Bulk load (max throughput)

A bulk-load transaction is the fastest way to load data, with MVCC or without it. It runs alone among writers: it waits for open write transactions to finish, and write transactions that begin while it is open wait for it. Readers never wait for it. Reads outside a transaction see the whole load once it commits; a read transaction that began before the commit does not see it. If read transactions are open when it commits, the commit records version history for them, which takes time proportional to the size of the load. Use it for one-shot ingest or ETL jobs.

1import { Database } from '@kitedb/core';23const db = Database.open('./my.kitedb');4db.beginBulk();5const nodeIds = db.createNodesBatch(keys); // keys: Array<string | null>6db.addEdgesBatch(edges); // edges: { src, etype, dst }[]7db.addEdgesWithPropsBatch(edgesWithProps);8db.commit();

Choose a write path

Current limitations

• Traversal and path queries read the committed view. If you need to traverse newly written edges, commit first.
• JavaScript batch() is synchronous; avoid async work inside a batch (do async work first, then batch the writes).

Basic transactions

1import { Database, PropValueType } from '@kitedb/core';23const db = Database.open('./my.kitedb');45// Begin a read-write transaction6db.begin();78try {9  // All operations are part of the transaction10  const nodeId = db.createNode('user:alice');11  db.setNodePropByName(nodeId, 'name', {12    propType: PropValueType.String,13    stringValue: 'Alice',14  });1516  // Commit the transaction17  db.commit();18} catch (e) {19  // Rollback on error20  db.rollback();21  throw e;22}

Read-only transactions

A read-only transaction reads one snapshot, as of its begin, for as long as it is open. Keep it short: while any transaction is open, commits record version history for it, and garbage collection can't remove that history until it ends.

1// Begin a read-only transaction2db.begin(true);34const node = db.get_node_by_key('user:alice');5const props = node !== null ? db.get_node_props(node) : null;67// Read-only transactions still need to be ended8db.commit();  // or db.rollback() - same effect for read-only

Transaction status

1// Check if there's an active transaction2if (db.hasTransaction()) {3  console.log('Transaction is active');4}56// The Kite high-level API auto-manages transactions7// and also supports explicit db.transaction()/db.batch()

Next steps

• High-level API: the full transaction API
• MVCC and transactions: how transactions are isolated