Cindel: Flutter-First Local Database — Full Overview

Cindel is a local-first, embedded database for Flutter and Dart applications. It stores structured data on-device through a Rust native core, exposes the database through a generated typed Dart API, and runs on every platform that Flutter targets — Android, iOS, macOS, Linux, Windows, and Web. Your application never touches raw rows or stringly typed maps; it works exclusively with Dart objects through a generated surface that is checked at compile time.

What Cindel is

Cindel is not a remote backend or a sync service. It is an embedded database that lives inside your app and makes local structured data available quickly and with full Dart type safety. It is useful when your app needs:

offline-capable structured data that survives app restarts,
cached records that are still queryable without a network connection,
local-first workflows where writes happen on-device before being synced,
durable UI state such as task lists, product catalogs, settings, or message threads.

Cindel is designed to complement your server, not replace it. If you need sync, you still provide the backend and a thin adapter; Cindel handles local storage, records local mutations in a durable outbox, and calls your adapter through a defined contract.

The code-generation model

Cindel’s public API is entirely generated. The workflow is:

Annotate a class. Add @Collection() (or @collection) to a Dart class, declare an Id dbId = autoIncrement field, and mark indexed fields with @Index.
Add a part directive. Include part 'modelname.g.dart'; in the model file so the generator can attach the output.
Run build_runner. Execute dart run build_runner build to produce the schema constant, typed collection getter, serializers, and query helpers.
Use the generated API. Register the generated schema when you open the database, then read and write through the typed collection getter.

A minimal model looks like this:

user.dart

import 'package:cindel_annotations/cindel_annotations.dart';

part 'user.g.dart';

@Collection(name: 'users')
class User {
  Id dbId = autoIncrement;

  @Index(unique: true)
  late String email;

  @Index()
  late String name;

  bool active = true;
}

After generation, the app registers UserSchema and uses db.users. Every method on db.users is typed to User:

db.users.put(user) accepts a User.
db.users.get(id) returns a Future<User?>.
Query helpers such as db.users.filter().activeEqualTo(true).findAll() are generated from your model’s field names.
Invalid field names cannot be passed as plain strings in everyday app code.

Available backends

Cindel selects its storage backend at open time. The application-level API stays the same regardless of which backend is active.

Backend	Platforms	How to select
MDBX (default)	Android, iOS, macOS, Linux, Windows	Omit the `backend` parameter
SQLite native	Android, iOS, macOS, Linux, Windows	Pass `backend: CindelStorageBackend.sqlite`
SQLite Web / OPFS	Browser (Flutter Web)	Automatic — MDBX is not used in browsers

Use MDBX for new native apps unless you have a specific reason to prefer SQLite. Both backends expose the same schemas, collection getters, queries, transactions, and watchers — switching backends does not require rewriting application code. On the web, cindel_flutter_libs bundles the SQLite Worker and Wasm assets. The directory parameter in Cindel.open becomes a logical browser database name rather than a filesystem path.

Core query entry points

Every generated collection exposes three query starting points:

all() — starts from the entire collection with no filter.
where() — uses generated helpers for fields marked with @Index; ideal for high-performance indexed lookups.
filter() — uses generated helpers for any stored field; supports rich predicates, string matching, list element queries, and boolean composition.

// Full collection scan
final everyone = await db.users.all().findAll();

// Indexed lookup — fast path through the index
final ada = await db.users
    .where()
    .emailEqualTo('ada@example.com')
    .findFirst();

// Field filter — works on any stored field
final activeUsers = await db.users
    .filter()
    .activeEqualTo(true)
    .findAll();

Both where() and filter() chains support sorting, pagination, distinct values, projections, aggregates, query-scoped updates, and query-scoped deletes. Watchers can be attached to any query chain.

Reactive watchers

Cindel can emit a fresh typed snapshot every time matching data changes. You attach a watcher to an object, a collection, or a query chain, and your stream listener receives the updated result without polling.

// Watch the whole collection
db.users.watchCollection().listen((users) {
  // Rebuild your widget with the latest snapshot.
});

// Watch a filtered query
db.users
    .filter()
    .activeEqualTo(true)
    .sortByName()
    .watch()
    .listen((activeUsers) {
      // Only fires when the active-user set changes.
    });

When to use Cindel vs. a remote database

Use Cindel when your app needs fast, typed, queryable data that lives on the device — task lists, product catalogs, draft content, user preferences, or anything that should work offline. Use a remote database (or add Cindel’s experimental sync) when authoritative data must be shared across devices or users, or when the server is the system of record. The two approaches are complementary: many apps store a local Cindel database for offline performance and sync changes to a backend when connectivity is available.

Next steps

Quickstart

Follow the step-by-step guide to define a model, generate code, and run your first typed query in a Flutter app.

Get Started

Data Modeling

Querying Data

Core Features

Platforms

Reference

Cindel: Flutter-First Local Database — Full Overview

What Cindel is

The code-generation model

Available backends

Core query entry points

Reactive watchers

When to use Cindel vs. a remote database

Next steps

Quickstart

​What Cindel is

​The code-generation model

​Available backends

​Core query entry points

​Reactive watchers

​When to use Cindel vs. a remote database

​Next steps

Quickstart

What Cindel is

The code-generation model

Available backends

Core query entry points

Reactive watchers

When to use Cindel vs. a remote database

Next steps