Add disableFormatUpgrade to Realm configuration (#1566)

CHANGELOG.md

@@ -6,6 +6,7 @@ X.Y.Z Release notes
 
 ### Enhancements
 * Added property `Realm.isClosed` which indicates if a Realm instance is closed or not.
+* Added property `disableFormatUpgrade` to the Realm configuration object which disables automatic file format upgrade when opening a Realm file.
 
 ### Bug fixes
 * None.

docs/realm.js

@@ -307,6 +307,9 @@ Realm.defaultPath;
  *    what fits in memory, but it is not persistent and will be removed when the last instance
  *    is closed.
  * @property {boolean} [readOnly=false] - Specifies if this Realm should be opened as read-only.
+ * @property {boolean} [disableFormatUpgrade=false] - Specifies if this Realm's file format should
+ *    be automatically upgraded if it was created with an older version of the Realm library.
+ *    If set to `true` and a file format upgrade is required, an error will be thrown instead.
  * @property {Array<Realm~ObjectClass|Realm~ObjectSchema>} [schema] - Specifies all the
  *   object types in this Realm. **Required** when first creating a Realm at this `path`.
  *   If omitted, the schema will be read from the existing Realm file.

lib/index.d.ts

@@ -85,6 +85,7 @@ declare namespace Realm {
         schemaVersion?: number;
         sync?: Realm.Sync.SyncConfiguration;
         deleteRealmIfMigrationNeeded?: boolean;
+        disableFormatUpgrade?: boolean;
     }
 
     // object props type

src/js_realm.hpp

@@ -520,6 +520,12 @@ void RealmClass<T>::constructor(ContextType ctx, ObjectType this_object, size_t
             if (!Value::is_undefined(ctx, cache_value)) {
                 config.cache = Value::validated_to_boolean(ctx, cache_value, "_cache");
             }
+
+            static const String disable_format_upgrade_string = "disableFormatUpgrade";
+            ValueType disable_format_upgrade_value = Object::get_property(ctx, object, disable_format_upgrade_string);
+            if (!Value::is_undefined(ctx, disable_format_upgrade_value)) {
+                config.disable_format_upgrade = Value::validated_to_boolean(ctx, disable_format_upgrade_value, "disableFormatUpgrade");
+            }
         }
     }
     else {

tests/js/realm-tests.js

@@ -1181,4 +1181,12 @@ module.exports = {
             new Realm({schema: schema, deleteRealmIfMigrationNeeded: true, migration: function(oldRealm, newRealm) {}});
         }, "Cannot include 'migration' when 'deleteRealmIfMigrationNeeded' is set.")
     },
+
+    testDisableFileFormatUpgrade: function() {
+        Realm.copyBundledRealmFiles();
+
+        TestCase.assertThrowsContaining(() => { 
+            new Realm({ path: 'dates-v3.realm', disableFormatUpgrade: true } );
+        }, 'The Realm file format must be allowed to be upgraded in order to proceed.');
+    }
 };