Cindel Backup: Export, Import, and Low-Level Helpers

Cindel provides CindelBackup for exporting and importing full typed database archives, plus a set of low-level helpers for maintenance flows and tooling. Normal app reads and writes should always go through the generated typed collections (db.users, db.todos, etc.) — the APIs on this page are for archival, migration tooling, and controlled maintenance scenarios.

`CindelBackup`

CindelBackup streams a full archive of your database as a JSONL file. The archive includes a header, schema records, document records for every collection you specify, and a footer with a document count and checksum. On native Dart the archive is gzip-compressed by default; pass CindelBackupCompression.none for Web or anywhere you need uncompressed JSONL bytes.

Exporting a Database

Pass your database instance, a list of CindelBackupCollection entries (one per schema), and an output StreamConsumer<List<int>> such as a file sink:

final report = await CindelBackup.exportDatabase(
  database: db,
  collections: [
    CindelBackupCollection(UserSchema),
    CindelBackupCollection(OrderSchema),
  ],
  output: File('backup.cindelbak').openWrite(),
);

print('Exported ${report.documentCount} documents');
print('Archive size: ${report.archiveSizeBytes} bytes');

For Web or any context that requires uncompressed output, set compression explicitly:

final report = await CindelBackup.exportDatabase(
  database: db,
  collections: [
    CindelBackupCollection(UserSchema),
  ],
  compression: CindelBackupCompression.none,
  output: output,
);

The returned CindelBackupReport carries:

Field	Description
`documentCount`	Total number of exported documents
`archiveSizeBytes`	Size of the written archive in bytes
`checksum`	Integrity checksum of the archive
`compression`	Compression mode used (`gzip` or `none`)

Importing a Database

Use CindelBackup.importDatabase to restore an archive into an empty database. Open the target database with the same schemas that were used during export, then pass the archive as a Stream<List<int>>:

final restoredDb = await Cindel.open(
  directory: restoredDirectory.path,
  schemas: [UserSchema, OrderSchema],
);

await CindelBackup.importDatabase(
  database: restoredDb,
  collections: [
    CindelBackupCollection(UserSchema),
    CindelBackupCollection(OrderSchema),
  ],
  input: File('backup.cindelbak').openRead(),
);

Always import into an empty database. Importing into a database that already contains data is not supported and will produce unpredictable results. Open a fresh database in a new directory before calling importDatabase.

Supporting Types

Type	Purpose
`CindelBackupCollection`	Wraps a generated schema to keep typing intact during backup
`CindelBackupProgress`	Reports the current phase, collection, and document count during a long operation
`CindelBackupReport`	Final summary returned by `exportDatabase`

Low-Level Helpers

The following helpers are intended for tooling, maintenance services, and migration code. Keep them out of normal application feature code.

`documentIds`

Returns every id in a collection, ordered ascending:

final ids = await db.documentIds('todos');
final todos = await db.todos.getAll(ids);

Use this only when the collection is known to be small and bounded. For collections of unknown or potentially large size, use documentIdsPage instead.

`documentIdsPage`

Returns a bounded page of ids, ordered ascending, starting after an optional cursor id:

int? afterId;

while (true) {
  final ids = await db.documentIdsPage(
    'todos',
    afterId: afterId,
    limit: 1000,
  );

  if (ids.isEmpty) {
    break;
  }

  final todos = await db.todos.getAll(ids);
  // Export, verify, or process this page.

  afterId = ids.last;
}

afterId is an exclusive cursor — pass the last id from the previous page to advance. limit must be greater than zero. documentIdsPage works identically across SQLite native, MDBX, and Web SQLite backends. Prefer documentIdsPage over documentIds whenever the collection size is unknown or potentially large.

`allocateId`

Allocates the next id for a collection without writing a document:

final id = await db.allocateId('todos');

You rarely need this directly — typed put and putAll allocate ids automatically when a field is marked autoIncrement. Use allocateId only in tooling that needs to reserve ids before constructing documents. Always pass the persisted collection name (the string identifier, not the Dart class name):

final id = await db.allocateId('users'); // ✅ persisted name

`compact`

Asks the storage backend to reclaim space freed by previous maintenance work, such as a completed migration. compact must be called inside a writeTxn:

await db.writeTxn(() async {
  await db.compact();
});

For post-migration compaction, set compactOnSuccess: true on your CindelMigrationPlan instead of calling compact() directly. That option handles compaction automatically after a successful migration without any extra code.

Call compact directly only from maintenance code that already controls when cleanup is safe.

Practical Guidance

Use generated typed collections for app features. db.todos.all().findAll() is faster to write, easier to read, and benefits from query compilation and indexing.
Use documentIdsPage over documentIds whenever you don’t control the upper bound of collection size. Fetching millions of ids at once can stall the UI or exhaust memory.
Use persisted collection names — the string identifiers — when calling any low-level helper. These are stable across renames of your Dart classes.
Isolate advanced helpers. Keep documentIdsPage, allocateId, and compact inside dedicated tooling, backup, or maintenance services. Normal feature code should never call them directly.

Get Started

Data Modeling

Querying Data

Core Features

Platforms

Reference

Cindel Backup: Export, Import, and Low-Level Helpers

`CindelBackup`

Exporting a Database

Importing a Database

Supporting Types

Low-Level Helpers

`documentIds`

`documentIdsPage`

`allocateId`

`compact`

Practical Guidance

​CindelBackup

​Exporting a Database

​Importing a Database

​Supporting Types

​Low-Level Helpers

​documentIds

​documentIdsPage

​allocateId

​compact

​Practical Guidance

`CindelBackup`

Exporting a Database

Importing a Database

Supporting Types

Low-Level Helpers

`documentIds`

`documentIdsPage`

`allocateId`

`compact`

Practical Guidance