---
title: Performance
description: >-
  Cocoon against drift, Isar, ObjectBox, Hive CE and sembast up to 1,000,000
  transactions - the wins, the honest losses, and the tuning knobs that trade
  one for the other.
---
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.page/redfieldchristabel/butterfly/llms.txt
> Use this file to discover all available pages before exploring further.

`benchmarks/cocoon_rivals` benchmarks Cocoon against the engines a big
on-device app would actually pick — drift (plain SQLite, the speed limit),
Isar, ObjectBox, Hive CE and sembast, plus Cocoon itself at
`Durability.normal` — on the same finance-shaped data, four sizes up to
1,000,000 transactions. Every run is a fresh process, every number is the
median of three runs, every memory number is measured against a bare-harness
baseline, and every rival's results are diffed against Cocoon's before any
timing counts. Full tables and per-workload verdicts:
[RESULTS.md][cocoon-results].

## The headline numbers at 1,000,000 transactions

<p align="center"><img src="https://raw.githubusercontent.com/redfieldchristabel/butterfly/master/packages/cocoon/doc/gifs/cocoon_latest50_race.gif" alt="Latest 50 for one account at 1M transactions, as a race against the clock" width="720" /></p>

<p align="center"><img src="https://raw.githubusercontent.com/redfieldchristabel/butterfly/master/packages/cocoon/doc/gifs/cocoon_ram.gif" alt="Extra RAM after the read workloads: drift -25 MB, Cocoon +2 MB, Isar +305 MB, ObjectBox +546 MB, Hive CE +2.1 GB, sembast +2.3 GB" width="720" /></p>

The full table:

| Workload | Cocoon | drift | Isar | ObjectBox | Hive CE | sembast |
|---|---|---|---|---|---|---|
| One account's latest 50, p50 (ms) | **0.7** | 0.5 | 55.5 | 44.4 | 710.5 | 796.3 |
| Month range, all accounts, paged (ms) | **308** | 2,588 | 6,534 | 12,478 | 621 | 102,646 |
| Year report, all accounts (ms) | **376** * | 358 | 1,928 | 1,830 | 326 | 1,131 |
| 50 biggest debits, p50 (ms) | **1.3** | 0.8 | 25.5 | 69.1 | 638.6 | 10,374.8 |
| Status search, p50 (ms) | **1.4** | 0.8 | 85.3 | 65.6 | 645.2 | 1,242.3 |
| 1,000 random gets by id (ms) | 94 (**8.7 with `getAll`**) | 79 | 6,656 | 10 | 5 | 573 |
| Bulk import, each engine's best bulk API (s) | **12.6** | 18.7 | 5.7 | 8.8 | 7.9 | 46.5 |
| RAM after the read workloads, over the harness floor (MB) | **+2** | −25 | +305 | +546 | +2,057 | +2,298 |
| Read-while-write latest-50, p95 (ms) | **3.2** | 4.3 | 67.1 | 50.4 | 760.8 | 1,049.7 |

\* The matrix run measured Cocoon's year report at 1,419 ms — it summed in
Dart. Since then `aggregate()`/`groupBy()` push the math into SQL: 376 ms
against drift's 358 ms `GROUP BY`, at parity within noise. See
[Aggregates & Group By](/libraries/cocoon/aggregates).

What holds at 1M: indexed reads stay flat while the in-RAM engines scan
(Cocoon answers every indexed query in 0.7-3.6 ms, flat from 10k to 1M), RAM
after the reads sits at the harness floor where Hive holds 2.1 GB and sembast
2.3 GB, cold open is 152 ms where Hive needs 5.2 s and sembast 8.0 s, and a
single write is 1,885 µs p50 at `Durability.full` against drift's 2,975 µs
(`Durability.normal`: 450 µs — still crash-safe, may lose the last moments on
power loss).

## How it scales: 10k to 1M

Cocoon's own numbers at every measured size (same matrix run). Indexed reads
and cold open stay flat while the data grows 100x; only the work that has to
touch every matching row grows with it.

| Workload | 10k | 100k | 300k | 1M |
|---|---|---|---|---|
| One account's latest 50, p50 (ms) | 0.7 | 0.7 | 0.8 | 0.7 |
| Status search, p50 (ms) | 1.3 | 1.2 | 1.2 | 1.4 |
| 50 biggest debits, p50 (ms) | 1.3 | 1.2 | 1.4 | 1.3 |
| Page 20 of one account's history (ms) | — | 0.9 | 0.7 | 0.9 |
| Count pending, p50 (ms) | 0.4 | 0.7 | 1.2 | 3.6 |
| Read-while-write latest-50, p95 (ms) | 2.5 | 2.6 | 2.5 | 3.2 |
| Cold open (ms) | 153 | 153 | 150 | 152 |
| Single write at `Durability.full`, p50 (µs) | 2,016 | 1,980 | 1,942 | 1,885 |
| Month range, all accounts, paged (ms) | 32 | 85 | 140 | 308 |
| Bulk import via `bulkWriter()` (s) | 0.2 | 1.1 | 3.4 | 12.6 |
| RAM after the read workloads, over the harness floor (MB) | −16 | −12 | −6 | +2 |

At 10k the deep-page walk never reaches page 20 (accounts are too short), so
that cell is empty. Every rival's column at every size is in
[RESULTS.md][cocoon-results].

## How it was measured

- **Machine:** Intel Core Ultra 5 325 (8 cores), 27 GB RAM, Dart 3.13.7,
  SQLite 3.54.1, run one process at a time as a Foreman job.
- **Data:** finance-shaped accounts and transactions (amounts, statuses,
  booking dates), the same generated dataset for every engine, at 10k, 100k,
  300k and 1M transactions.
- **Fair answers first:** a 500-transaction smoke test asserts every engine
  returns identical, contract-ordered results for every workload, and at
  every size a `verify` dump is diffed against Cocoon's before any timing
  counts. Each engine uses its own documented idiom (offset paging for
  drift, Isar, ObjectBox and sembast; keyset cursors for Cocoon).
- **Noise control:** every run is a fresh process, every number is the
  median of three runs, and memory is reported over a bare-harness baseline
  (450 MB RSS) so the dataset the harness holds is not billed to any engine.
  Import wall times on this disk vary by about ±25%.

The isolate modes (`CocoonIsolate.background` / `auto`) were measured
separately: see [Isolates: Caller, Background, Auto](/libraries/cocoon/isolates).

## File size

| file at 1M transactions | size |
|---|---|
| Cocoon, shipped layout, fresh 1M import via `bulkWriter()` | 307.6 MiB |
| same load, change log pruned (`pruneChanges`/`changeRetention`) | 252.7 MiB |
| pre-2026-11 layout (with the path column), same data | 374.7 MiB |
| drift, same data (reference) | 230.9 MiB |

Per row: the document blob (canonical protobuf) averages 125.1 B, the change
log adds ~52 B per written document until pruned, and the secondary + scope
indexes together 126.4 MB. The full anatomy — what every byte is, and the
layout variants that were measured and rejected:
[STORAGE.md][cocoon-storage].

## Where Cocoon loses, and why

- **Bulk load vs the in-RAM engines.** Isar imports 1M in 5.7 s, Hive 7.9 s,
  ObjectBox 8.8 s — Cocoon's 12.6 s trails them 2.2x / 1.6x / 1.4x. They
  append to append-only stores; SQLite pays fsynced commits that rewrite
  index pages scattered over four secondary indexes — the import writes 61x
  the final file size to disk (Hive and sembast 1x). It still beats drift
  (18.7 s) and sembast (46.5 s), and sits within ~1.4x of raw SQLite's own
  9.5 s deferred-index ceiling ([CEILING.md][cocoon-ceiling]).
- **Gets by id.** 94 ms per 1,000 is 9x behind ObjectBox and 19x behind
  Hive's in-RAM hash lookups (10 and 5 ms): a SQLite round trip plus a wire
  decode against a pointer chase. `getAll` closes most of the gap (8.7 ms
  cold, 0.2 ms warm per 1,000 — see
  [Bulk Loads & Batch Reads](/libraries/cocoon/bulk)).
- **Indexed reads cost 1.4-2x drift's.** The planner and the index are the
  same shape; the gap is decoding documents into typed objects, which plain
  SQL rows skip.
- **The file is ~33% bigger than drift's** (307.6 vs 230.9 MiB at 1M): the
  change log plus the scope/secondary indexes. The blob itself is not the
  problem — Cocoon's protobuf row is *smaller* than drift's JSON columns
  for the same document.
- **The 300k NDJSON restore is 13.0 s vs Hive's 3.1 s** — Hive appends
  lines to a file; Cocoon commits documents through the write path.

## The tuning knobs

Every option at once, with its default or a typical value:

```dart
final db = await Cocoon.open(
  file,
  collections: [accounts, txns, splits], // register every collection once
  options: const CocoonOptions(
    durability: Durability.full, // PRAGMA synchronous; `normal` for speed
    cacheSize: 2000, // bounded LRU of decoded hot documents; 0 disables
    keepChanges: true, // write the change log the watches and sync read
    changeRetention: null, // or ChangeRetention(...) to bound the log
    pageCacheMiB: 64, // PRAGMA cache_size on the writer; readers keep the default; <= 0 = default
    tempStoreInMemory: true, // PRAGMA temp_store = MEMORY
    walAutoCheckpointPages: 8000, // PRAGMA wal_autocheckpoint; <= 0 = default
    compactAfterUpgrade: true, // VACUUM once after a storage-format upgrade that left > 1/5 of the file free
    onMissingIndex: MissingIndexMode.throwError, // or .scanAndWarn: debug-only full-scan fallback (asserts on) that logs once per index and fills db.missingIndexes
  ),
);
```

The knobs of `CocoonOptions`, with their measured trade-offs:

- **`durability: Durability.normal`** — skips the per-commit fsync. Single
  writes at 100k: p50 2,032 → 483 µs (4.2x). Still durable against
  application crashes (WAL); on power loss the last commits may be lost.
  Keep `full` for money data that must survive a power cut.
- **`keepChanges: false`** — stops writing the on-disk change log: ~11%
  faster single writes, and at 1M the log is 52.2 MB of the file. Only for
  databases where nothing needs `changesSince` (in-process `watch()`
  streams keep working). For databases where something does,
  **`changeRetention`** (`ChangeRetention(maxChanges:, maxAge:)`) bounds
  the log instead — small batched deletes after commits — the difference
  between a 305 MB and a 253 MB file at 1M. See
  [Realtime: Watches & Change Log](/libraries/cocoon/realtime).
- **`cacheSize`** — the LRU of decoded documents. It is a cap, not a
  pre-allocation: RAM follows the working set. A warm 1,000-document
  working set reads 50x faster than cold SQLite round-trips (113 → 2 ms),
  and raising `cacheSize` beyond the working set (2000 → 20000) measured no
  speed gain and no RSS gain. Raise it only to keep a larger hot set
  cached; lower it (or `0`) to shrink the ceiling.
- **`pageCacheMiB`** (default 64) — the SQLite page-cache budget on the
  writer connection (readers keep SQLite's default, so the memory is paid
  once). SQLite's own 2 MB default cannot hold the hot upper levels of a
  six-B-tree table once the file outgrows it, and bulk imports pay for the
  re-reads: the raw-SQLite probe put the 1M per-1000-row commit cost at
  63.2 s with the default and 43.5 s with 64 MB. `<= 0` keeps SQLite's
  default.
- **`tempStoreInMemory`** (default on) — temp B-trees (sorts, spilling
  index maintenance) stay in RAM: 43.5 → 35.6 s on top of the 64 MB page
  cache at 1M.
- **`walAutoCheckpointPages`** (default 8000 = 32 MiB) — how much WAL
  accumulates before SQLite checkpoints it into the database file.
  SQLite's own 1000 pages (~4 MiB) checkpoints after nearly every commit
  of a bulk import at a cost that grows with the database; raising the
  interval roughly halved the raw 1M import (45.6 → ~19-24 s) with the WAL
  bounded at ~36 MB. Disabling checkpoints outright was measured and
  rejected (an unbounded 4.2 GB WAL). `<= 0` keeps SQLite's default.
- **`compactAfterUpgrade`** (default on) — a storage-format upgrade leaves
  the dropped tables' pages on the freelist; the open compacts once when
  more than a fifth of the file is free. See
  [Schema Migrations](/libraries/cocoon/migrations).

The bulk-load knobs — `BulkWriterOptions(chunkSize:)`, `deferIndexes`,
`logChanges` — are covered in
[Bulk Loads & Batch Reads](/libraries/cocoon/bulk).

## Reproducing

Every table above comes from `results/*.json` in the benchmark directory;
each file documents its own methodology and reproduce command:

- [RESULTS.md][cocoon-results] — the full matrix, per-workload verdicts.
- [AGGREGATES.md][cocoon-aggregates] — the aggregate pushdown, before/after.
- [IMPORT.md][cocoon-import] — the bulk-write path, chunk curve, levers.
- [CEILING.md][cocoon-ceiling] — raw SQLite's floor and what each lever buys.
- [GETALL.md][cocoon-getall] — the batch-read numbers and the chunk sweep.
- [STORAGE.md][cocoon-storage] — where the bytes go, layout variants.

[cocoon-results]: https://github.com/redfieldchristabel/butterfly/blob/master/benchmarks/cocoon_rivals/RESULTS.md
[cocoon-aggregates]: https://github.com/redfieldchristabel/butterfly/blob/master/benchmarks/cocoon_rivals/AGGREGATES.md
[cocoon-import]: https://github.com/redfieldchristabel/butterfly/blob/master/benchmarks/cocoon_rivals/IMPORT.md
[cocoon-ceiling]: https://github.com/redfieldchristabel/butterfly/blob/master/benchmarks/cocoon_rivals/CEILING.md
[cocoon-getall]: https://github.com/redfieldchristabel/butterfly/blob/master/benchmarks/cocoon_rivals/GETALL.md
[cocoon-storage]: https://github.com/redfieldchristabel/butterfly/blob/master/benchmarks/cocoon_rivals/STORAGE.md
