Skip to content

Guides

Performance checklist

Choose the fastest write path and config presets

Use this checklist to pick a write path and a durability preset for your workload. Most write-path gains come from three things: fewer WAL syncs, fewer per-operation allocations, and larger batches.

Decision matrix

GoalBest path
Fastest ingestbeginBulk() + batch APIs
Atomic writestransaction() / batch()
Several writer threadssyncMode: 'Normal' (concurrent commits are written together); retry conflicting commits
Strong durability per commitsyncMode: 'Full'
Throwaway or test datasyncMode: 'Off'

Bulk ingest (fastest path)

A bulk-load transaction works with MVCC (the default): for 200k nodes and 1M edges with 2 properties each, loaded in batches of 5,000, it ran at 2.88M/s for nodes and 1.00M/s for edges on an Apple M5 Pro, against 2.90M/s and 975K/s with MVCC off. It runs alone among writers (it waits for open write transactions, and new ones wait for it), and readers never wait for it. A read transaction left open across the load slows its edge inserts, because the load's commits record version history for that reader (615K/s for edges in the same test, with nodes at 2.95M/s). Use it for one-shot ingest or ETL jobs.

TypeScript
import { Database } from '@kitedb/core';const db = Database.open('./my.kitedb');db.beginBulk();const nodeIds = db.createNodesBatch(keys);db.addEdgesBatch(edges);db.addEdgesWithPropsBatch(edgesWithProps);db.commit();

Config presets

PresetSettings
Single-writer ingestsyncMode: 'Normal', default WAL and checkpoint settings
Several writer threadssyncMode: 'Normal', chunked batches
Max durabilitysyncMode: 'Full', smaller batches
Fast reopen, bounded memorycheckpointLogBudget: 32 * 1024 * 1024 (as recommendedReopenHeavyProfile() sets, with a 16 MB WAL)
Max speed (test)syncMode: 'Off'

Checklist

  • Use batch APIs: createNodesBatch, addEdgesBatch, addEdgesWithPropsBatch
  • Prefer beginBulk() for ingest; commit in chunks
  • Don't hold read transactions open across a bulk load
  • Keep the default 4 MB WAL for large ingest: a full WAL spills into WAL segments, and checkpoints run on the database's checkpoint thread. A larger WAL means fewer spills, but it also raises the floors of the checkpoint trigger (3/8 of the WAL), the segment limit (16 WALs) and the segment extent (2 WALs): more log, and more memory, before a small database checkpoints
  • Leave auto-checkpoint on. With it off, writes fail once the WAL segments reach walSegmentLimit, or fill the segment table (63 extents: with default extents, about four times a limit up to 512 MiB, and 2 GiB beyond); to hold a whole load and checkpoint once at the end, raise the limit, and walSegmentSize with it past that
  • Lower checkpointLogBudget (default 128 MiB) to bound memory and reopen replay time; raise checkpointLogRatio to checkpoint less often on a large database. checkpointThreshold is deprecated and has no effect
  • Use low-level API for hot paths in JS/TS
  • Avoid per-edge property sets when you can batch props with the edge

Verify with benchmarks