Skip to main content
Setting up Cindel requires four packages, a one-time code-generation step, and — optionally — a backend selection for native platforms. This page covers each piece in detail so your project is configured correctly before you write any model code.

​
The four packages

Cindel is split across four packages, each with a distinct role: You do not need to add cindel_annotations directly to your pubspec.yaml. It is pulled in transitively by cindel. Import it in model files with package:cindel_annotations/cindel_annotations.dart if you prefer a minimal import, or use package:cindel/cindel.dart which re-exports everything you need.

​
pubspec.yaml

Add the following to your pubspec.yaml, then run flutter pub get:
pubspec.yaml
Every model file that Cindel should generate code for must include a part directive pointing to the generated file. For a model defined in todo.dart, add the following line directly below your imports:
Without this directive, build_runner cannot attach the generated schema, collection getter, and query helpers to your model class.

​
Running the code generator

Run the generator once before you first open a database, and again after any model change:
During active development, keep the generator watching for changes so generated files stay in sync automatically:
The generator produces a *.g.dart file next to each annotated model. These files contain:
  • a schema constant (e.g. TodoSchema) to pass to Cindel.open,
  • a typed collection getter (e.g. db.todos) on the database handle,
  • serializers for reading and writing objects,
  • typed where() and filter() query helper chains.
Never hand-edit the generated *.g.dart files. They are overwritten every time you run the generator.

​
Choosing a backend

​
MDBX (default)

MDBX is the default native backend on Android, iOS, macOS, Linux, and Windows. You do not need to pass a backend parameter to use it:
MDBX is the recommended starting point for new native Flutter apps.

​
SQLite native

To use the native SQLite backend instead of MDBX, pass CindelStorageBackend.sqlite explicitly:
Switching between MDBX and SQLite does not change your application-level code. Generated schemas, collection getters, CRUD operations, queries, transactions, and watchers have the same shape with both backends.

​
SQLite Web / OPFS (browser)

Flutter Web uses SQLite in a Worker with OPFS persistence automatically. You do not select a backend for Web — MDBX is not available in the browser and the SQLite Web runtime is loaded from cindel_flutter_libs assets. On Web, pass a logical database name as the directory parameter instead of a filesystem path:
The directory value on Web is the logical browser database name, not a filesystem path. Use a stable name — changing it means opening a different browser database and any previously persisted data will not be visible to the new name.
Keep both cindel and cindel_flutter_libs in your dependencies for Web apps; cindel_flutter_libs bundles the Worker and Wasm assets that Cindel.open loads at runtime in the browser.

​
Platform support

Cindel supports all Flutter target platforms: Web support requires a browser context with Workers, Wasm, and OPFS available. Validate Web behavior in your target browsers, focusing on startup, asset loading, persistence after reopen, queries, transactions, and watcher behavior.

​
Next steps

With packages installed and the generator configured, you are ready to define your first model and open a database:

Quickstart

Follow the step-by-step guide to annotate a model, generate code, and run your first typed query.

Data Modeling

Learn how to define collections, choose field types, add indexes, and use embedded objects.