10.6.0 - Runtime schema definition

Enhancements

• Added two extension methods on ISet to get an IQueryable collection wrapping the set:

  • set.AsRealmQueryable() allows you to get a IQueryable<T> from ISet<T> that can be then treated as a regular queryable collection and filtered/ordered with LINQ or Filter(string).
  • set.Filter(query, arguments) will filter the set and return the filtered collection. It is roughly equivalent to set.AsRealmQueryable().Filter(query, arguments).

  The resulting queryable collection will behave identically to the results obtained by calling realm.All<T>(), i.e. it will emit notifications when it changes and automatically update itself. (Issue #2555)

• Added two new methods on Migration (Issue #2543):

  • RemoveType(typeName) allows to completely remove a type and its schema from a realm during a migration.
  • RenameProperty(typeName, oldPropertyName, newPropertyName) allows to rename a property during a migration.

• A Realm Schema can now be constructed at runtime as opposed to generated automatically from the model classes. The automatic generation continues to work and should cover the needs of the vast majority of Realm users. Manually constructing the schema may be required when the shape of the objects depends on some information only known at runtime or in very rare cases where it may provide performance benefits by representing a collection of known size as properties on the class. (Issue #824)

  • RealmConfiguration.ObjectClasses has now been deprecated in favor of RealmConfiguration.Schema. RealmSchema has an implicit conversion operator from Type[] so code that previously looked like ObjectClasses = new[] { typeof(Foo), typeof(Bar) } can be trivially updated to Schema = new[] { typeof(Foo), typeof(Bar) }.
  • Property has been converted to a read-only struct by removing the setters from its properties. Those didn't do anything previously, so we don't expect anyone was using them.
  • Added several factory methods on Property to simplify declaration of Realm properties by being explicit about the range of valid options - e.g. Property.FromType<int>("IntProperty") or Property.Object("MyPersonProp", "Person"). The constructor of Property is now public to support advanced scenarios, but we recommend using the factory methods.
  • Made ObjectSchema.Builder public and streamlined its API. It allows you to construct a mutable representation of the schema of a single object and add/remove properties to it. You can either get an empty builder or you can see it with the information from an existing model class (i.e. inheriting from RealmObject or EmbeddedObject).
  • Made RealmSchema.Builder public and streamlined its API. It allows you to construct a mutable representation of the schema of an entire Realm and add/remove object schemas to it.
  • A simple example for how to use the new API would look like:

  public class Person : RealmObject
  {
    public string Name { get; set; }
    public Address Address { get; set; }
  }
  
  // Declare schema from existing model classes
  var config = new RealmConfiguration
  {
    Schema = new[] { typeof(Person), typeof(Address) }
  };
  
  // Manually construct a schema - we don't need to call .Build() on the builders
  // because we have implicit conversion operators defined that will call it for us.
  // Explicitly calling .Build() is also perfectly fine, if a little more verbose.
  var config = new RealmConfiguration
  {
    Schema = new RealmSchema.Builder
    {
      new ObjectSchema.Builder("MyClass", isEmbedded: false)
      {
        Property.FromType<int>("Id", isPrimaryKey: true),
        Property.PrimitiveDictionary("Tags", RealmValueType.String)
      },
      new ObjectSchema.Builder("EmbeddedClass", isEmbedded: true)
      {
        Property.Primitive("DateProp", RealmValueType.Date, isNullable: true)
      }
    }
  };
  
  // Enhance an existing model with new properties that will be accessible via
  // the dynamic API.
  var personSchema = new ObjectSchema.Builder(typeof(Person))
  {
    Property.FromType<string>("NewStringProp")
  };
  
  var config = new RealmConfiguration
  {
    Schema = new RealmSchema.Builder
    {
      personSchema,
      new ObjectSchema.Builder(typeof(Address))
    }
  };
  
  // Regular Person properties can be accessed as usual while runtime defined ones
  // need to go through the dynamic API.
  var person = realm.All<Person>().First();
  var name = person.Name;
  var stringPropValue = person.DynamicApi.Get<string>("NewStringProp");

• Fixed an issue that would result in SIGABORT on macOS/Linux when opening a Realm in dynamic mode (i.e. read the schema from disk) and the schema contains an object with no properties. (Issue #1978)

Compatibility

• Realm Studio: 11.0.0 or later.

Internal

• Using Core 11.4.1.
• Moved perf tests to run on a self-hosted runner. (PR #2638)

10.5.1 - Bug fixes

Fixed

• Fixed a bug that would cause a NullReferenceException to be reported during compilation of a class containing a getter-only RealmObject property. (Issue #2576)
• Fixed an issue that would result in Unable to load DLL 'realm-wrappers' when deploying a WPF .NET Framework application with ClickOnce. This was due to the incorrect BuildAction type being applied to the native libraries that Realm depends on. (Issue #1877)
• [Unity] Fixed an issue that would fail Unity builds with Multiple precompiled assemblies with the same name Mono.Cecil.dll if importing the Realm package into a project that already references Mono.Cecil. (Issue #2630)
• Fixed a bug that would sometimes result in assemblies not found at runtime in a very specific edge scenario. More details about such a scenario can be found in its PR's description. (Issue #1568)

Compatibility

• Realm Studio: 11.0.0 or later.

Internal

• Using Core 11.4.1.

10.5.0

Enhancements

• ThreadSafeReference no longer pins the source transaction version for anything other than a Results backed by a Query. (Core upgrade)
• A ThreadSafeReference to a Results backed by a collection can now be created inside a write transaction as long as the collection was not created in the current write transaction. (Core upgrade)
• Synchronized Realms are no longer opened twice, cutting the address space and file descriptors used in half. (Core upgrade)

Fixed

• If an object with a null primary key was deleted by another sync client, the exception KeyNotFound: No such object could be triggered. (Core upgrade)
• Fixed a race condition that could result in an assertion m_state == SyncUser::State::LoggedIn if the app previously crashed during user logout. (Core upgrade)

Compatibility

• Realm Studio: 11.0.0 or later.

Internal

• Using Core 11.4.1.
• Added an action to post releases to Slack. (Issue #2501)
• Added MSBuild inline task to extract the changelog of the latest version. (Issue #2558)
• When a release succeeds, merge the original PR, tag the release, then update changelog. (PR #2609)

10.4.1

Fixed

• Fixed a regression that would prevent the SDK from working on older Linux versions. (Issue #2602)
• Fixed an issue that manifested in circumventing the check for changing a primary key when using the dynamic API - i.e. myObj.DynamicApi.Set("Id", "some-new-value") will now correctly throw a NotSupportedException if "some-new-value" is different from myObj's primary key value. (PR #2601)

Compatibility

• Realm Studio: 11.0.0 or later.

10.4.0 - Bug fixes and small improvements

Fixed

• Fixed an issue that would cause Logger.Default on Unity to always revert to Debug.Log, even when a custom logger was set. (Issue #2481)
• Fixed an issue where Logger.Console on Unity would still use Console.WriteLine instead of Debug.Log. (Issue #2481)
• Added serialization annotations to RealmObjectBase to prevent Newtonsoft.Json and similar serializers from attempting to serialize the base properties. (Issue #2579)
• Fixed an issue that would cause an InvalidOperationException when removing an element from an UI-bound collection in WPF. (Issue #1903)
• User profile now correctly persists between runs. (Core upgrade)
• Fixed a crash when delivering notifications over a nested hierarchy of lists of RealmValue that contain RealmObject inheritors. (Core upgrade)
• Fixed a crash when an object which is linked to by a RealmValue property is invalidated (sync only). (Core upgrade)
• Fixes prior_size history corruption when replacing an embedded object in a list. (Core upgrade)
• Fixed an assertion failure in the sync client when applying an AddColumn instruction for a RealmValue property when that property already exists locally. (Core upgrade)
• Fixed an Invalid data type assertion failure in the sync client when applying an AddColumn instruction for a RealmValue property when that property already exists locally. (Core upgrade)

Enhancements

• Added two extension methods on IList to get an IQueryable collection wrapping the list:

  • list.AsRealmQueryable() allows you to get a IQueryable<T> from IList<T> that can be then treated as a regular queryable collection and filtered/ordered with LINQ or Filter(string).
  • list.Filter(query, arguments) will filter the list and return the filtered collection. It is roughly equivalent to list.AsRealmQueryable().Filter(query, arguments).

  The resulting queryable collection will behave identically to the results obtained by calling realm.All<T>(), i.e. it will emit notifications when it changes and automatically update itself. (Issue #1499)

• Added a cache for the Realm schema. This will speed up Realm.GetInstance invocations where RealmConfiguration.ObjectClasses is explicitly set. The speed gains will depend on the number and complexity of your model classes. A reference benchmark that tests a schema containing all valid Realm property types showed a 25% speed increase of Realm.GetInstance. (Issue #2194)

• Improve performance of creating collection notifiers for Realms with a complex schema. In the SDKs this means that the first run of a synchronous query, first call to subscribe for notifications will do significantly less work on the calling thread.

• Improve performance of calculating changesets for notifications, particularly for deeply nested object graphs and objects which have List or Set properties with small numbers of objects in the collection.

• Query parser now accepts BETWEEN operator. Can be used like realm.All<Person>().Filter("Age BETWEEN {20, 60}") which means "'Age' must be in the open interval ]20;60[". (Core upgrade)

Compatibility

• Realm Studio: 11.0.0 or later.

10.3.0 - Unity Support

This release marks our Unity support as GA. This means that our automated tests pass on all supported platforms. We've also done extensive manual testing and believe the SDK is of high enough quality for production use. Take a look at the docs for more information on how to get started or head over to MongoDB .live for a walkthrough of using the local database and Sync in a Unity game.

Note: This release uses xcframework and enables bitcode for the iOS native libraries. This significantly increases the package size and may appear to increase the .ipa size when compiling for iOS. However, the bitcode portion, as well as the unnecessary architectures, will be trimmed by the App Store, so the size of the actual download sent to users will be unchanged or smaller than before.

Fixed

• Fixed an issue that would prevent realm-wrappers.dll from being loaded on Windows 8.1. (Issue #2298)
• Fixed an assertion failure when listening for changes to a list of primitive Mixed which contains links. (Core upgrade)
• Fixed an assertion failure when listening for changes to a dictionary or set which contains an invalidated link. (Core upgrade)
• Fixed an endless recursive loop that could cause a stack overflow when computing changes on a set of objects which contained cycles. (Core upgrade)
• Add collision handling to Dictionary implementation. (Core upgrade)
• Fixed a crash after clearing a list or set of Mixed containing links to objects. (Core upgrade)
• Fixed a recursive loop which would eventually crash trying to refresh a user app token when it had been revoked by an admin. Now this situation logs the user out and reports an error. (Core upgrade)
• Fixed a race between calling Realm.DeleteRealm and concurrent opening of the realm file. (Core upgrade)
• [Unity] Added code to preserve the constructors of several base serializers to ensure that most of the basic serialization/deserialization workloads work out of the box. (PR #2489)

Enhancements

• Changed the native iOS library to use xcframework. This means that running in the simulator on M1 macs is now supported. (Issue #2240)
• Added bitcode to the native iOS library. This has no effect on Xamarin.iOS, but allows Unity applications to take advantage of optimizations performed by the App Store servers and eventually support new architectures as they are released. (Issue #2240)

Compatibility

• Realm Studio: 11.0.0 or later.
• This release uses xcframework for the iOS native libraries, which requires Xamarin.iOS 14.14.2.5 or later.

10.2.1 - New Unity package format

This release changes the way Unity binaries are packaged and obviates the need to have an extra Unity package that contains the dependencies as standalone modules. If you were using the io.realm.unity-bundled package, please remove it and add the newly released io.realm.unity one.

Fixed

• [Unity] Fixed an issue where failing to weave an assembly due to modeling errors, would only show an error in the logs once and then fail opening a Realm with No RealmObjects. Has linker stripped them?. Now, the weaving errors will show up on every code change/weave attempt and the runtime error will explicitly suggest manually re-running the weaver. (Issue #2310)
• [Unity] Fixed an issue that would cause the app to hang on exit when using Sync. (PR #2467)
• [Unity] Fixed an issue that would cause the Unity editor on macOS to hang after assembly reload if the app uses Sync. (Issue #2482)
• Fixed an issue where a crash could happen on Android x86 due to converting UInt32 into TableKey and Int64 into ObjKey incorrectly. (Issue #2456)

Compatibility

• Realm Studio: 11.0.0 or later.

10.2.0 - New datatypes and Unity improvements

This release adds SDK support for four new datatatypes - Guid, RealmValue, ISet<TValue>, and IDictionary<string, TValue>.

NOTE: This version upgrades the Realm file format version to add support for the new data types and to adjust how primary keys are handled. Realm files opened will be automatically upgraded and cannot be read by versions older than v10.2.0. This upgrade should be a fairly fast one. Note that we now automatically create a backup of the pre-upgrade Realm.

Enhancements

• Add support for the Guid data type. It can be used as primary key and is indexable. (PR #2120)

• Add support for dictionaries. Currently only string keys are supported, while the value type may be any of the supported types (the primitive types, RealmValue, or custom types that inherit from RealmObject/EmbeddedObject). Lists, sets, or other dictionaries may not be used as the value type. To add a dictionary to your model, define a getter-only property of type IDictionary<string, T>:

  public class MyObject : RealmObject
  {
      public IDictionary<string, decimal> Denominations { get; }
  }
  
  // Realm will automatically manage the underlying dictionary, so there's no need
  // to define a constructor  or assign it to some value.
  
  var obj = new MyObject();
  obj.Denominations.Add("quarter", 0.25d);

• Add support for RealmValue data type. This new type can represent any valid Realm data type, including objects. Collections (lists, sets and dictionaries) of RealmValue are also supported, but RealmValue itself cannot contain collections. Please note that a property of type RealmValue cannot be nullable, but can contain null, represented by the value RealmValue.Null. (PR #2252)

  public class MyObject : RealmObject
  {
      public RealmValue MyValue { get; set; }
  
      public IList<RealmValue> ValuesList { get; }
  
      public ISet<RealmValue> ValuesSet { get; }
  
      public IDictionary<string, RealmValue> ValuesDict { get; }
  }
  
  var obj = new MyObject();
  obj.MyValue = RealmValue.Null;
  obj.MyValue = 1;
  obj.MyValue = "abc";
  
  if (obj.MyValue.Type == RealmValueType.String)
  {
      var myString = obj.MyValue.AsString();
  }

• Add support for sets of objects or primitive values. Sets are unordered collections that ensure uniqueness of their elements. Realm uses its internal equality comparer and it is not possible to customize its behavior by overriding Equals or GetHashCode on your custom classes. Objects will always be compared by db reference - i.e. two distinct objects in the database will always be different, even if their contents are identical, and multiple references to the same database object will always be equal.

  public class MyObject : RealmObject
  {
      public ISet<string> UniqueStrings { get; }
  }
  
  // Realm will automatically manage the underlying set, so there's no need
  // to define a constructor  or assign it to some value.
  
  var obj = new MyObject();
  var didAdd = obj.UniqueStrings.Add("foo"); // true
  didAdd = obj.UniqueStrings.Add("foo"); // false

• Added support for value substitution in string based queries. This enables expressions following this syntax: realm.All<T>().Filter("field1 = $0 && field2 = $1", 123, "some-string-value"). (Issue #1822)

• Reduced the size of the native binaries by ~5%. (PR #2239)

• Added a new class - Logger, which allows you to override the default logger implementation (previously writing to stdout or stderr) with a custom one by setting Logger.Default. This replaces AppConfiguration.CustomLogger and AppConfiguration.LogLevel which will be removed in a future release. The built-in implementations are:

  • Console - uses the System.Console for most projects and UnityEngine.Debug for Unity projects: Logger.Default = Logger.Console;
  • Null - ignores all messages: Logger.Default = Logger.Null;
  • Function - proxies calls to a supplied function: Logger.Default = Logger.Function(message => myExternalLogger.Log(message));

  Custom loggers can derive from the Logger class and provide their own implementation for the Log method or use Function and provide an Action<string>. (PR #2276)

• RealmObjectBase now correctly overrides and implements GetHashCode(). (Issue #1650)

• Added an override of RealmObject.ToString() to output more meaningful information about the object content. It will output the type of the object, the primary key (if one is defined), as well as information whether the object is managed or deleted. (Issue #2347)

• Added new API for dynamically accessing object properties. These are designed to support ahead-of-time compiled platforms, such as Xamarin.iOS and Unity with IL2CPP compilation. The
  intention is to eventually make these the default API, while also supporting the legacy DLR-based API. Example:

  // Make sure to cast away the dynamic immediately on AOT platforms.
  var people = (IQueryable<RealmObject>)realm.DynamicApi.All("Person");
  foreach (var person in people)
  {
      var firstName = person.DynamicApi.Get<string>("FirstName");
      var address = person.DynamicApi.Get<EmbeddedObject>("Address");
      var city = address.DynamicApi.Get<string>("City");
  }
  
  // When casting a dynamic object, always cast first to object and then
  // to the actual object type to remove any callsites being generated.
  var newPerson = (RealmObject)(object)realm.DynamicApi.Create("Person", 123);
  newPerson.DynamicApi.Set("FirstName", "Peter");

• Added a Unity Editor option to enable weaving editor assemblies. This should be "off" unless your project has Editor assemblies that reference Realm - for example, an EditMode test assembly that tests Realm-related functionality. Keeping it "on" may slow down builds a little as more assemblies will need to be evaluated for weaving. (Issue #2346)

• We now make a backup of the realm file prior to any file format upgrade. The backup is retained for 3 months. Backups from before a file format upgrade allows for better analysis of any upgrade failure. We also restore a backup, if a) an attempt is made to open a realm file whith a "future" file format and b) a backup file exist that fits the current file format. (#4166)

Fixed

• Fixed a bug where applying multiple OrderBy clauses on a query would result in the clauses being appended to each other as if they were .ThenBy rather than the last clause replacing the preceding ones. (PR #2255)
• When explicitly specifying SyncConfiguration.ObjectTypes, added a check to validate the schema and ensure all EmbeddedObject classes are reachable from a class inheriting from RealmObject. More info about this subject can be found here. (PR #2259)
• Fixed a bug that would result in an error similar to Undefined symbols for architecture xxx: "_realm_thread_safe_reference_destroy" when building a Unity project for iOS. (Issue #2318)
• The weaver will now emit an error if you try to define a collection of RealmInteger values. This has never been supported, but previously it would fail silently whereas now it'll be a compile time error. (Issue #2308)
• Fixed an issue where using collections of managed objects (lists or results) in a Unity project would result in an invalid compiled binary. (PR #2340)
• Fixed a memory leak when a migration callback is defined, but the Realm didn't actually need to run it (PR #2331)
• Added back 32bit support for iOS builds. (Issue #2429)
• Removed redundant warnings when building a Unity project for device that mentioned that the schema for Realm and Realm.UnityUtils is empty. (Issue #2320)
• Fixed an issue that could cause NullReferenceException to be thrown if you set SyncConfiguration.OnProgress to null shortly after calling Realm.GetInstanceAsync(syncConfig). (Issue #2400)
• When replacing an embedded object, emit a sync instruction that sets the link to the embedded object to null so that it is properly cleared. This resolves an issue that would have manifested itself as Failed to parse, or apply received changeset: ERROR: ArrayInsert: Invalid prior_size (list size = 4, prior_size = 0) (Issue #4740
• Made Linux implementation of ExternalCommitHelper work with new versions of Linux that changed epoll behavior, including Android 12 (Issue #4666)
• The file format is changed in the way that we now - again - have search indexes on primary key columns. This is required as we now stop deriving the ObjKeys from the primary key values, but just use an in...

10.1.4 - Bug fixes

Fixed

• Fixed a bug that could lead to crashes with a message similar to Invalid ref translation entry [0, 78187493520]. (Core upgrade)
• Fix assertion failures such as !m_notifier_skip_version.version or m_notifier_sg->get_version() + 1 == new_version.version when performing writes inside change notification callbacks. (Core upgrade)
• Fix collection notification reporting for modifications. This could be observed by receiving the wrong indices of modifications on sorted or distinct results, or notification blocks sometimes not being called when only modifications have occurred. (Core upgrade)
• Proactively check the expiry time on the access token and refresh it before attempting to initiate a sync session. This prevents some error logs from appearing on the client such as: ERROR: Connection[1]: Websocket: Expected HTTP response 101 Switching Protocols, but received: HTTP/1.1 401 Unauthorized. (Core upgrade)
• Destruction of the TableRecycler at exit was unordered compared to other threads running. This could lead to crashes, some with the TableRecycler at the top of the stack. (Core upgrade)
• Fixed errors related to uncaught exception in notifier thread: N5realm11KeyNotFoundE: No such object. This could happen in a synchronized app when a linked object was deleted by another client. (Core upgrade)
• Opening a metadata realm with the wrong encryption key or different encryption configuration will remove that metadata realm and create a new metadata realm using the new key or configuration. (Core upgrade)
• Creating a ThreadSafeReference to a readonly Realm would result in a crash. (Core upgrade)

Unity support

The Unity packages are very early previews and are considered unstable. We do not recommend using them in production because issues are expected, especially when compiling with IL2CPP.

10.2.0-beta.2 - Bug fixes

Fixed

• Fixed a bug that would result in an error similar to Undefined symbols for architecture xxx: "_realm_thread_safe_reference_destroy" when building a Unity project for iOS. (Issue #2318)
• The weaver will now emit an error if you try to define a collection of RealmInteger values. This has never been supported, but previously it would fail silently whereas now it'll be a compile time error. (Issue #2308)
• Fixed an issue where using collections of managed objects (lists or results) in a Unity project would result in an invalid compiled binary. (PR #2340)
• Fixed a memory leak when a migration callback is defined, but the Realm didn't actually need to run it (PR #2331)

Enhancements

• Added an override of RealmObject.ToString() to output more meaningful information about the object content. It will output the type of the object, the primary key (if one is defined), as well as information whether the object is managed or deleted. (Issue #2347)

Unity support

The Unity packages are very early previews and are considered unstable. We do not recommend using them in production because issues are expected, especially when compiling with IL2CPP.