Schema Migrations: Evolving Your Cindel Data Model

When you change a field name, type, or model structure, the data already on a user’s device still reflects the old shape. Migrations let you open that existing data with the old schemas, convert it to the current shape, and continue with the new generated API — all transparently at app startup.

How Cindel Runs Migrations

Cindel stores a database-level migration version inside every database file. When you open the database, CindelMigrationPlan compares the stored version with targetVersion, runs any missing steps in order, persists each successful toVersion after the step completes, and returns a database opened with the target schemas. Completed steps are skipped on future opens; only the outstanding steps run.

final db = await Cindel.open(
  directory: appDataDirectory.path,
  schemas: [UserSchema],
  migrationPlan: migrations,
);

Core Types

`CindelMigrationPlan`

Declare a plan with a targetVersion, a baselineVersion (for databases that have no stored version yet), and an ordered list of steps:

final migrations = CindelMigrationPlan(
  targetVersion: 2,
  baselineVersion: 1,
  steps: [
    migrateUsersFrom1To2,
  ],
);

Pass the same plan every time you open the database. Steps that have already been applied are skipped automatically.

`CindelMigrationStep`

Each step describes exactly one version move and carries its own schemas, migration logic, and optional verification hooks:

Field	Role
`fromVersion`	The version this step starts from
`toVersion`	The version this step completes
`openSchemas`	Schemas that can read the existing stored shape
`targetSchemas`	Schemas that should exist after the step
`migrate`	Required migration callback
`verifyBefore`	Optional — throw to abort before data is rewritten
`verifyAfter`	Optional — throw to abort if the migrated result is wrong

Step Lifecycle

Every migration step follows the same ordered lifecycle:

Export old data

Use context.exportObjects(schema) to read old typed objects, or context.exportDocuments(schema) to read raw map-shaped documents.

// Typed export — easy when the old model still maps well to stored data.
final oldUsers = await context.exportObjects(OldUserSchema);

// Document export — useful when fields are being heavily renamed.
final oldDocuments = await context.exportDocuments(OldUserSchema);

Both APIs read data in id order with bounded batches, so the process is predictable regardless of collection size.

Call context.registerTargetSchemas() to prepare the target collections before you write any converted data into them.

await context.registerTargetSchemas();

Do not import target objects before this call.

Import converted data

Use context.importObjects(schema, iterable) for new typed objects, or context.importDocuments(schema, iterable) for target documents.

await context.importObjects(
  UserSchema,
  oldUsers.map(User.fromLegacy),
);

Make sure required fields are filled, removed fields are no longer referenced, and ids are preserved when records should remain the same logical objects.

Verify before and after (optional)

The verifyBefore hook runs before data is rewritten. The verifyAfter hook runs after. Throw from either hook to abort the step and prevent it from being marked complete.

verifyAfter: (context) async {
  final version = await context.database.schemaVersion('users');
  if (version == null) {
    throw StateError('Users schema was not registered.');
  }
},

Useful checks: required collections exist, document counts match expectations, ids were preserved, and converted values are valid for the new model.

Complete Example: Renaming a Field

This example migrates a User model from version 1 to version 2, where the fullName field is renamed to name and the email_address persisted field is normalised to email.

// Conversion helper — preserves dbId so records remain the same logical objects.
extension UserFromLegacy on User {
  static User fromLegacy(OldUser old) {
    return User()
      ..dbId = old.dbId
      ..email = old.email
      ..name = old.fullName
      ..active = old.deletedAt == null;
  }
}

// The migration step.
final migrateUsersFrom1To2 = CindelMigrationStep(
  fromVersion: 1,
  toVersion: 2,
  openSchemas: [OldUserSchema],
  targetSchemas: [UserSchema],
  verifyBefore: (context) async {
    // Check that the old collection is readable — throw to abort if not.
    await context.database.documentIds('users');
  },
  migrate: (context) async {
    final oldUsers = await context.exportObjects(OldUserSchema);

    await context.registerTargetSchemas();

    await context.importObjects(
      UserSchema,
      oldUsers.map(User.fromLegacy),
    );
  },
  verifyAfter: (context) async {
    final version = await context.database.schemaVersion('users');
    if (version == null) {
      throw StateError('Users schema was not registered.');
    }
  },
);

// The plan — passed to Cindel.open() on every app start.
final migrations = CindelMigrationPlan(
  targetVersion: 2,
  baselineVersion: 1,
  steps: [migrateUsersFrom1To2],
);

final db = await Cindel.open(
  directory: appDataDirectory.path,
  schemas: [UserSchema],
  migrationPlan: migrations,
);

// After migration, use the current generated API normally.
final users = await db.users.all().findAll();

Automatic Compaction

Set compactOnSuccess: true on your CindelMigrationPlan to have Cindel call compact() automatically after a migration finishes. This reclaims storage space freed by replacing old records and is the preferred way to compact after a migration.

final migrations = CindelMigrationPlan(
  targetVersion: 2,
  baselineVersion: 1,
  compactOnSuccess: true,
  steps: [migrateUsersFrom1To2],
);

Best Practices

Keep steps small and single-purpose. One step should handle exactly one version move. For two releases of schema changes, write two steps — not one step that tries to handle every old shape.
Preserve dbIds. When existing records should remain the same logical objects after migration, copy old.dbId into the new object during conversion.
Always pass the migration plan at startup. Leave the plan in place until you are certain that no supported device can have a database below targetVersion. Removing the plan prematurely leaves some users unable to open their database.
Choose your export format deliberately. Use exportObjects when the old schema still produces useful Dart objects. Use exportDocuments when fields are being renamed heavily and you need direct access to persisted field names.

Do not remove the CindelMigrationPlan from Cindel.open() until every supported database is already at targetVersion. Removing it early means users still running an older database version will open without migration, potentially causing a crash or data corruption.

Low-Level Primitives

migrationVersion(), setMigrationVersion, registerMigratedSchemas, and compact() are low-level primitives exposed for controlled tooling and diagnostics. Do not call them directly in application migration code — use CindelMigrationPlan and CindelMigrationStep instead.

Get Started

Data Modeling

Querying Data

Core Features

Platforms

Reference

Schema Migrations: Evolving Your Cindel Data Model

How Cindel Runs Migrations

Core Types

`CindelMigrationPlan`

`CindelMigrationStep`

Step Lifecycle

Complete Example: Renaming a Field

Automatic Compaction

Best Practices

Low-Level Primitives

​How Cindel Runs Migrations

​Core Types

​CindelMigrationPlan

​CindelMigrationStep

​Step Lifecycle

​Complete Example: Renaming a Field

​Automatic Compaction

​Best Practices

​Low-Level Primitives

How Cindel Runs Migrations

Core Types

`CindelMigrationPlan`

`CindelMigrationStep`

Step Lifecycle

Complete Example: Renaming a Field

Automatic Compaction

Best Practices

Low-Level Primitives