Isar v3'ten Isar Plus v4'e Geçiş

Eski isar 3.x paketlerinden isar_plus (v4) sürümüne yükseltmek kırıcı ve dosya formatını değiştiren bir işlemdir. v4 çekirdeği farklı metadata yazar ve v3 tarafından yazılan bir veritabanını açamaz, bu yüzden şu hatayı görürsünüz:

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

Çözüm; eski verilerinizi legacy çalışma zamanı ile dışa aktarıp taze bir Isar Plus veritabanına içe aktarmaktır. Aşağıdaki adımlar bu süreci anlatır.

Geçiş Özeti

Bağımlılıkları Yan Yana Güncelleyin

Kopya bitene kadar eski çalışma zamanını tutun, ardından yenisini ekleyin:

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

İki paket aynı Dart sembollerini dışa vurur, bu yüzden geçiş süresince her zaman alias kullanarak içe aktarın:

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

Şemalarınızı v4 İçin Yeniden Üretin

Isar Plus, üreticisini ana paketle birlikte getirir. Yeni yardımcılar ve adapter'ların üretilebilmesi için builder'ı tekrar çalıştırın:

dart run build_runner build --delete-conflicting-outputs

Burada durup derleme hatalarını giderin (örneğin, Id? alanlarının non-null int id olması gerekir ve otomatik üretilen ID'ler için collection.autoIncrement() kullanın).

API Geçiş Rehberi Temel Değişiklikler

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; // ❌ v3'te geçerliydi
  String? name;
}

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

  final int id; // ✅ Non-nullable, siz yönetirsiniz
  String? name;
}

// ✅ v4: Oluştururken auto-increment ID al
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>();

// Bunun yerine gömülü nesneler kullanın
List<Post> posts = [];

Benzersiz İndeksler

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

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

Linklerle İlgili Ayrıntılar

Projeniz yoğun şekilde IsarLink, IsarLinks veya @Backlink kullanıyorsa, verileri kopyalamadan önce bu ilişkileri yeni modele taşıyın. v4 çekirdeği yalnızca sıradan Dart alanlarını (skalerler, gömülü nesneler, List<T>) bilir; dolayısıyla her link ya gömülü bir nesneye ya da sizin yöneteceğiniz açık bir foreign-key ID'sine dönüşmelidir. Şu adımları izleyin:

1. Tüm legacy linkleri envanterleyin

• Modellerinizde IsarLink, IsarLinks ve @Backlink için arama yapın.
• Her ilişki için kardinaliteyi (bire bir, bire çok, çoktan çoka) not alın.
• İlgili verinin daima ebeveynle birlikte taşınıp taşınmadığına karar verin. Her zaman birlikteyse embed edin, değilse ID tutun.

2. Şemayı v4 terimleriyle yeniden yazın

• Embed edin: Her zaman ebeveynle gelen küçük listeler için alanı List<EmbeddedTip> veya nullable gömülü tipe çevirin.
• ID saklayın: Büyük koleksiyonlar veya bağımsız yaşam döngüsü gereken ilişkiler için int authorId, List<int> followerIds> gibi alanlar ekleyin ve sorgularla yükleyin.
• Backlink'leri açık referanslara çevirin; @Backlink(to: 'posts') yerine int authorId alanı ekleyin.

// 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; // eski author linki
  final List<TweetReaction> reactions; // likedBy linklerinin yerini alır
}

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

  final int userId;
  final DateTime createdAt;
}

Daha fazla örnek ve canlı referans için ilişkiler rehberine göz atın.

3. Mevcut veriyi dönüştürün

Kopyalama sırasında her linki elle materyalize edin ve yeni yapıya map'leyin:

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; // veya farklı bir strateji seçin
      }

      final reactions = legacyTweet.likedBy.map((user) {
        return TweetReaction(
          userId: user.id!,
          createdAt: DateTime.now(), // metadata saklıyorsanız burada kullanın
        );
      }).toList();

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

v3'te iki IsarLinks ile tuttuğunuz çoktan çoka ilişkiler için, her iki ID'yi bir arada saklayan açık bir join koleksiyonu oluşturun. Migrasyon sırasında link çiftlerini okuyup bu koleksiyona kendiniz ekleyin. Backlink yerine ise filtreli sorgular kullanın: user.posts yerine isar.posts.where().authorIdEqualTo(user.id) gibi.

Tüm linkler veri olarak ifade edildiğinde Isar Plus'a geçiş sıradan insert'lerden ibarettir ve projeden bütün IsarLink API'lerini kaldırabilirsiniz.

Verilerin Kendini Kopyalayın

Geçici bir geçiş rutini oluşturun (örneğin uygulamanızı başlatmadan önce main() içinde veya ayrı bir bin/migrate.dart dosyasında). Şablon şu şekildedir:

1. Legacy store'u v3 çalışma zamanı ile açın
2. Farklı bir dizinde veya farklı bir adla yeni bir v4 örneği açın
3. Her koleksiyonu sayfalayarak yeni şemaya eşleyin ve yeni veritabanına put edin
4. İşlemin iki kez çalışmaması için geçişi tamamlandı olarak işaretleyin

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, // native için IsarEngine.isar
    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),
        )),
      );
    });
  }
}

Çok büyük koleksiyonlarınız varsa UI'yi bloklamamak için döngüyü bir izolede veya arka plan servisinde çalıştırın. Aynı desen gömülü nesneler ve linkler için de geçerlidir—legacy sorgu API'siyle yükleyin ve yeni şema ile kaydedin.

Yalnızca Bir Kez Çalıştığından Emin Olun

Her iki çalışma zamanını aynı anda göndermek, her soğuk başlangıcın tekrar geçiş denemesi yapmasına yol açabilir. Rutini bir bayrakla sınırlandırın; böylece her kurulumda sadece bir kez çalışır:

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));
}

Temizlik

Her koleksiyonun kopyalanması bittiğinde:

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

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

Legacy build'i artık kullanıcılar açmadığından emin olduktan sonra yalnızca isar_plusa bağımlı bir güncelleme yayınlayın.

Sorun Giderme

VersionError Devam Ediyor

Yinelenen Birincil Anahtarlar

Üreteç Hata Veriyor

Derleme öncesinde temizlik yapın:

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

Hiçbir part '...g.dart'; yönergesinin eksik olmadığından emin olun.

Geri Dönmek İstiyorum

Bu adımları tamamladıktan sonra kullanıcılar isar 3.x sürümünden isar_plus yayınınıza veri kaybetmeden geçiş yapabilir.