Get Started with Cindel: Flutter Local Database Guide

This guide walks you through every step to get Cindel running in a Flutter app from scratch. By the end you will have a persistent Todo collection with typed reads, writes, and a reactive watcher — all driven by generated Dart code.

Add dependencies

Open your pubspec.yaml and add the four Cindel packages. The cindel and cindel_flutter_libs packages are runtime dependencies; build_runner and cindel_generator are used only during development to generate code.

pubspec.yaml

dependencies:
  cindel: ^1.0.0
  cindel_flutter_libs: ^1.0.0

dev_dependencies:
  build_runner: ^2.15.0
  cindel_generator: ^1.0.0

Run flutter pub get after saving the file.

Define a model

Create a Dart file for your model. Annotate the class with @Collection(), declare an Id dbId = autoIncrement field, and add a part directive for the file that build_runner will generate.

todo.dart

import 'package:cindel_annotations/cindel_annotations.dart';

part 'todo.g.dart';

@Collection()
class Todo {
  Id dbId = autoIncrement;
  late String title;
  bool completed = false;
}

Add @Index() to any field you plan to use with the generated where() helper for fast indexed lookups. Fields without an index are still fully queryable through filter().

Generate code

Run the code generator once to produce todo.g.dart. This file contains the TodoSchema constant, the db.todos getter, serializers, and all typed query helpers.

dart run build_runner build

During active development, use watch mode so the generator re-runs automatically whenever you edit a model:

dart run build_runner watch

Never hand-edit the generated *.g.dart files. Re-run the generator any time you change a model class or its annotations.

Open the database and use it

Resolve a writable directory with path_provider, open the database with the generated TodoSchema, and then read and write through the typed db.todos collection.

final dir = await getApplicationDocumentsDirectory();
final db = await Cindel.open(
  directory: dir.path,
  schemas: [TodoSchema],
);

// Create
final todo = Todo()..title = 'Buy groceries';
await db.writeTxn(() => db.todos.put(todo));

// Read all
final todos = await db.todos.where().findAll();

// Watch changes
db.todos.watchCollection().listen((allTodos) {
  // rebuild UI
});

await db.close();

When dbId is set to autoIncrement, Cindel assigns a new id the first time you call put. After put returns, the generated id setter writes the allocated id back to the todo object, so todo.dbId contains the real persisted id immediately.

For unit tests, use Cindel.openInMemory(schemas: [TodoSchema]) instead of Cindel.open. In-memory databases are fast to create, require no filesystem path, and are automatically discarded when closed — making them ideal for isolated test cases.

What to explore next

Now that your first collection is working, explore the rest of the Cindel feature set:

Installation — full package details, backend selection, and platform support.
Data Modeling — field types, enums, embedded objects, indexes, and Freezed support.
Querying Data — where(), filter(), sorting, pagination, projections, and aggregates.
Transactions — group related writes with writeTxn so they commit or roll back atomically.
Flutter Web — run the same typed code in the browser with SQLite Web/OPFS.

Get Started

Data Modeling

Querying Data

Core Features

Platforms

Reference

Get Started with Cindel: Flutter Local Database Guide

What to explore next

​What to explore next

What to explore next