---
title: Overview & Why Cocoon
description: >-
  A typed, disk-backed, Firestore-style local database for Dart and Flutter,
  built on SQLite. Standalone, no Butterfly packages needed.
---
> ## 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.

<div style={{ textAlign: "center" }}>
  <img src="https://raw.githubusercontent.com/redfieldchristabel/butterfly/master/packages/cocoon/doc/kepo.png" alt="Kepo, the Cocoon mascot" width="180" />
</div>

**Cocoon** (`package:cocoon`) is a typed, disk-backed, Firestore-style local
database for Dart and Flutter, built on SQLite. Collections, documents and
subcollections (`accounts/{accountId}/txns`), indexed queries with keyset
pagination, SQLite-computed aggregates and group-by, bulk loads and batch
reads by id, realtime watches backed by a durable change log, and whole-file
backups — with your model classes as the schema. A key-value store for
one-of-a-kind values (`db.prefs`, `db.single`) lives in the same file too —
see [Prefs & Single Models](/libraries/cocoon/prefs).

<Info>
  <Icon name="plug" /> **Standalone:** Cocoon depends on no other Butterfly
  package and not on Flutter — pure Dart on `sqlite_async`. It works in
  Flutter apps, Dart servers and CLIs alike.
</Info>

## Why Cocoon exists

Nothing in Dart today gives all four of these at once:

| | Typed | On disk (bounded RAM) | Real queries | Firestore-style API |
| --- | --- | --- | --- | --- |
| sembast | no (`Map`) | no (whole DB in RAM) | yes | yes |
| Hive CE | yes | normal boxes load everything | no | no |
| drift | yes | yes | yes | no (tables + SQL) |
| Isar | yes | yes | yes | close, but stalled |
| ObjectBox | yes | yes | yes | closed core, license limits |
| **Cocoon** | **yes** | **yes (LRU cache)** | **yes (index rule)** | **yes** |

- **sembast** keeps every document in RAM forever — fine for small caches,
  not for years of transactions.
- **Hive CE** normal boxes also load everything into memory and cannot query
  beyond key lookups.
- **drift** is excellent but its API is tables and SQL, not a document tree.
- **Isar 3** development has stalled; **ObjectBox** has a closed core.

Cocoon's answer: store documents as canonical protobuf blobs in SQLite, copy
indexed fields into real typed columns at write time, and enforce a
Firestore-style index rule over them.

## The 30-second version

```dart
final db = await Cocoon.open(file, collections: [accounts, txns, splits]);

final a1 = db.collection(accounts).doc('a1'); // root: CollectionRef<Account>
await a1.set(Account(
  name: 'Acme',
  openedAt: DateTime.utc(2026, 1, 1),
  balanceMinor: 0,
  active: true,
)); // upsert

final txRef = await a1.collection(txns).add(txn); // id = UUIDv7
final snap = await txRef.get(); // DocSnapshot<Txn>? (null when missing)

await a1.delete(); // deletes a1 AND its whole subtree
```

The models above come from annotating plain Dart classes; `cocoon_generator`
writes the adapters, typed query handles (`Txn$.bookedOn`) and codecs. See
[Models & Code Generation](/libraries/cocoon/models).

## Installation

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

That's all, in Flutter apps too: the native SQLite is bundled
automatically. The full walkthrough — install, first model,
codegen, open, first query and watch — is in
[Getting Started](/libraries/cocoon/getting-started).

## The native SQLite library

Cocoon talks to SQLite through `sqlite_async` on top of `package:sqlite3`
(FFI). **There is nothing to install**, for Flutter apps and Dart
CLIs/servers alike: `package:sqlite3` 3.x bundles a precompiled SQLite into
the app through its build hook on Android, iOS, macOS, Linux and Windows
(downloaded from that package's GitHub releases at build time; its docs cover
compiling SQLite yourself or switching to SQLCipher).

<Warning>
  **Don't add `sqlite3_flutter_libs`.** It was needed with sqlite3 2.x; since
  3.x sqlite3's own upgrade guide says to drop it. If another package in your app still pulls in `sqlite3_flutter_libs` 0.5.x (the old, 2.x-era version with its own build scripts), upgrade it to `^0.6.0`, which is an empty placeholder, so only one SQLite ships.
</Warning>

<Warning>
  **Native platforms only.** The wire codec relies on Dart's native 64-bit
  `int`; there is no web build.
</Warning>

## Where to go next

<CardGroup cols={2}>
  <Card title="Getting Started" icon="rocket" href="/libraries/cocoon/getting-started">
    Install, first model, codegen, open, first query and watch.
  </Card>
  <Card title="Models & Code Generation" icon="tags" href="/libraries/cocoon/models">
    Annotate plain classes; let `cocoon_generator` write the rest.
  </Card>
  <Card title="Collections & Documents" icon="folder-tree" href="/libraries/cocoon/collections">
    Refs, subcollections, cascade deletes and transactions.
  </Card>
  <Card title="Prefs & Single Models" icon="sliders" href="/libraries/cocoon/prefs">
    A key-value store and one-model helpers in the same file, with synchronous reads after a preload.
  </Card>
  <Card title="Queries & Indexes" icon="magnifying-glass" href="/libraries/cocoon/queries">
    Filters, ordering, the index rule and keyset pagination.
  </Card>
  <Card title="Aggregates & Group By" icon="calculator" href="/libraries/cocoon/aggregates">
    Totals in SQLite with Firestore semantics, plus the groupBy extension.
  </Card>
  <Card title="Bulk Loads & Batch Reads" icon="boxes" href="/libraries/cocoon/bulk">
    bulkWriter(), db.batch() and getAll for import-shaped work.
  </Card>
  <Card title="Realtime" icon="bolt" href="/libraries/cocoon/realtime">
    Doc and query watches, plus the durable change log.
  </Card>
  <Card title="Schema Migrations" icon="arrows-rotate" href="/libraries/cocoon/migrations">
    The interactive `migrate` command and the on-device runner.
  </Card>
  <Card title="Backup & Restore" icon="box-archive" href="/libraries/cocoon/backup">
    Consistent copies of a live database, verified restores, the instance id.
  </Card>
  <Card title="Performance" icon="chart-line" href="/libraries/cocoon/performance">
    The rivals benchmark at 1M transactions, the honest losses, the knobs.
  </Card>
  <Card title="Internals" icon="screwdriver-wrench" href="/libraries/cocoon/internals">
    Storage layout, the canonical wire format and money guidance.
  </Card>
</CardGroup>
