Skip to content
~/docs/guides/transactions
DOCUMENTATION

Transactions

ACID transactions and isolation levels

KiteDB supports transactions for atomic operations. The low-level API provides explicit transaction control.

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.

typescript
import { kite } from '@kitedb/core';

const db = await kite('./my.kitedb', { nodes: [User], edges: [follows] });

await db.transaction(async (ctx) => {
  const alice = ctx.insert('user').values('alice', { name: 'Alice' }).returning();
  const bob = ctx.insert('user').values('bob', { name: 'Bob' }).returning();
  ctx.link(alice.id, 'follows', bob.id, { since: 2024 });
});

Batch Operations

Batch operations run in a single transaction. This is ideal for fast ingestion (e.g., indexing a codebase) and guarantees atomicity.

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

Bulk Load (Max Throughput)

Bulk-load disables MVCC to minimize per-write overhead. Use for one-shot ingest or ETL jobs; avoid concurrent readers/writers while it runs.

typescript
import { Database } from '@kitedb/core';

const db = Database.open('./my.kitedb');
db.beginBulk();
const nodeIds = db.createNodesBatch(keys); // keys: Array<string | null>
db.addEdgesBatch(edges); // edges: { src, etype, dst }[]
db.addEdgesWithPropsBatch(edgesWithProps);
db.commit();

Choose Your Write Path

GoalRecommended API
Max throughput, single writerbeginBulk() + batch APIs
Atomic ingest w/ MVCCbatch() / transaction()
Multi-writer throughputsyncMode: 'Normal' + group commit + chunked batches

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

typescript
import { Database } from '@kitedb/core';

const db = Database.open('./my.kitedb');

// Begin a read-write transaction
db.begin();

try {
  // All operations are part of the transaction
  const nodeId = db.createNode('user:alice');
  const nameKey = db.getOrCreatePropkey('name');
  db.setNodePropByName(nodeId, 'name', { propType: 'String', stringValue: 'Alice' });
  
  // Commit the transaction
  db.commit();
} catch (e) {
  // Rollback on error
  db.rollback();
  throw e;
}

Read-Only Transactions

typescript
// Begin a read-only transaction (faster, no locking)
db.begin(true);

const node = db.getNodeByKey('user:alice');
const props = db.getNodeProps(node);

// Read-only transactions still need to be ended
db.commit();  // or db.rollback() - same effect for read-only

Transaction Status

typescript
// Check if there's an active transaction
if (db.hasTransaction()) {
  console.log('Transaction is active');
}

// The Kite high-level API auto-manages transactions
// and also supports explicit db.transaction()/db.batch()

Next Steps

./edit --remote