Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/mainser/cindel/llms.txt

Use this file to discover all available pages before exploring further.

CindelBackup provides full-database typed export and import over caller-supplied streams. Archives are written as JSONL records — one JSON object per line — and are optionally gzip-compressed. Every archive includes a checksum-verified footer so that import detects truncated or corrupted files before writing a single document. The same API works across MDBX, SQLite native, and SQLite Web/OPFS; the only difference is the default compression, which is gzip on native Dart and none on Web.

​
CindelBackup

CindelBackup is an abstract final class. All functionality is exposed through two static methods: exportDatabase and importDatabase.

​
exportDatabase

static Future<CindelBackupReport> exportDatabase({
  required CindelDatabase database,
  required Iterable<CindelBackupCollection<dynamic>> collections,
  required StreamConsumer<List<int>> output,
  int batchSize = 1000,
  CindelBackupCompression? compression,
  CindelBackupProgressCallback? onProgress,
})
Streams a typed JSONL archive of the listed collections into output. Documents are read in ascending id order using bounded page reads. The header, schema, doc, and footer records are emitted in that order; compression (if selected) is applied to the entire byte stream before it reaches output. Returns a CindelBackupReport describing the archive once the stream is closed.
​
database
CindelDatabase
required
Open database handle to export from. The database must already have the target schemas registered.
​
collections
Iterable<CindelBackupCollection>
required
Collections to include in the archive. Each collection must be distinct (no duplicate schema names); exportDatabase throws an ArgumentError if duplicates are found.
​
output
StreamConsumer<List<int>>
required
Destination stream for the compressed or plain JSONL bytes. Pass a file sink (File(...).openWrite()), a network socket, or any other StreamConsumer.
​
batchSize
int
default:"1000"
Number of document ids fetched from the database per page read. Larger values reduce round-trips; smaller values reduce peak memory. Must be greater than zero.
​
compression
CindelBackupCompression?
Compression algorithm applied to the archive stream. When omitted, defaults to CindelBackupCompression.gzip on native Dart and CindelBackupCompression.none on Web. Pass an explicit value to override the platform default.
​
onProgress
CindelBackupProgressCallback?
Optional callback invoked after each document record is written. Receives a CindelBackupProgress snapshot with the current phase, collection name, and running document count.
Returns: Future<CindelBackupReport>

​
importDatabase

static Future<CindelBackupReport> importDatabase({
  required CindelDatabase database,
  required Iterable<CindelBackupCollection<dynamic>> collections,
  required Stream<List<int>> input,
  int batchSize = 1000,
  CindelBackupCompression? compression,
  CindelBackupProgressCallback? onProgress,
})
Reads a JSONL archive from input and imports every doc record into the matching collection. Documents are accumulated in memory until batchSize is reached, then flushed to the database in a single bulk write. On completion, Cindel validates the document count and FNV-1a checksum from the archive footer and throws a StateError if either does not match.
​
database
CindelDatabase
required
Open database handle to restore into. Every collection listed in collections must be empty; importDatabase throws a StateError if any collection already contains documents.
​
collections
Iterable<CindelBackupCollection>
required
Collections to restore. The set of collection names must exactly match the schema records in the archive; extra or missing collections cause a StateError.
​
input
Stream<List<int>>
required
Source stream of the archive bytes. Pass a file read stream (File(...).openRead()), an HTTP response body, or any Stream<List<int>>.
​
batchSize
int
default:"1000"
Number of documents buffered before each bulk write. Must be greater than zero.
​
compression
CindelBackupCompression?
Decompression algorithm to apply to input. Must match the compression used during export. When omitted, defaults to the same platform default as exportDatabase.
​
onProgress
CindelBackupProgressCallback?
Optional callback invoked after each document record is read. Receives a CindelBackupProgress snapshot with phase set to CindelBackupPhase.import.
Returns: Future<CindelBackupReport> Throws: StateError if any target collection is non-empty, if the archive header or footer is missing or malformed, if the document count mismatches, or if the checksum does not verify.

​
Usage Example

// Export
final output = File('backup.cindelbak').openWrite();
final report = await CindelBackup.exportDatabase(
  database: db,
  collections: [
    CindelBackupCollection(UserSchema),
    CindelBackupCollection(OrderSchema),
  ],
  output: output,
);
print('Exported ${report.documents} documents (${report.archiveBytes} bytes).');

// Import — target database must be empty for all collections
final restoredDb = await Cindel.open(
  directory: restoreDir.path,
  schemas: [UserSchema, OrderSchema],
);
await CindelBackup.importDatabase(
  database: restoredDb,
  collections: [
    CindelBackupCollection(UserSchema),
    CindelBackupCollection(OrderSchema),
  ],
  input: File('backup.cindelbak').openRead(),
);

​
CindelBackupCollection<T>

A typed handle that couples a generated CindelCollectionSchema<T> to the backup engine. Create one instance per collection you want to include in an export or import.

​
Constructor

CindelBackupCollection(CindelCollectionSchema<T> schema)
​
schema
CindelCollectionSchema<T>
required
Generated collection schema. The schema provides the collection name, serializers (toDocument / fromDocument), and id accessors used internally by exportDatabase and importDatabase.

​
CindelBackupCompression

Controls the byte-level encoding of the archive stream. 
enum CindelBackupCompression { none, gzip }
ValueDescription
nonePlain UTF-8 JSONL with no compression. Compatible with Web environments and any JSONL tooling.
gzipGzip-compressed UTF-8 JSONL. The default on native Dart platforms. Significantly reduces file size for text-heavy document sets.

​
CindelBackupReport

Summary returned by both exportDatabase and importDatabase once the archive stream has been fully consumed or written.

​
Properties

​
documents
int
Total number of doc records in the archive. During export this reflects the number of documents serialized; during import it reflects the number successfully written.
​
uncompressedBytes
int
Size of the JSONL byte stream before compression, including newline terminators for every record. Useful for estimating storage costs before choosing a compression algorithm.
​
archiveBytes
int
Actual bytes read from or written to the caller-supplied stream (i.e., after compression on export, before decompression on import).
​
checksum
int
FNV-1a checksum computed over every non-footer JSONL record (header, schema, and doc lines). Matches the checksum stored in the archive footer.
​
compression
CindelBackupCompression
Compression algorithm that was used for this archive, reflecting either the explicit value passed by the caller or the resolved platform default.

​
CindelBackupProgress

Snapshot delivered to onProgress after each document record during export or import.

​
Properties

​
phase
CindelBackupPhase
Current operation — CindelBackupPhase.export during exportDatabase and CindelBackupPhase.import during importDatabase.
​
collection
String?
Name of the collection currently being processed. null for archive-level metadata records (header and footer); always a non-null string for document records.
​
documents
int
Running total of documents processed since the operation started.

​
Archive Format

After decompression, a Cindel backup archive is a sequence of UTF-8 JSON lines — one record per line — followed by a single newline. The importDatabase method validates record ordering and rejects any archive that deviates from the expected structure.

​
Record Types

header — First record in every archive. 
{
  "type": "header",
  "format": "cindel.backup.jsonl",
  "version": 1,
  "backend": "mdbx",
  "createdAt": "2024-11-01T10:00:00.000Z",
  "migrationVersion": 2
}
FieldTypeDescription
formatStringAlways "cindel.backup.jsonl". Rejects unknown formats on import.
versionintArchive format version. Currently 1.
backendStringStorage backend name from the exporting database.
createdAtStringISO-8601 UTC timestamp of the export.
migrationVersionint?Data version recorded in the source database at export time; restored into the target database on import when present.
schema — One record per collection, emitted after the header and before any doc records. 
{
  "type": "schema",
  "collection": "users",
  "schemaVersion": 3
}
FieldTypeDescription
collectionStringCollection name. Must match a name in the collections list passed to importDatabase.
schemaVersionint?Schema version stored in the source database.
doc — One record per document, grouped by collection. 
{
  "type": "doc",
  "collection": "users",
  "id": 42,
  "document": { "dbId": 42, "email": "ada@example.com", "name": "Ada Lovelace", "active": true }
}
FieldTypeDescription
collectionStringCollection this document belongs to.
idintAuto-increment id of the document.
documentObjectFull serialized document including the id field.
footer — Last record in every archive. Not included in the FNV-1a checksum. 
{
  "type": "footer",
  "documents": 1024,
  "checksum": 3421459283
}
FieldTypeDescription
documentsintExpected total number of doc records. Verified against the count accumulated during import.
checksumintFNV-1a checksum (32-bit, initial value 0x811c9dc5) computed over all non-footer records. Verified on import.

Build docs developers (and LLMs) love

Get started for freeTalk to us