Cindel Current Limits: Modeling, Sync, and Web Constraints

Data Modeling

The following modeling patterns are not supported in the current release:

No indexes in embedded classes — you cannot annotate a field inside an embedded object with an index. Place indexes on root collection fields instead. Embedded objects remain useful for value-shaped data (addresses, settings blocks) that belongs to a root document.
No nested lists — lists whose elements are themselves lists are not supported. Flatten your data model or store the nested structure as a serialized field.
No Freezed union or sealed multi-constructor models — Freezed classic classes and single primary-factory models work. If a model needs multiple union cases, keep the union outside the persisted Cindel collection, or persist an explicit discriminator field such as type and branch on it in Dart.

Querying

No query updates while sync is enabled — updateFirst / updateAll-style query updates are not supported when sync is active. Instead, read the records you want to change, mutate them in Dart, then write them back:

final todos = await db.todos.all().findAll();

for (final todo in todos) {
  todo.completed = true;
}

await db.writeTxn(() => db.todos.putAll(todos));

Migrations

No incremental or partial backups — the backup API supports full archive export only. There is no incremental or partial backup mechanism.
No merge-restore into a non-empty database — when you restore from a backup, the target database must be empty. You cannot merge a backup archive into a database that already contains records.

For full archive export/import, use CindelBackup:

await CindelBackup.exportDatabase(
  database: db,
  collections: [CindelBackupCollection(UserSchema)],
  output: output,
);

Restore into an empty database opened with matching schemas.

Sync

Sync is experimental. The API may change between releases.The current public sync API does not include:

No bundled hosted sync server — you must provide your own backend and implement the CindelSyncAdapter contract
No manual push/pull/pause/resume/flush controls — sync runs on the interval configured at open time; there are no public methods to trigger or pause a cycle manually
No built-in auth or conflict resolution — your backend is responsible for authentication, validation, idempotency, checkpoints, and conflict handling
No query updates while sync is enabled — see the Querying section above
No Web multi-tab sync coordination — sync watcher delivery on Web is single-tab only

Configure sync at open time:

final db = await Cindel.open(
  directory: directory.path,
  schemas: [OrderSchema],
  sync: CindelSyncConfig(
    adapter: AppSyncAdapter(serverBaseUri),
  ),
);

Web

Cindel on Flutter Web uses SQLite Web with OPFS. The current Web implementation has the following constraints:

MDBX backend not available — MDBX is the default native backend on all other platforms but is not used in browsers. SQLite Web is the only option on Web.
Watcher delivery is single-tab only — watch() streams deliver updates only within the tab that made the write. This applies to both collection watchers and sync watchers.
No multi-tab coordination — there is no mechanism to synchronize state across multiple open browser tabs.
Storage quota and OPFS availability vary — browser support for OPFS and the available storage quota depend on the browser, operating system, and whether the page is served in a secure context. Private-browsing mode may restrict or disable storage entirely.

Design Web apps so each tab loads its own view of local data. Do not depend on one tab receiving watcher notifications triggered by another tab’s writes.

General

These items apply across multiple areas of the API:

No embedded-field indexes — indexes must be placed on root collection fields, not on fields inside embedded classes. This affects both querying and code generation. See the Data Modeling section for details.
No query updates while sync is enabled — updateFirst / updateAll-style query updates are not supported when sync is active. See the Querying and Sync sections for the read-mutate-write pattern.
No incremental backups or merge-restore — the backup API supports full archive export only, and restore requires an empty target database. See the Migrations section.

Design your application around the limits documented on this page. Where a capability is not yet available, keep that logic in your application or backend code.

Get Started

Data Modeling

Querying Data

Core Features

Platforms

Reference

Cindel Current Limits: Modeling, Sync, and Web Constraints