> ## Documentation Index
> Fetch the complete documentation index at: https://cindel.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Started with Cindel: Flutter Local Database Guide

> Build your first Cindel-powered Flutter feature in minutes: add packages, define a model, generate code, and run your first typed query.

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.

<Steps>
  <Step title="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.

    ```yaml pubspec.yaml theme={null}
    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.
  </Step>

  <Step title="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.

    ```dart todo.dart theme={null}
    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()`.
  </Step>

  <Step title="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.

    ```bash theme={null}
    dart run build_runner build
    ```

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

    ```bash theme={null}
    dart run build_runner watch
    ```

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

  <Step title="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.

    ```dart theme={null}
    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();
    ```

    <Note>
      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.
    </Note>

    <Tip>
      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.
    </Tip>
  </Step>
</Steps>

## What to explore next

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

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