configuration - disable format upgrade

CHANGELOG.md

@@ -7,6 +7,13 @@ x.x.x Release notes (yyyy-MM-dd)
 * Made all `Configuration` fields final so they can only be initialized in the constructor. This better conveys the immutability of the configuration class. ([#455](https://github.com/realm/realm-dart/pull/455))
 
 ### Enhancements
+* Added a new `Configuration` option: `disableFormatUpgrade`. When set to `true`, opening a Realm with an older file format will throw an exception to avoid automatically migrating it. ([#310](https://github.com/realm/realm-dart/pull/310))
+    ```dart
+    var config = Configuration([Car.schema], disableFormatUpgrade: true);
+    await File('old-format.realm').copy(config.path);
+    var realm = Realm(config);
+    //Opening 'Realm' will throw a RealmException with message: "The Realm file format must be allowed to be upgraded in order to proceed." 
+    ```
 * Support result value from write transaction callbacks ([#294](https://github.com/realm/realm-dart/pull/294/))
 * Added a property `Realm.isInTransaction` that indicates whether the Realm instance has an open write transaction associated with it.
 * Support anonymous application credentials ([#443](https://github.com/realm/realm-dart/pull/443/))

lib/src/configuration.dart

@@ -34,7 +34,7 @@ class Configuration {
 
   /// Creates a [Configuration] with schema objects for opening a [Realm].
   Configuration(List<SchemaObject> schemaObjects,
-      {this.fifoFilesFallbackPath, this.isReadOnly = false, this.isInMemory = false, this.schemaVersion = 0, String? path})
+      {String? path, this.fifoFilesFallbackPath, this.isReadOnly = false, this.isInMemory = false, this.schemaVersion = 0, this.disableFormatUpgrade = false})
       : schema = RealmSchema(schemaObjects),
         path = path ?? defaultPath;
 
@@ -99,6 +99,11 @@ class Configuration {
   /// The FIFO special files are very lightweight and the main [Realm] file will still be stored in the location defined
   /// by the [path] you  property. This property is ignored if the directory defined by [path] allow FIFO special files.
   final String? fifoFilesFallbackPath;
+
+  /// Specifies if a [Realm] file format should be automatically upgraded
+  /// if it was created with an older version of the [Realm] library.
+  /// An exception will be thrown if a file format upgrade is required.
+  final bool disableFormatUpgrade;
 }
 
 /// A collection of properties describing the underlying schema of a [RealmObject].

lib/src/native/realm_core.dart

@@ -143,16 +143,20 @@ class _RealmCore {
       final configHandle = ConfigHandle._(configPtr);
       _realmLib.realm_config_set_schema(configHandle._pointer, schemaHandle._pointer);
       _realmLib.realm_config_set_schema_version(configHandle._pointer, config.schemaVersion);
-
-      final schemaMode = config.isReadOnly ? realm_schema_mode.RLM_SCHEMA_MODE_IMMUTABLE : realm_schema_mode.RLM_SCHEMA_MODE_AUTOMATIC;
-      _realmLib.realm_config_set_schema_mode(configHandle._pointer, schemaMode);
-      _realmLib.realm_config_set_in_memory(configHandle._pointer, config.isInMemory);
-
+      _realmLib.realm_config_set_path(configHandle._pointer, config.path.toUtf8Ptr(arena));
+      _realmLib.realm_config_set_scheduler(configHandle._pointer, schedulerHandle._pointer);
+      if (config.isReadOnly) {
+        _realmLib.realm_config_set_schema_mode(configHandle._pointer, realm_schema_mode.RLM_SCHEMA_MODE_IMMUTABLE);
+      }
+      if (config.isInMemory) {
+        _realmLib.realm_config_set_in_memory(configHandle._pointer, config.isInMemory);
+      }
       if (config.fifoFilesFallbackPath != null) {
         _realmLib.realm_config_set_fifo_path(configHandle._pointer, config.fifoFilesFallbackPath!.toUtf8Ptr(arena));
       }
-      _realmLib.realm_config_set_path(configHandle._pointer, config.path.toUtf8Ptr(arena));
-      _realmLib.realm_config_set_scheduler(configHandle._pointer, schedulerHandle._pointer);
+      if (config.disableFormatUpgrade) {
+        _realmLib.realm_config_set_disable_format_upgrade(configHandle._pointer, config.disableFormatUpgrade);
+      }
 
       return configHandle;
     });

test/configuration_test.dart

@@ -143,4 +143,21 @@ Future<void> main([List<String>? args]) async {
     final realm2 = getRealm(config);
     expect(realm1.config, isNot(realm2.config));
   });
+
+  test('Configuration - disableFormatUpgrade=true throws error', () async {
+    final realmBundleFile = "test/data/realm_files/old-format.realm";
+    var config = Configuration([Car.schema], disableFormatUpgrade: true);
+    await File(realmBundleFile).copy(config.path);
+    expect(() {
+      Realm(config);
+    }, throws<RealmException>("The Realm file format must be allowed to be upgraded in order to proceed"));
+  }, skip: isFlutterPlatform);
+
+  test('Configuration - disableFormatUpgrade=false', () async {
+    final realmBundleFile = "test/data/realm_files/old-format.realm";
+    var config = Configuration([Car.schema], disableFormatUpgrade: false);
+    await File(realmBundleFile).copy(config.path);
+    var realm = Realm(config);
+    realm.close();
+  }, skip: isFlutterPlatform);
 }

test/test.dart

@@ -118,28 +118,16 @@ Future<void> setupTests(List<String>? args) async {
       }
 
       for (final path in paths) {
-        var file = File(path);
         try {
           Realm.deleteRealm(path);
         } catch (e) {
           fail("Can not delete realm at path: $path. Did you forget to close it?");
         }
-
-        if (await file.exists() && file.path.endsWith(".realm")) {
-          await tryDeleteFile(file);
-        }
-
-        file = File("$path.lock");
-        if (await file.exists()) {
-          await tryDeleteFile(file);
-        }
-
-        final dir = Directory("$path.management");
-        if (await dir.exists()) {
-          if ((await dir.stat()).type == FileSystemEntityType.directory) {
-            await tryDeleteFile(dir, recursive: true);
-          }
-        }
+        String pathKey = _path.basenameWithoutExtension(path);
+        String realmDir = _path.dirname(path);
+        await Directory(realmDir).list().forEach((f) {
+          if (f.path.contains(pathKey)) tryDeleteFile(f, recursive: true);
+        });
       }
     });
   });