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.

Before reading or writing any data you must open a database handle. Cindel’s entry point is Cindel.open, a static Future on the Cindel class that initialises the native engine, registers your generated schemas, and returns a CindelDatabase ready for use. The same call works on native platforms (iOS, Android, macOS, Windows, Linux) and on Flutter Web — the underlying backend is selected automatically or explicitly through the backend parameter.

​
Cindel.open

static Future<CindelDatabase> open({
  required String directory,
  Iterable<CindelCollectionSchema<dynamic>> schemas = const [],
  CindelStorageBackend backend = defaultCindelStorageBackend,
  CindelMigrationPlan? migrationPlan,
  CindelSyncConfig? sync,
})

​
Parameter Reference

ParameterTypeRequiredDescription
directoryString✅Path to a writable directory where database files are stored. On Flutter Web, pass a short string name (not a filesystem path) — it becomes the OPFS origin-private storage name. Must not be empty.
schemasIterable<CindelCollectionSchema>—Generated schema objects for every collection the app reads or writes. Pass the XyzSchema constant emitted by the generator (e.g. UserSchema).
backendCindelStorageBackend—Storage engine. Defaults to CindelStorageBackend.mdbx. Pass CindelStorageBackend.sqlite to select SQLite explicitly on native. Web always uses SQLite/OPFS regardless of this value.
migrationPlanCindelMigrationPlan?—Versioned migration plan executed before the final handle is opened. See the Migrations page for details.
syncCindelSyncConfig?—Experimental local-first sync configuration. See the Sync page for details.

​
MDBX (Default)

MDBX is the default backend for new Cindel databases on native platforms. It uses a memory-mapped B-tree file format with very low read overhead and is the recommended backend for most Flutter apps. 
import 'package:path_provider/path_provider.dart';
import 'package:cindel/cindel.dart';

final dir = await getApplicationDocumentsDirectory();

final db = await Cindel.open(
  directory: dir.path,
  schemas: [UserSchema, AccountSchema],
);
Because backend defaults to CindelStorageBackend.mdbx, no explicit backend argument is needed.

​
SQLite (Explicit)

Select SQLite when you need the native SQLite backend — for example, when your app already relies on SQLite tooling, you need SQL-level introspection, or you are integrating with an existing SQLite database file: 
final db = await Cindel.open(
  directory: dir.path,
  schemas: [UserSchema],
  backend: CindelStorageBackend.sqlite,
);

​
Choosing a Backend

MDBXSQLite
Default on native✅No
Flutter WebNo✅ (OPFS)
Recommended for new apps✅When you specifically need SQLite
SQL-level toolingNo✅
Flutter Web always uses SQLite with OPFS regardless of which backend you specify. The generated typed API — CRUD, queries, transactions, watchers — works identically across both backends.

​
In-Memory Database (Tests)

Cindel.openInMemory opens a database that lives only in memory. Data is discarded when the handle is closed, making it ideal for fast unit tests: 
test('stores users', () async {
  final db = await Cindel.openInMemory(schemas: [UserSchema]);
  addTearDown(db.close);

  final user = User()
    ..email = 'ada@example.com'
    ..name = 'Ada';

  await db.users.put(user);

  expect(await db.users.get(user.dbId), isNotNull);
});
openInMemory accepts schemas, backend, and sync — the same as open minus directory and migrationPlan.

​
Flutter Web

On the Web, directory is a short string identifier used as the OPFS storage origin name rather than a filesystem path. Pass a consistent name across restarts so data is reloaded correctly: 
final db = await Cindel.open(
  directory: 'app.db',
  schemas: [UserSchema],
);
Cindel loads the packaged Worker and Wasm assets automatically when you include both cindel and cindel_flutter_libs in your pubspec.yaml: 
dependencies:
  cindel: ^0.9.1
  cindel_flutter_libs: ^0.9.1

​
Closing a Database

Call close() on the returned CindelDatabase to flush any pending state and release native resources. Calling close() more than once is safe: 
await db.close();
On mobile apps it is typical to open one database handle for the entire app lifetime and close it in a dispose or teardown hook. In tests use addTearDown(db.close) so every test cleans up even when it fails.
migrationPlan and sync are each covered in their own pages. See the Migrations and Sync sections for full examples.

Build docs developers (and LLMs) love

Get started for freeTalk to us