Kepo, the Cocoon mascot

Cocoon

A document database for Dart & Flutter that lives on disk, not in your RAM.

Firestore-style collections · typed models · protobuf-packed docs · real indexes

Kepo keeps your data wrapped up tight on disk until you need it.

"Wait, SQLite? So it's SQL?" Nope. You never write a query string, a table or a join. Cocoon is a NoSQL document store, the Firestore way: collections, documents, subcollections. SQLite is only the engine room (a crash-safe single file). Firestore runs on Spanner and nobody writes Spanner SQL; same deal.

Documentation: docs.page/redfieldchristabel/butterfly/libraries/cocoon (Getting Started · Performance & benchmarks · Migrations)

Why Cocoon

  • Documents, not rows. Paths like accounts/{accountId}/txns, and set / get / add / watch on them. Your Dart class is the schema, no Map<String, Object?> anywhere.
  • Tiny on disk. Documents are stored as canonical protobuf, about 125 B for a typical transaction doc.
  • Indexes that actually index. Indexed fields are mirrored into typed columns, pages are keyset cursors (no OFFSET), and a query only runs when an index serves it.
  • RAM stays flat. Data is never loaded wholesale; only a bounded cache of hot documents lives in memory.
  • Prefs & single models. db.prefs for primitives, db.single for one typed model (the current user, say), preload() for synchronous reads.
  • Migrations you don't write. Field numbers are pinned by name in a committed cocoon.lock; reorder or add fields freely, and a type change needs one conversion line.
  • Native platforms only, no web. Android, iOS, macOS, Linux and Windows (the wire codec needs a 64-bit int).

Install

dart pub add cocoon
dart pub add --dev cocoon_generator build_runner

That's all, in Flutter apps too: SQLite is bundled automatically through package:sqlite3's build hook, so don't add sqlite3_flutter_libs. A runnable tour of the core API lives in example/main.dart.

Quick start

// lib/models.dart
import 'package:cocoon/cocoon.dart';

part 'models.cocoon.dart';

@Collection('accounts')
class Account {
  const Account({required this.name});
  @Indexed()
  final String name;
}

@Collection('accounts/{accountId}/txns')
@Index(['accountId', '-bookedOn'])
class Txn {
  const Txn({required this.bookedOn, required this.amountMinor});
  final int bookedOn; // yyyymmdd
  final int amountMinor; // minor units
}
dart run cocoon_generator:migrate  # writes the initial cocoon.lock
dart run build_runner build -d     # writes the adapters and typed handles

(The one-time build.yaml that points build_runner at the lock is in Getting Started.)

// bin/main.dart
import 'package:cocoon/cocoon.dart';
import 'package:my_app/models.dart';

Future<void> main() async {
  final db = await Cocoon.open('app.cocoon', collections: [accounts, txns]);

  final a1 = db.collection(accounts).doc('a1');
  await a1.set(const Account(name: 'Acme')); // upsert
  final snap = await a1.get(); // DocSnapshot<Account>? (null when missing)
  print(snap?.data.name);

  await a1.collection(txns).add(
    const Txn(bookedOn: 20261111, amountMinor: -1250),
  ); // fresh UUIDv7 id

  final recent = a1.collection(txns)
      .orderBy(Txn$.bookedOn, descending: true)
      .limit(50);
  final page = await recent.get(); // QueryPage<Txn>: .docs, .nextCursor
  print(page.docs.length);

  final live = recent.watch().listen((page) => print(page.docs.length));
  await live.cancel();
  await db.close();
}

1,000,000 transactions later

Latest 50 transactions for one account at 1M: drift 0.5 ms, Cocoon 0.7 ms, ObjectBox 44.4 ms, Isar 55.5 ms, Hive CE 710.5 ms, sembast 796.3 ms

Only hand-written SQL (drift) beats it, and drift gives you rows, not typed documents. Memory stays flat too: +2 MB after the read workloads, where Hive holds 2.1 GB and sembast 2.3 GB.

Where it loses, honestly: bulk import trails Isar 2.2x, and gets by id trail Hive's in-RAM lookups. Every workload, with the losses spelled out, is on the Performance page and in benchmarks/cocoon_rivals/RESULTS.md.

What happens when you write

What set() does: your object, canonical protobuf bytes, a row with typed index columns, the index entry, the change log, then watches fire after the commit

You call set(). Cocoon encodes the object as canonical protobuf, writes the row, its index entries and a change-log row in one SQLite transaction, then wakes only the watches on that collection.

Learn more

Everything below lives on docs.page.

Status

The storage engine, change log, realtime watches, cocoon_generator codegen (with the interactive migrate command), the on-device migration runner and the DevTools inspector are in. See doc/design.md.

Development

From the Butterfly workspace root:

dart pub get
cd packages/cocoon
dart analyze
dart test

Libraries

cocoon
A typed, disk-backed, Firestore-style local database built on SQLite.