Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/mainser/cindel/llms.txt

Use this file to discover all available pages before exploring further.

Cindel is a Flutter-first local database that gives your application a fully typed, code-generated API over your data — without requiring you to write SQL, manage serialization, or call into an untyped key-value store. You annotate plain Dart classes, run the code generator, and Cindel produces typed collections, query builders, watchers, and migration tooling that work consistently across MDBX (the default), SQLite native, and the experimental SQLite Web/OPFS browser backend.

​
The Four Packages

Cindel is split into four packages with distinct roles so that each part of your project only pulls in what it needs.
PackageRoleAdd as
cindelRuntime API — typed collections, queries, transactions, watchers, sync, and backend loadingdependency
cindel_annotationsPublic annotations (@Collection, @Index, @Embedded, …) and shared schema metadata typesdependency (pulled in transitively by cindel)
cindel_generatorBuild-time source generator — reads annotations and emits the *.g.dart files consumed by the runtimedev_dependency
cindel_flutter_libsPrebuilt native libraries and Web Worker/Wasm runtime assets — bundles everything Flutter needs on each platformdependency
Flutter apps need all four. cindel_flutter_libs carries no public Dart API of its own; it is present so Flutter’s platform build can locate and bundle the correct native library or Web runtime assets automatically.

​
Key Features

Generated Typed API

Annotate your Dart models and run build_runner. The generator emits typed collection accessors, where() index helpers, filter() query builders, sorting, pagination, projections, aggregates, and natural-key upsert helpers — all strongly typed at compile time.

MDBX Performance

MDBX is the default native backend. It is Cindel’s reference implementation and the backend targeted by insert-path and hydration optimizations. SQLite native can be selected explicitly when you need it.

SQLite Compatibility

Select CindelStorageBackend.sqlite at open time to switch to SQLite on native platforms. The same generated typed app code, queries, transactions, and watchers work unchanged — the backend adapts internally.

Flutter Web (OPFS)

Flutter Web uses SQLite in a dedicated Worker with OPFS persistence. Cindel.open(...) loads the packaged Worker and Wasm assets from cindel_flutter_libs automatically. Generated typed CRUD, queries, transactions, and single-tab watchers are the supported Web path.

Migrations

Pass a CindelMigrationPlan to Cindel.open at every app start. Cindel stores the data version inside the database, skips completed steps, and opens the final handle with target schemas after a successful migration. Export, import, verify-before, verify-after, and compaction hooks are available.

Sync

Experimental local-first sync is configured only at open time through CindelSyncConfig. App code keeps using the same typed collections and queries; Cindel records mutations in an internal durable outbox and runs an internal scheduler against your CindelSyncAdapter.

​
Architecture Overview

Working with Cindel follows four steps that stay consistent across every platform and backend:
  1. Annotate — Add @Collection, @Index, @Embedded, and related annotations to your Dart model classes.
  2. Generate — Run dart run build_runner build to produce *.g.dart files containing schemas, serializers, typed collection accessors, and query helpers.
  3. Open — Call Cindel.open(directory: path, schemas: [YourSchema]) to get a CindelDatabase handle. Pass a CindelMigrationPlan for versioned schema changes, or CindelSyncConfig to enable sync.
  4. Use — Access db.yourCollection for fully typed reads, writes, queries, transactions, and watchers. The same call surface works whether the backend is MDBX, SQLite native, or SQLite Web/OPFS.
// Annotate
@Collection(name: 'users')
class User {
  Id dbId = autoIncrement;

  @Index(unique: true)
  late String email;
}

// Generate (terminal)
// dart run build_runner build --delete-conflicting-outputs

// Open
final db = await Cindel.open(
  directory: directory.path,
  schemas: [UserSchema],
);

// Use
await db.users.put(User()..email = 'ada@example.com');
final user = await db.users.where().emailEqualTo('ada@example.com').findFirst();

​
Pre-1.0 Status

Cindel is in active pre-1.0 development. The public typed API and storage format can still change while backend parity, Web behavior, and release packaging are finalized. Keep the cindel and cindel_flutter_libs package versions aligned, because the Dart runtime expects a matching native ABI from the companion package. Review the changelog before upgrading across minor versions.

​
Next Steps

Quickstart

Add Cindel to a Flutter project, define a model, run the generator, and perform your first typed read and write in under 5 minutes.

Installation

Detailed setup for Flutter apps, pure Dart tools, Freezed models, and platform-specific native library requirements.

Build docs developers (and LLMs) love

Get started for freeTalk to us