Migrate from Isar v3 to Isar Plus v4

Upgrading from the legacy isar 3.x packages to isar_plus (v4) is a breaking, file-format change. The v4 core writes different metadata and cannot open a database that was written by v3, so you see errors such as:

VersionError: The database version is not compatible with this version of Isar.

The fix is to export your existing data with the legacy runtime and import it into a fresh Isar Plus database. The steps below walk you through the process.

Migration Overview

Update Dependencies Side by Side

Keep the old runtime until the copy finishes, then add the new one:

dependencies:
  isar: ^3.1.0+1
  isar_flutter_libs: ^3.1.0+1
  isar_generator: ^3.1.0+1
  isar_plus: ^1.2.0
  isar_plus_flutter_libs: ^1.2.0

dev_dependencies:
  build_runner: ^2.4.10

The two packages expose the same Dart symbols, so always import them with aliases during migration:

import 'package:isar/isar.dart' as legacy;
import 'package:isar_plus/isar_plus.dart' as plus;

Regenerate Your Schemas for v4

Isar Plus ships its generator inside the main package. Re-run the builder so it emits the new helpers and adapters:

dart run build_runner build --delete-conflicting-outputs

Pause here and address any compilation errors (for example, nullable Id? fields must become non-nullable int id, and use collection.autoIncrement() for auto-generated IDs).

API Migration Guide Key Changes

await isar.writeTxn(() async {
  await isar.users.put(user);
});

await isar.writeAsync((isar) async {
  await isar.users.put(user);
});

@collection
class User {
  Id id = Isar.autoIncrement; // ❌ This was valid in v3
  String? name;
}

@collection
class User {
  User(this.id);

  final int id; // ✅ Non-nullable, managed by you
  String? name;
}

// ✅ v4: Get auto-increment ID when creating
isar.write((isar) {
  final user = User(isar.users.autoIncrement())
    ..name = 'John';
  isar.users.put(user);
});

@enumerated
enum Status { active, inactive }

@enumValue
enum Status { active, inactive }

final posts = IsarLinks<Post>();

// Use embedded objects instead
List<Post> posts = [];

Unique Indexes

await isar.writeAsync((isar) async {
  final clash = await isar.users
      .where()
      .emailEqualTo(user.email)
      .findFirst();
  if (clash != null) {
    throw StateError('email already registered');
  }

  await isar.users.put(user);
});

Legacy Links Deep Dive

If your project relied heavily on IsarLink, IsarLinks, or @Backlink, convert them before you start copying rows. The v4 core only understands regular Dart fields (scalars, embedded objects, List<T>) so each link must become either an embedded document or an explicit foreign-key ID that you manage yourself. Use the following workflow:

1. Inventory every legacy link

• Search your v3 models for IsarLink, IsarLinks, or @Backlink annotations.
• Record whether each relationship is one-to-one, one-to-many, or many-to-many.
• Decide whether the related data should always travel with the parent (embed it) or live in its own collection (store IDs).

2. Rewrite the schema in v4 terms

• Embed one-to-few relationships that you always load together. Replace the link field with a List<YourEmbeddedType> or a nullable embedded object.
• Store IDs for relationships that span large collections or need independent lifecycle. Add int authorId, List<int> memberIds, etc. and use queries to load the related records.
• For backlinks, expose the forward reference explicitly (for example, add int authorId instead of @Backlink(to: 'posts')).

// v3
@collection
class LegacyTweet {
  LegacyTweet({this.id});

  Id? id;
  late IsarLink<LegacyUser> author;
  late IsarLinks<LegacyUser> likedBy;
}

// v4
@collection
class Tweet {
  Tweet(this.id, this.authorId, {this.reactions = const []});

  final int id;
  final int authorId; // was author IsarLink
  final List<TweetReaction> reactions; // replaces likedBy links
}

@embedded
class TweetReaction {
  TweetReaction({required this.userId, required this.createdAt});

  final int userId;
  final DateTime createdAt;
}

See the dedicated relationships guide for more schema patterns and live references.

3. Migrate the existing data

During the copy phase, materialize every link into the new structure yourself:

Future<void> _copyTweets(
  legacy.Isar legacyDb,
  plus.Isar plusDb,
) async {
  final tweets = await legacyDb.legacyTweets.where().findAll();

  await plusDb.writeAsync((isar) async {
    for (final legacyTweet in tweets) {
      final authorId = legacyTweet.author.value?.id;
      if (authorId == null) {
        continue; // or decide on a fallback
      }

      final reactions = legacyTweet.likedBy.map((user) {
        return TweetReaction(
          userId: user.id!,
          createdAt: DateTime.now(), // capture metadata if you stored it elsewhere
        );
      }).toList();

      await isar.tweets.put(
        Tweet(
          legacyTweet.id ?? isar.tweets.autoIncrement(),
          authorId,
          reactions: reactions,
        ),
      );
    }
  });
}

For many-to-many tables where you previously used two IsarLinks, create an explicit join collection that stores both IDs. During migration, iterate over the legacy link pairs and insert rows into that join collection yourself. Backlinks become filtered queries: instead of user.posts, query isar.posts.where().authorIdEqualTo(user.id).

Once every link is expressed as data that your Dart code owns, the copy to Isar Plus becomes a normal insert, and you can delete all IsarLink APIs from the project.

Copy the Actual Data

Create a one-off migration routine (for example in main() before initializing your app, or in a separate bin/migrate.dart). The pattern is:

1. Open the legacy store with the v3 runtime
2. Open a new v4 instance in a different directory or under a different name
3. Page through each collection, map it to the new schema, and put it into the new database
4. Mark the migration as finished so you do not run it twice

Future<void> migrateLegacyDb(String directoryPath) async {
  final legacyDb = await legacy.Isar.open(
    [LegacyUserSchema, LegacyTodoSchema],
    directory: directoryPath,
    inspector: false,
    name: 'legacy',
  );

  final plusDb = plus.Isar.open(
    schemas: [UserSchema, TodoSchema],
    directory: directoryPath,
    name: 'app_v4',
    engine: plus.IsarEngine.sqlite, // or IsarEngine.isar for native
    inspector: false,
  );

  await _copyUsers(legacyDb, plusDb);
  await _copyTodos(legacyDb, plusDb);

  await legacyDb.close();
  await plusDb.close();
}

Future<void> _copyUsers(legacy.Isar legacyDb, plus.Isar plusDb) async {
  const pageSize = 200;
  final total = await legacyDb.legacyUsers.count();

  for (var offset = 0; offset < total; offset += pageSize) {
    final batch = await legacyDb.legacyUsers
      .where()
      .offset(offset)
      .limit(pageSize)
      .findAll();
      
    await plusDb.writeAsync((isar) async {
      await isar.users.putAll(
        batch.map((user) => User(
          id: user.id ?? isar.users.autoIncrement(),
          email: user.email,
          status: _mapStatus(user.status),
        )),
      );
    });
  }
}

If you have very large collections, run the loop inside an isolate or background service to avoid blocking the UI. The same pattern works for embedded objects and links—load them with the legacy query API, then persist them with the new schema.

Make Sure It Only Runs Once

Shipping both runtimes means every cold start could try to migrate again unless you gate it behind a flag. Persist a migration version so the copy runs only once per installation:

class MigrationTracker {
  static const key = 'isarPlusMigration';

  static Future<bool> needsMigration() async {
    final prefs = await SharedPreferences.getInstance();
    return !prefs.getBool(key).toString().contains('true');
  }

  static Future<void> markDone() async {
    final prefs = await SharedPreferences.getInstance();
    await prefs.setBool(key, true);
  }
}

Future<void> bootstrapIsar(String dir) async {
  if (await MigrationTracker.needsMigration()) {
    await migrateLegacyDb(dir);
    await MigrationTracker.markDone();
  }

  final isar = plus.Isar.open(
    schemas: [UserSchema, TodoSchema],
    directory: dir,
  );

  runApp(MyApp(isar: isar));
}

Clean Up

After every collection finishes copying:

await prefs.setBool('migratedToIsarPlus', true);

await plus.Isar.deleteDatabase(
  name: 'legacy',
  directory: directoryPath,
  engine: plus.IsarEngine.isar,
);

Only when you are confident that users no longer open the legacy build should you ship an update that depends solely on isar_plus.

Troubleshooting

VersionError Persists

Duplicate Primary Keys

Generator Fails

Run cleanup before building:

dart pub clean
dart run build_runner build --delete-conflicting-outputs

Ensure no part '...g.dart'; directives are missing.

Need to Rollback

Once these steps are in place, users can upgrade directly from an isar 3.x build to an isar_plus release without data loss.