Realm .NET enables you to efficiently write your app’s model layer in a safe, persisted, and fast way. Here’s what it looks like:

// Define your models like regular C# classes
public class Dog : RealmObject
{
    public string Name { get; set; }
    public int Age { get; set; }
    public Person Owner { get; set; }
}

public class Person : RealmObject
{
    public string Name { get; set; }
    public IList<Dog> Dogs { get; }
}

var realm = Realm.GetInstance();

// Use LINQ to query
var puppies = realm.All<Dog>().Where(d => d.Age < 2);

puppies.Count(); // => 0 because no dogs have been added yet

// Update and persist objects with a thread-safe transaction
realm.Write(() =>
{
    realm.Add(new Dog { Name = "Rex", Age = 1 });
});

// Queries are updated in realtime
puppies.Count(); // => 1

// LINQ query syntax works as well
var oldDogs = from d in realm.All<Dog>() where d.Age > 8 select d;

// Query and update from any thread
new Thread(() =>
{
    var realm2 = Realm.GetInstance();

    var theDog = realm2.All<Dog>().Where(d => d.Age == 1).First();
    realm2.Write(() => theDog.Age = 3);
}).Start();

Getting Started

You install Realm via NuGet, or you can browse the source code on GitHub.

Prerequisites

We support the following platforms:

• Xamarin.iOS for iOS 7 or later, using native UI or Xamarin Forms
• Xamarin.Android for API level 10 or later, using native UI or Xamarin Forms
• Xamarin.Mac for macOS 10.11 or later, using nativeUI or Xamarin Forms
• .NET Framework 4.6.1 or later for Windows 8.1 or later
• Universal Windows Platform applications using .NET Standard 1.4 or later
• .NET Core 1.1 or later on:
  • Ubuntu 16.04 or later
  • Debian 8 or later
  • RHEL 7.1 or later
  • macOS 10.11 or later
  • Windows 10 or later

And the following environments:

• Visual Studio 2015 Update 2 or higher
• Visual Studio for Mac 7.0 or higher

Using .NET Core on Linux requires a token for the Professional or Enterprise Edition of the Realm Platform.

Important note for PCL users: this works via the NuGet Bait and Switch Trick. You must install the Realm NuGet package into every PCL that uses Realm as well as each of your platform-specific projects, i.e., your final app for iOS and Android. If you are using shared projects, you only have to install the NuGet into each platform-specific project.

Android ABI Support

Due to some instruction set limitations, we do not support the armeabi ABI setting.

The default templates that create new Xamarin projects currently have all ABI settings checked, for Debug builds, but only armeabi on Release. You must change this before doing your own Release builds.

If you do not have other ABIs checked, a System.TypeInitializationException may occur when a user runs on a different device. For example, deploying on a 64-bit device such as a Galaxy Tab S2 will cause that error if you have armeabi and armeabi-v7a but not arm64-v8a checked.

Unless you have a good reason to avoid linking other ABIs, the best thing to do is to check all of them other than armeabi, so you want checked:

• armeabi-v7a
• arm64-v8a
• x86
• x86_64

In Visual Studio for Mac, these settings are from right-clicking a project’s Options - Build - Android Build - Advanced Tab.

In Visual Studio on Windows, these settings are from right-clicking a project’s Properties - Android Options - Advanced Tab.

Installation

• Visual Studio for Mac
• Visual Studio on Windows

<?xml version="1.0" encoding="utf-8" ?>
<Weavers>
    <RealmWeaver />
</Weavers>

<?xml version="1.0" encoding="utf-8" ?>
<Weavers>
    <RealmWeaver />
</Weavers>

Realm Studio

Realm Studio is our premiere developer tool, built so you can easily manage the Realm Database and Realm Platform. With Realm Studio, you can open and edit local and synced Realms, and administer any Realm Object Server instance. It supports Mac, Windows and Linux.

API Reference

You can consult our full API reference for all classes, methods & more.

Examples

You can find a number of examples in our repository in the examples folder.

Getting Help

• Need help with your code? Ask on StackOverflow. We actively monitor & answer questions on SO!
• Have a bug to report? Open an issue on our repo. If possible, include the version of Realm, as much logging output as possible, the Realm file, and a project that shows the issue.
• Have a feature request? Open an issue on our repo. Tell us what the feature should do, and why you want the feature.

Models

Realm data models are defined using traditional C# classes with properties. Simply subclass RealmObject to create your Realm data model objects.

Realm model objects mostly function like any other C# objects – you can add your own methods and events to them and use them like you would any other object. The main restrictions are that you can only use an object on the thread which it was created, and persisted properties have generated getters and setters.

Also, note that your class must have a public, parameterless constructor. If you don’t add any constructors, the compiler will add this for you. However, if you add at least one constructor to your class, make sure there is a public parameterless one as well.

Relationships and nested data structures are modeled simply by including properties of the target type or IList for typed lists of objects.

// Dog model
public class Dog : RealmObject
{
    public string Name { get; set; }
    public int Age { get; set; }
    public Person Owner { get; set; }
}

public class Person : RealmObject
{
    public string Name { get; set; }
    public IList<Dog> Dogs { get; }
}

Supported Types

Realm supports primitive types except unsigned ones (bool, char, byte, short, int, long, float and double) as well as string, and DateTimeOffset. The nullable equivalents are supported as well, described further in Optional Properties.

Collections

Using collections of supported objects is done by declaring a property of type IList<T> where T is any supported type:

public class Image : RealmObject
{
    // Other properties...

    public IList<string> Tags { get; }

    public IList<double?> Ratings { get; }
}

The collection properties emit change notifications (see Collection Notifications for more details) and can contain both primitive types - integers, strings, etc. - and other objects (see To-Many Relationships). Modifying the collection (e.g. adding or removing items) must happen in a write transaction:

var image = ...;
realm.Write(() =>
{
    image.Tags.Add("sunset");
    image.Ratings.Move(from: 2, to: 5);
});

Date Type

We use the standard DateTimeOffset type as our main type for representing dates, rather than DateTime.

This is based on the recommendation from Microsoft due to ambiguities in DateTime.

It is stored down to full precision of 100-nanosecond Ticks.

Whilst you can specify a DateTimeOffset using a timezone, we store the UTC value. This is an unambiguous representation which will mean the same instant if read with other languages. However, because we lose the timezone specifier, this may cause confusion if you compare values using Ticks instead of UtcTicks.

Counters

Realm offers RealmInteger<T> as a special integer type. RealmInteger<T> exposes an additional API that can more clearly express intent and generate better conflict resolution steps when using Synchronized Realms. The type argument, T, can be either byte, short, int, or long.

Traditionally, a counter would be implemented by reading a value, incrementing it and setting it (myObject.Counter += 1). This will not work well in an asynchronous situation—for example when two clients are offline—because both parties will read a value, say 10, increment it, and store the value as 11. Eventually, when they regain connectivity and try to merge their changes, they’ll agree that the counter is at 11 rather than the expected 12.

RealmIntegers are backed by traditional integer types, so no migration is required when changing a property type from T to RealmInteger<T>.

public class MyObject : RealmObject
{
    [PrimaryKey]
    public int Id { get; set; }

    public RealmInteger<int> Counter { get; set; }
}

To increment the counter, simply call Increment:

var obj = realm.Find<MyObject>(1);
obj.Counter; // 0
obj.Counter.Increment(); // 1
obj.Counter.Decrement(); // 0
obj.Counter.Increment(2); // 2
obj.Counter.Increment(-5); // -3

To reset the counter, just assign it a new value. Keep in mind that in this case, regular merge rules apply and care must be taken to ensure proper semantics in your app:

var obj = realm.Find<MyObject>(1);
obj.Counter = 0; // Resetting to 0

Because RealmInteger<T> is implicitly convertible to and from T, you can use it without casting or without manually constructing it:

var obj = new MyObject
{
    Counter = 3
};
realm.Write(() => realm.Add(obj));

DoSomething(obj.Counter);

public void DoSomething(int value)
{
    // ...
}

Relationships

RealmObjects can be linked to each other by using RealmObject and IList properties.

For lists, you declare classes with an IList property and an implementing object will be created when the getter is first used. You should only specify a get; automatic method as there is no way to set such a list.

To-One Relationships

For many-to-one or one-to-one relationships, simply declare a property with the type of your RealmObject subclass.

public class Dog : RealmObject
{
    // ... other property declarations
    public Person Owner { get; set; };
}

public class Person : RealmObject
{
    public string Name { get; set; }
}

You can use this property like you would any other:

realm.Write(() =>
{
    var jim = realm.Add(new Person { Name = "Jim" });

    var rex = realm.Add(new Dog { Owner = jim });
});

To break the relationship, simply assign null:

rex.Owner = null;

When using RealmObject properties, you can access nested properties using normal property syntax. For example rex.Owner.Address.Country will traverse the object graph and automatically fetch each object from Realm as needed.

To-Many Relationships

You can define a to-many relationship using IList properties. When you use these properties, you get back a collection which may be empty or contains related RealmObjects of a single type.

To add a “Dogs” property on our Person model that links to multiple dogs, we simply declare it as an IList<Dog> property. You don’t have to initialize the IList – the Realm SDK takes care of that for you. Just add and delete Dog objects from the list to establish the relationship between a given Person and a Dog.

public class Dog : RealmObject
{
    public string Name { get; set; }
}

public class Person : RealmObject
{
    // ... other property declarations
    public IList<Dog> Dogs { get; }
}

jim.Dogs.Add(rex);
jim.Dogs.Count();  // => 1 -- nobody but rex

Inverse Relationships

Links are unidirectional. So if a to-many property Person.Dogs links to a Dog instance and a to-one property Dog.Owner links to Person, these links are independent from one another. Appending a Dog to a Person instance’s Dogs property doesn’t automatically set the dog’s Owner property to this Person. Because manually synchronizing pairs of relationships is error prone, complex and duplicates information, Realm provides backlink properties to represent these inverse relationships.

With backlink properties, you can obtain all objects that link to a given object from a specific property. For example, a Dog object can have a property named Owners that contains all of the Person objects that have this exact Dog object in their Dogs property. This is done by making the Owners property of type IQueryable<Person> and then applying the [Backlink] attribute to indicate the relationship that Owners has with the Person model objects.

public class Dog : RealmObject
{
    [Backlink(nameof(Person.Dogs))]
    public IQueryable<Person> Owners { get; }
}

A backlink property can point either to an IList<RealmObject> property (to-many relationship) or a RealmObject property (to-one relationship):

public class Ship : RealmObject
{
    public Captain Captain { get; set; }
}

public class Captain : RealmObject
{
    [Backlink(nameof(Ship.Captain))]
    public IQueryable<Ship> Ships { get; }
}

Optional Properties

Reference types such as string, byte[] and related RealmObject values can be null.

Nullable value types such as int? are fully supported.

We also support the optional DateTimeOffset? to complete the full range of having an optional version of each property type.

Controlling Property Persistence

Classes which descend from RealmObject are processed by the Fody weaver at compilation time. All their properties that have automatic setters and getters are presumed to be persistent and have setters and getters generated to map them to the internal Realm storage.

We also provide some C# attributes to add metadata to control persistence.

To avoid a property being made persistent, simply add the [Ignored] attribute. A common example is using external media, where you could persist the path to a file but not the binary image:

public string HeadshotPath { get; set; }

// Image in memory during run
[Ignored]
public Image Headshot { get; set; }

Custom Setters

Properties which have their own setter or getter implementation are automatically ignored. You can use this to add validation:

private string Email_ { get; set; }

// Validating version of persistent Email_ property
public string Email
{
    get { return Email_; }
    set
    {
        if (!value.Contains("@")) throw new Exception("Invalid email address");
        Email_ = value;
    }
}

Indexed Properties

Currently only strings, integers, booleans and DateTimeOffset can be indexed.

Indexing a property will greatly speed up queries where the property is compared for equality (i.e. the == and Contains operators), at the cost of slower insertions.

To index a property, simply add the [Indexed] attribute to the property declaration, e.g.:

public class Person : RealmObject
{
    [Indexed]
    public string Name { get; set; }
    public IList<Dog> Dogs { get; }
}

Mapped Properties

Realm files are inherently platform agnostic and can be opened or synchronized with any of the available bindings. To do that, the schema should be identical for different languages, including casing of property names. To avoid writing non-standard C# classes you can use the [MapTo] attribute, e.g.:

// C# model
public class Person : RealmObject
{
    [MapTo("name")]
    public string Name { get; set; }

    [MapTo("dogs")]
    public IList<Dog> Dogs { get; }
}

// Equivalent js model
class Person {}
Person.schema = {
  name: 'Person',
  properties: {
    name: {type: 'string'},
    dogs: {type: 'list', objectType: 'Dog'}
  }
};

Auto-Updating Objects

As soon as an instance of a RealmObject is managed, it becomes a live, auto-updating views into the underlying data, which means objects never have to be refreshed. Modifying the properties of an object will immediately reflect in any other instances referring to the same object.

var myDog = new Dog { Name = "Fido", Age = 1 };
realm.Write(() =>
{
    realm.Add(myDog);
});

var myPuppy = realm.All<Dog>().First(d => d.Age == 1);
realm.Write(() =>
{
    myPuppy.Age = 2;
}

myDog.Age; // => 2

This aspect of RealmObject not only keeps Realm fast and efficient, it allows your code to be simpler and more reactive. For example, if your UI code is dependent on a specific Realm object, you don’t need to worry about refreshing or re-fetching it before triggering a UI redraw.

You can subscribe to Realm notifications to know when Realm data in an object is updated, indicating when your app’s UI should be refreshed.

PrimaryKey Properties

The [PrimaryKey] attribute can be specified on one property in a RealmObject class. Declaring a PrimaryKey allows objects to be looked up and updated efficiently and enforces uniqueness for each value.

Only chars, integral types, and strings can be used as PrimaryKeys. There is no particular storage or performance advantage to using char or smaller integer types. They are supported only in case you already have a property of that type.

Putting the [PrimaryKey] attribute on multiple properties will compile but is validated at runtime and will throw an exception reporting that Schema validation failed, as soon as you try to open that Realm.

Once an object with a PrimaryKey is added to a Realm, the PrimaryKey cannot be changed.

Trying to create another object with the same key will throw a RealmDuplicatePrimaryKeyValueException.

You can retrieve an object by PrimaryKey very quickly using Realm.Find which performs more streamlined query construction than using LINQ, as well as using an index. It is overloaded to take string, character or integer keys, eg:

public class Person : RealmObject
{
    [PrimaryKey]
    public string SSN { get; set; }
    public string Name { get; set; }
    public IList<Dog> Dogs { get; }
}

var objByPK = realm.Find<Person>("457-55-5462");

Model Inheritance

Realm .NET does not allow models to be further subclassed in any way. The weaver will fail if it detects a class that inherits indirectly from the RealmObject class.

Collections

Realm uses standard types to represent groups of objects:

1. IQueryable<T>, a class representing objects retrieved from queries.
2. IList<T>, a class representing to-many relationships in models.

At runtime, both conform to the IRealmCollection<T> interface which in turn conforms to IReadOnlyList<T> and INotifyCollectionChanged and supports lazy enumeration - the size of the collection is known but objects are only loaded into memory as you iterate the collection.

Writes

To share objects between threads or re-use them between app launches, you must persist them to a Realm, an operation which must be done within a write transaction.

Since write transactions incur non-negligible overhead, you should architect your code to minimize the number of write transactions, i.e. if inserting multiple items in a loop, prefer to do it in a single transaction, rather than creating a transaction for each item, e.g.:

realm.Write(() =>
{
    var people = Realm.All<Person>();
    foreach (var person in people)
    {
        person.Age += 1;
    }
});

Because write transactions could potentially fail like any other disk IO operations, you should be prepared to handle exceptions from writes so you can handle and recover from failures like running out of disk space. There are no other recoverable errors. For brevity, our code samples don’t handle these errors but you certainly should in your production applications.

There are two easy ways to create write transactions: Realm.BeginWrite() and Realm.Write(). The first one, Realm.BeginWrite() returns a Transaction which implements the Dispose pattern, allowing you to use it with using:

using(var transaction = realm.BeginWrite())
{
    person.FirstName = "John";
    person.Age = 56;
    transaction.Commit();
}

Note that you must explicitly Commit the transaction, or it will automatically be rolled back. The other way is to wrap your mutating code with Realm.Write():

realm.Write(() =>
{
    person.FirstName = "John";
    person.Age = 56;
});

Here, the implicit transaction will be committed by default unless an exception was thrown.

Also see the Realm.WriteAsync() discussion below under Threading.

Creating Objects

When you have defined a model you can instantiate your RealmObject subclass and add the new instance to the Realm. Consider this simple model:

public class Dog : RealmObject
{
    public string Name { get; set; }
    public int Age { get; set; }
}

You can turn an instance of this class into a persisted, live object using the Realm.Add() method:

realm.Write(() =>
{
    var myDog = new Dog();
    myDog.Name = "Rex";
    myDog.Age = 10;
    realm.Add(myDog);
});

After you have created the object, all changes you make to it will be persisted (and must be made within a write transaction). Any changes are made available to other threads that use the same Realm when the write transaction is committed.

Please note that writes block each other, and will block the thread they are made on if multiple writes are in progress. We recommend you offload your writes to a separate thread.

Due to Realm’s MVCC architecture, reads are not blocked while a write transaction is open. Unless you need to make simultaneous writes from many threads at once, you should favor larger write transactions that do more work over many fine-grained write transactions.

Updating Objects

You can update any object by setting its properties within a write transaction.

// Update an object with a transaction
using (var trans = realm.BeginWrite())
{
    author.Name = "Thomas Pynchon";
    trans.Commit();
}

For objects where you have specified a [PrimaryKey], you can pass in update: true in realm.Add to add the passed in object or update the existing one:

public class Person : RealmObject
{
    [PrimaryKey]
    public int Id { get; set; }

    // ... other property declarations
}

realm.Write(() =>
{
    realm.Add(new Person
    {
        Id = 1,
        Name = "Kristian"
    });
});

var kristianWithC = new Person
{
    Id = 1,
    Name = "Christian"
};

realm.Write(() => realm.Add(kristianWithC, update: true));

If you specify update: true and pass in a class that does not have a PrimaryKey, the method will not be able to find object to update, so it will behave as if update: false was passed. If your object has relationships with other RealmObjects, they will be added or updated when they have PrimaryKey specified, or simply added, when they don’t:

var kristian = new Person { Id = 1, Name = "Kristian" };
var rex = new Dog { Id = 1, Name = "Rex" };
kristian.Dogs.Add(rex);

realm.Write(() => realm.Add(kristian));

var christian = new Person { Id = 1, Name = "Christian" };
christian.Dogs.Add(new Dog { Id = 1, Name = "Bethoven" });

realm.Write(() => realm.Add(christian, update: true));

var newName = kristian.Name; // Christian
var newDogName = kristian.Dogs.First().Name; // Bethoven

Deleting Objects

Pass the object to be deleted to the Realm.Remove method within a write transaction.

var cheeseBook = realm.All<Book>().First(b => b.Name == "Cheese");

// Delete an object with a transaction
using (var trans = realm.BeginWrite())
{
    realm.Remove(cheeseBook);
    trans.Commit();
}

You can also delete all objects stored in a Realm. Note the Realm file will maintain its size on disk to efficiently reuse that space for future objects.

Queries

Queries implement standard LINQ syntax.

You get a basic, typed collection of all objects of a given type using the realm.All<T> method and then apply Where or other LINQ operators to get a filtered collection.

See the exact scope of LINQ implemented on our LINQ Support page.

Fluent or Extension Syntax

var oldDogs = realm.All<Dog>().Where(d => d.Age > 8);

Query Expression Syntax

var oldDogs = from d in realm.All<Dog>() where  d.Age > 8 select d;

Regardless of which syntax you use, the resulting collection conforms to the IQueryable interface so you can further iterate or process it:

foreach (var d in oldDogs)
{
    Debug.WriteLine(d.Name);
}

More Query Examples

If you’re not used to LINQ queries, here are some examples of basic queries to get you used to the syntax. Sticking with the Extension Syntax, you can see how to write your basic queries.

To extract a list of all users named John or Peter you would write:

var johnsAndPeters = realm.All<Person>().Where(p =>
    p.FirstName == "John" ||
    p.FirstName == "Peter");
var peopleList = johnsAndPeters.ToList();

The first statement gives you a new instance johnsAndPeters of a class that implements IQueryable and can be used to find the users with the name “John” or “Peter”. This is standard LINQ implementation - you get an object representing the query. The query doesn’t do anything until you make a further call that needs to iterate or count the results.

The ToList call, in this example, fires off the query which maps straight to the Realm core.

Objects are not copied - you get a list of references to the matching objects, and you work directly with the original objects that match your query.

Instead of retrieving them all into a list, you could also iterate through the query results, with the standard C# foreach statement:

foreach (var person in johnsAndPeters) // iterate query
{
    Debug.WriteLine(person.Name);
}

Logical Operators

The standard C# logical operators are used in LINQ expressions to compose the query.

That includes the ability to use parentheses to group nested expressions, with the precedence as you’d expect in an if statement:

var complexPeople = realm.All<Person>().Where(p =>
    p.LastName == "Doe" &&
    (p.FirstName == "Fred" || p.Score > 35));

Retrieving objects by type

To get all objects of a given type from a Realm, just use realm.All<T>(). It returns an IQueryable collection of all instances of the model class being queried - Person in the example above.

You can then choose to apply a LINQ query further to restrict the set. Remember, until you start iterating the collection, there’s no overhead.

var ap = realm.All<Person>();  // this is all items of a type
var scorers = ap.Where(p => p.Score > 35);  // restrict with first search clause
var scorerDoe = scorers.Where(p => p.LastName == "Doe");  // effectively an AND clause

Sorting

The standard LINQ clauses OrderBy, OrderByDescending, ThenBy, and ThenByDescending can be used to specify a multi-level sort that affects the order of objects supplied by the Queryable returned from Realm.All or subsequent LINQ clauses.

They work via the internal query engine to provide efficient sorted access without loading all objects in the results.

Warning: If you use the ToList clause to extract a list of objects and then use an OrderBy you are sorting in-memory using LINQ for Objects. Make sure you only use ToList at the end of your expression.

var highestScore = realm.All<Person>().OrderByDescending(p => p.Score).First();

var sortedPeople = realm.All<Person>()
    .OrderBy(p => p.LastName)
    .ThenBy(p => p.FirstName);

Chaining Queries

Since results are never copied, but are computed on request, you can very efficiently chain queries to gradually filter your data:

var teenagers = realm.All<Person>().Where(p => p.Age >= 13 && p.Age <= 20);
var firstJohn = teenagers.Where(p => p.FirstName == "John").First();

Limiting Results

Most other database technologies provide the ability to paginate results from queries (such as the LIMIT keyword in SQLite). This is often done out of necessity to avoid reading too much from disk, or pulling too many results into memory at once.

Since queries in Realm are lazy, performing this sort of paginating behavior isn’t necessary at all, as Realm will only load objects from the results of the query once they are explicitly accessed.

If for UI-related or other implementation reasons you require a specific subset of objects from a query, it’s as simple as taking the IQueryable object, and reading out only the objects you need.

While you may be tempted to use the LINQ Take, that is not yet supported. When added, it will enumerate and instantiate all the objects you request in one operation.

Realms

A Realm is an instance of a Realm Database container. Realms can be local or synchronized. A synchronized Realm uses the Realm Object Server to transparently synchronize its contents with other devices. While your application continues working with a synchronized Realm as if it’s a local file, the data in that Realm might be updated by any device with write access to that Realm. In practice, your application works with any kind of Realm the same way, although opening a synchronized Realm requires a User that’s been authenticated to the Object Server and that’s authorized to open that Realm.

For a more detailed discussion about Realms, read The Realm Data Model.

Opening Realms

Opening a Realm is simply performed by instantiating a new Realm object. We’ve seen this used already in examples:

// Get a Realm instance
var realm = Realm.GetInstance();

With no arguments, GetInstance instantiates the Default Realm. However, you can also specify a RealmConfiguration object.

Configuring a Realm

A RealmConfiguration allows you to control the database path in several ways. (Note that you can’t change the path once the configuration has been constructed.) You can:

1. Change the entire path by passing in a new absolute path.
2. Put your Realm files in a subdirectory of the standard location by passing in a relative path.
3. Change the Realm filename by just passing in a new filename.

var config = new RealmConfiguration("OtherPath.realm");
var otherRealm = Realm.GetInstance(config);

In the configuration you can also specify the schema version. For details about this, see the Migrations section. While developing, you can also set the property ShouldDeleteIfMigrationNeeded to true. This will cause Realm.GetInstance() to delete the existing database in case your schema mismatches that in the file being opened. This makes it easier to play around with models before releasing. However, do not release an app with this flag. You might want to set it within an #if DEBUG section to avoid accidents.

You can pass around an instance of a configuration, to open all your Realms with the same settings. This is the most common use for opening the same Realm in different threads.

You can also override the default configuration to change the defaults without having to pass around an object.

It is important to note that Realm instances are per-configuration, per-thread singletons. This means that Realm.GetInstance() will return the same instance every time it’s called on the same thread for the same configuration.

The Default Realm

Calling Realm.GetInstance() without passing any arguments returns the “default Realm” instance. The default Realm simply maps to a file called default.realm located in Environment.SpecialFolder.Personal.

In-memory Realms

With an InMemoryConfiguration configuration, you can create a Realm that runs entirely in memory without being persisted to disk:

var config = new InMemoryConfiguration("some-identifier");
var realm = Realm.GetInstance(config);

In-memory Realms might still use disk space if memory is running low, but all files created by an in-memory Realm will be deleted when the Realm is closed. Creating an in-memory Realm with the same identifier as a persisted Realm isn’t allowed - identifiers still have to be unique.

When all in-memory Realm instances with a particular identifier are disposed or garbage collected, that frees all that Realm’s data. To keep an in-memory Realm “alive” throughout your app’s execution, hold onto a reference to it.

Asynchronously Opening Realms

If opening a Realm might require a time-consuming operation, such as applying migrations, compaction or downloading the remote contents of a synchronized Realm, you should use the Realm.GetInstanceAsync API to perform all work needed to get the Realm to a usable state on a background thread before completing the returned Task<Realm>. You should also use Realm.GetInstanceAsync with Realms that the user has read permissions only.

For example:

var config = new RealmConfiguration
{
    SchemaVersion = 1,
    MigrationBlock = (migration, oldSchemaVersion) =>
    {
        // potentially lengthy data migration
    }
};

try
{
    var realm = await Realm.GetInstanceAsync(config);
    // Realm successfully opened, with migration applied on background thread
}
catch (Exception ex)
{
    // Handle exception that occurred while opening the Realm
}

In addition, synchronized Realms wait for all remote content available at the time the operation began to be downloaded and available locally. For example:

var serverURL = new Uri("realm://my.realm-server.com:9080/~/default");
var config = new SyncConfiguration(user, serverURL));
try
{
    var realm = await Realm.GetInstanceAsync(config);
    // Realm successfully opened, with all remote data available
}
catch (Exception ex)
{
    // Handle error that occurred while opening or downloading the contents of the Realm
}

Closing Realm Instances

The Realm class implements IDisposable in order to take care of native memory deallocation and file descriptors so instances will be closed automatically when variables go out of scope.

Finding a Realm File

If you need help finding your app’s Realm file, check this StackOverflow answer for detailed instructions.

Auxiliary Realm Files

Alongside the standard .realm files, Realm also generates and maintains additional files for its own internal operations.

• .realm.lock - A lock file for resource locks.
• .realm.note - A named pipe for notifications.

These files don’t have any effect on .realm database files, and won’t cause any erroneous behavior if their parent database file is deleted or replaced.

When reporting Realm issues, please be sure to include these auxiliary files along with your main .realm file as they contain useful information for debugging purposes.

Bundling a Realm with an App

If you want to bundle a Realm with your app, see this StackOverflow answer which explains how to include files in Xamarin projects as resources and copy them for use.

Class Subsets

In some scenarios you may wish to limit which classes can be stored in a specific Realm.

You can do this by setting the ObjectClasses property of your RealmConfiguration:

class LoneClass : RealmObject
{
    public string Name { get; set;}
}

var config = new RealmConfiguration("RealmWithOneClass.realm");
config.ObjectClasses = new[] { typeof(LoneClass) };

// or specifying two classes in the Realm
config.ObjectClasses = new[] { typeof(Dog), typeof(Cat) };

Compacting Realms

Over the course of using your application, the memory used by Realm might become fragmented and take up more space than necessary. To rearrange the internal storage and potentially reduce the filesize, you can compact the Realm file by specifying a RealmConfiguration.ShouldCompactOnLaunch callback when opening a Realm file:

var config = new RealmConfiguration
{
    ShouldCompactOnLaunch = (totalBytes, usedBytes) =>
    {
        // totalBytes refers to the size of the file on disk in bytes (data + free space)
        // usedBytes refers to the number of bytes used by data in the file

        // Compact if the file is over 100MB in size and less than 50% 'used'
        var oneHundredMB = 100 * 1024 * 1024;
        return totalBytes > oneHundredMB && (double)usedbytes / totalBytes < 0.5;
    }
};

try
{
    var realm = Realm.GetInstance(config);
}
catch (Exception e)
{
    // handle error compacting or opening Realm
}

The Realm will be compacted if you return true from the ShouldCompactOnLaunch delegate and the Realm file is not currently in use.

Alternatively, you can compact the file without obtaining a Realm instance by calling Realm.Compact(config):

var config = new RealmConfiguration("my.realm");
Realm.Compact(config);

Notes on compacting

• There should not be any open realm instances that use the file.
• The file system should have free space for at least a copy of the Realm file.
• If any operation fails, the Realm file is left untouched.
• The method will return true if the operation is successful and false if there are open Realm instances accessing the same file.
• At the moment, we don’t provide API for estimating the potential size gain by compacting a Realm. The recommended approach is to monitor your database’s size between launches and compact it if it crosses some threshold.

Deleting Realm Files

In some cases, such as clearing caches, or resetting your entire dataset, it may be appropriate to completely delete a Realm file from disk.

Unlike most files, Realm files are memory-mapped and Realm instances expect the files to be available for the duration of the instance’s lifetime.

To avoid your application code having to be aware of all files in a Realm, we provide a convenience method Realm.DeleteRealm(RealmConfiguration).

var config = new RealmConfiguration("FileWeThrowAway.realm");
Realm.DeleteRealm(config);
var freshRealm = Realm.GetInstance(config);

Threading

Within individual threads, you can just treat everything as regular objects without worrying about concurrency or multithreading. There is no need for any locks or resource coordination to access them (even if they are simultaneously being modified on other threads) and it is only modifying operations that have to be wrapped in transactions.

Realm makes concurrent usage easy by ensuring that each thread always has a consistent view of the Realm. You can have any number of threads working on the same Realms in parallel, and since they all have their own snapshots, they will never cause each other to see inconsistent state.

The only thing you have to be aware of is that you cannot have multiple threads sharing the same instances of Realm objects. If multiple threads need to access the same objects, they will each need to get their own instances (otherwise changes happening on one thread could cause other threads to see incomplete or inconsistent data).

Seeing Changes From Other Threads

On the main UI thread (or any thread with a runloop/looper), objects will automatically update with changes from other threads between each iteration of the runloop. At any other time you will be working on the snapshot, so individual methods always see a consistent view and never have to worry about what happens on other threads.

When you initially open a Realm on a thread, its state will be based off the most recent successful write commit, and it will remain on that version until refreshed. Realms are automatically refreshed at the start of every runloop iteration. If a thread has no runloop (which is generally the case in a background thread), then Realm.Refresh() must be called manually in order to advance the transaction to the most recent state.

Realms are also refreshed when write transactions are committed with Transaction.Commit().

Failing to refresh Realms on a regular basis could lead to some transaction versions becoming “pinned”, preventing Realm from reusing the disk space used by that version, leading to larger file sizes. Refer to our Current Limitations for more details on this effect.

Passing Instances Across Threads

Persisted instances of Realm, RealmObject, IQueryable returned from Realm.All, or IList properties of RealmObjects can only be used on the thread on which they were created, otherwise an exception is thrown. This is one way Realm enforces transaction version isolation. Otherwise, it would be impossible to determine what should be done when an object is passed between threads at different transaction versions without a potentially extensive relationship graph.

Realm exposes a mechanism to safely pass thread-confined instances in three steps:

1. Obtain a ThreadSafeReference by calling one of the ThreadSafeReference.Create overloads with the thread-confined object.
2. Pass that ThreadSafeReference to a destination thread or queue.
3. Resolve this reference on the target Realm by calling one of the Realm.ResolveReference overloads. Use the returned object as you normally would.

For example:

var person = new Person { Name = "Jane" };
realm.Write(() => realm.Add(person));

var personReference = ThreadSafeReference.Create(person);

Task.Run(() =>
{
    var otherRealm = Realm.GetInstance(realm.Config);
    var otherPerson = otherRealm.ResolveReference(personReference);
    if (otherPerson == null)
    {
        return; // person was deleted
    }

    realm.Write(() =>
    {
        otherPerson.Name = "Jane Doe";
    });
});

A ThreadSafeReference object must be resolved at most once. Failing to resolve it will result in the source version of the Realm being pinned until the reference is deallocated. For this reason, ThreadSafeReference should be short-lived.

ThreadSafeReference wrappers are provided for RealmObject, IList<RealmObject>, and IQueryable<RealmObject. They should only be used for persisted instances only, as the standalone versions of those are intrinsically not thread confined.

Using a Realm Across Threads

To access the same Realm file from different threads, you must initialize a new Realm to get a different instance for every thread of your app. As long as you specify the same configuration, all Realm instances will map to the same file on disk.

Sharing Realm instances across threads is not supported. Realm instances accessing the same realm file must also all use the same RealmConfiguration.

Asynchronous Writes

The Realm.WriteAsync() method is a special form of Write which makes it easy to offload the UI thread by performing writes on a background thread.

Caution: WriteAsync opens a temporary Realm instance, which is passed to your lambda as a parameter, seen in the example below. Be careful to only use the passed-in instance in the lambda and not the original thread’s realm. Due to the way lambdas capture the calling context, failing to change this code will not get a compiler error but instead a runtime exception will be thrown.

await realm.WriteAsync(tempRealm =>
{
    var pongo = tempRealm.All<Dog>().Single(d => d.Name == "Pongo");
    var missis = tempRealm.All<Dog>().Single(d => d.Name == "Missis");
    for (var i = 0; i < 15; i++)
    {
        tempRealm.Add(new Dog
        {
            Breed = "Dalmatian",
            Mum = missis,
            Dad = pongo
        });
    }
});

When its threaded action is complete, WriteAsync also calls Realm.Refresh() to advance the read state of the original (usually UI) thread. That thread will immediately receive notifications of any changes in the background threads.

There is no point using WriteAsync from code which you know is already running on a worker thread as it will just forward a call to Write without creating an extra thread. However, it is quite safe to use from any thread and adds no meaningful overhead. It is important to consider that on a background thread, WriteAsync will operate on the current Realm instance, rather than create a new instance.

In general, since realm writes are very fast, we recommend using Write for interface-driven changes (e.g. the user types some string, or checks a checkbox) where only a few values change at a time. WriteAsync is useful in scenarios where there are hundreds or thousands of changes (e.g. fetching objects from the network or batch updating multiple objects) and performing them synchronously might lead to interface jitters.

Notifications

Realm Notifications

If you have a background thread adding data to a Realm, your UI or other threads can get notified of changes in a Realm by adding a listener, which is executed when the Realm is changed (also by another thread or process):

realm.RealmChanged += (s, e) =>
{
    // Update UI
}

Keep in mind that the current implementation of RealmChanged does not provide detailed information for the changes, so if you need that, check the Object Notifications or Collection Notifications sections.

Object Notifications

RealmObject implements INotifyPropertyChanged so if you want to listen for changes, you can subscribe to the PropertyChangedEvent event.

public class Account : RealmObject
{
    public long Balance { get; set; }
}

If you subscribe to the PropertyChangedEvent event on your class, your handler will be triggered when the Balance property is changed.

var account = new Account();
realm.Write(() => realm.Add(account));
account.PropertyChanged += (sender, e) =>
{
    Debug.WriteLine($"New value set for {e.PropertyName}");
}

realm.Write(() => account.Balance = 10); // => "New value set for Balance"

Note that it doesn’t matter whether you subscribe before or after adding the object to the Realm. The event will be raised as expected in either case.

This is handy in and of itself, but furthermore, it enables databinding with Xamarin.Forms. For more info, see From Data Bindings to MVVM in the Xamarin Docs.

Collection Notifications

IQueryable objects returned from Realm.All<T>() or subsequent LINQ clauses are live queries, meaning that they are always kept up to date. Any time you iterate over the collection, you will get a result that is up to date with the latest changes. Similarly IList properties on RealmObjects represent live to-many relationships, meaning that each time you iterate over them, you will get the most up-to-date collection of related objects.

The runtime objects backing both of these collections also implement IRealmCollection<T> which means that it exposes two mechanisms for subscribing for change notifications. We’ve provided a convenience extension method: AsRealmCollection that will cast an IList<T> or IQueryable<T> to IRealmCollection<T>.

If you prefer to use the standard .NET INotifyCollectionChanged interface that works nicely with MVVM and data-binding, you can pass the IRealmCollection<T> directly to your views.

Alternatively, if you wish more detailed change information, that is useful for manipulating a UITableView or ListView directly (e.g. in a Xamarin Native UI project), you can use the SubscribeForNotifications extension method. You give this method a delegate that will be called with a change set, telling you what has been added, removed or modified.

var token = realm.All<Person>().SubscribeForNotifications ((sender, changes, error) =>
{
    // Access changes.InsertedIndices, changes.DeletedIndices, and changes.ModifiedIndices
});

// Later, when you no longer wish to receive notifications
token.Dispose();

Migrations

When working with any database, it is likely your data model will change over time. Since data models in Realm are defined as standard C# classes, making model changes is as easy as changing any other class. For example, suppose we have the following Person model:

public class Person : RealmObject
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public int Age { get; set; }
}

We want to update the data model to require a FullName property, rather than separate first and last names. To do this, we simply change the object interface to the following:

public class Person : RealmObject
{
    public string FullName { get; set; }
    public int Age { get; set; }
}

At this point if you had saved any data with the previous model version, there will be a mismatch between what Realm sees defined in code and the data Realm sees on disk. When this occurs, an exception will be thrown when you try to open the existing file unless you run a migration.

Performing a Migration

The minimal solution you can perform is to bump the schema version. When unspecified, Realms will have a schema version set to 0. As soon as you make a schema change, you must increase the schema version in your configuration. This way, we avoid accidental schema changes that potentially destroy data.

var config = new RealmConfiguration() { SchemaVersion = 1 };

var realm = Realm.GetInstance(config);

Now, if you do nothing more than this and run it with a database file that was created with the old schema, all the FirstName and LastName entries will be deleted and every Person will have an empty FullName property. This probably isn’t what you wanted here. So you must tell Realm how to handle the migration.

We do this by specifying a MigrationCallback function. This function will receive a Migration object, which will contain two Realm properties: OldRealm and NewRealm. You can now copy and adapt data from the old schema to the new.

Note that if you simply rename a class or a property, Realm will not be able to detect that and you will have to copy data in the migration as well.

This callback function will be called exactly once when a Realm with a lower version is opened. You should migrate all updated classes during that call.

As our Person model no longer contains the FirstName and LastName properties, we cannot access those through the typed API. However, we can utilize the dynamic API and achieve the same thing.

var config = new RealmConfiguration
{
    SchemaVersion = 1,
    MigrationCallback = (migration, oldSchemaVersion) =>
    {
        var newPeople = migration.NewRealm.All<Person>();

        // Use the dynamic api for oldPeople so we can access
        // .FirstName and .LastName even though they no longer
        // exist in the class definition.
        var oldPeople = migration.OldRealm.All("Person");

        for (var i = 0; i < newPeople.Count(); i++)
        {
            var oldPerson = oldPeople.ElementAt(i);
            var newPerson = newPeople.ElementAt(i);

            newPerson.FullName = oldPerson.FirstName + " " + oldPerson.LastName;
        }
    }
};

var realm = Realm.GetInstance(config);

As your app grows older and you have multiple changes to the model in different versions, you make a sequence of migrations by inspecting the oldSchemaVersion parameter to your callback. Let’s say you change the Person model further by changing the Age field to a Birthday field:

public class Person : RealmObject
{
    public string FullName { get; set; }
    public int Age { get; set; }
    public DateTimeOFfset Birthday { get; set; }
}

This is then version 2 of the schema, and your migration setup could now look something like the following:

var config = new RealmConfiguration
{
    SchemaVersion = 2,
    MigrationCallback = (migration, oldSchemaVersion) =>
    {
        var newPeople = migration.NewRealm.All<Person>();
        var oldPeople = migration.OldRealm.All("Person");

        for (var i = 0; i < newPeople.Count(); i++)
        {
            var oldPerson = oldPeople.ElementAt(i);
            var newPerson = newPeople.ElementAt(i);

            // Migrate Person from version 0 to 1: replace FirstName and LastName with FullName
            if (oldSchemaVersion < 1)
            {
                newPerson.FullName = oldPerson.FirstName + " " + oldPerson.LastName;
            }

            // Migrate Person from version 1 to 2: replace Age with Birthday
            if (oldSchemaVersion < 2)
            {
                newPerson.Birthday = DateTimeOffset.Now.AddYears(-(int)oldPerson.Age);
            }
        }
    }
};

var realm = Realm.GetInstance(config);

Encryption

Realm supports encrypting the database file on disk with AES-256+SHA2 by supplying a 64-byte encryption key when creating a Realm.

var config = new RealmConfiguration("Mine.realm");
config.EncryptionKey = new byte[64] // key MUST be exactly this size
{
  0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08,
  0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17, 0x18,
  0x21, 0x22, 0x23, 0x24, 0x25, 0x26, 0x27, 0x28,
  0x31, 0x32, 0x33, 0x34, 0x35, 0x36, 0x37, 0x38,
  0x41, 0x42, 0x43, 0x44, 0x45, 0x46, 0x47, 0x48,
  0x51, 0x52, 0x53, 0x54, 0x55, 0x56, 0x57, 0x58,
  0x61, 0x62, 0x63, 0x64, 0x65, 0x66, 0x67, 0x68,
  0x71, 0x72, 0x73, 0x74, 0x75, 0x76, 0x77, 0x78
};

var realm = Realm.GetInstance(config);  // will create/open encrypted realm "Mine.realm"

This makes it so that all of the data stored on disk is transparently encrypted and decrypted with AES-256 as needed, and verified with a SHA-2 HMAC. The same encryption key must be supplied every time you obtain a Realm instance.

You should use a key that is unique to your app, not the one in the example above. Furthermore, if you need unique keys for each user, look into the Xamarin.Auth API.

Note that if you specify the wrong key or fail to specify a key for an encrypted Realm, you get a RealmFileAccessErrorException when you call GetInstance.

There is a small performance hit (typically less than 10% slower) when using encrypted Realms.

Sync

The Realm Platform (RP) extends the Realm Database across the network, enabling automatic synchronization of data across devices. In order to do this, a new set of types and classes are provided that support these synchronized Realms; these new classes are additive to the existing Realm Database and are covered here.

Enabling Realm Platform

No explicit steps are required to enable Realm Platform. It is installed by default in the standard Realm NuGet.

Users

The central object in the Realm Object Server is the concept of a Realm User—a User—that is associated with a synchronized Realm. The User can be authenticated to a shared Realm via a username/password scheme or through a number of 3rd party authentication methods.

Creating and logging in a user requires two objects:

• A Uri of a Realm Authentication Server to connect to.
• Credentials for an authentication mechanism that describes the user as appropriate for that mechanism (i.e., username/password, access key, etc).

Authentication

Authentication is used to establish the identity of users and log them in. Refer to our authentication documentation for a list of authentication providers supported by the Realm Platform.

The credential information for a given user can be created in one of several ways:

• Providing a valid username/password combination
• Providing a token obtained from a supported third-party authentication service
• Providing a token and a custom authentication provider (see Custom Authentication)

The username and password authentication is entirely managed by the Realm Object Server, giving you full control over your application’s user management. For other authentication methods, your application is responsible for logging into the external service and obtaining the authentication token.

Here are some examples of setting credentials with various providers.

JSON Web Token

The JWT authentication provider allows you to integrate with an existing authentication system. It requires that your authentication server generates a signed JWT, which the client sends to the Realm Object Server for verification.

var token = "..."; // a string representation of a JWT, obtained from your auth server
var credentials = Credentials.JWT(token);

Username/Password

var credentials = Credentials.UsernamePassword(username, password, createUser: false);

The third parameter of UsernamePassword() is the createUser flag which should only be true the first time, as it indicates that the user should be created. Once the user is created, the parameter must be set to false.

Alternatively, you can require that all users are created in advance on the server using an admin Dashboard, and always pass false for the createUser parameter.

To change a user’s password, you can use User.ChangePasswordAsync:

var currentUser = User.Current;
await currentUser.ChangePasswordAsync("new-secure-password");

// The user's password has been changed, they'll no longer be able to use their old password.

Admin users may change other users’ passwords (e.g. as part of a server-side app that automates password retrieval) by passing in a user’s Id:

var adminUser = await User.LoginAsync(...);
await adminUser.ChangePasswordAsync("some-user-id", "new-secure-password");

// The password of the user with Id some-user-id has been changed to new-secure-password.

Nickname

The Nickname provider allows you to authenticate users just by their nickname without requiring passwords or other identifying information. This is useful when prototyping collaborative features for your app without worrying about the actual login flow until later in the development lifecycle.

var credentials = Credentials.Nickname("some-nickname", isAdmin: false);

Anonymous

Sometimes it’s useful to create a synchronized Realm for a user without prompting them for credentials - e.g. in an e-commerce application where any disruption leads to user churn. For such cases, the Realm Object Server exposes an anonymous provider that requires no payload and creates a new user for every request (which means that you must use User.Current to avoid resetting the state on every launch).

var credentials = Credentials.Anonymous();

Google

var token = "..."; // a string representation of a token obtained by Google Login API
var credentials = Credentials.Google(token);

Facebook

var token = "..."; // a string representation of a token obtained by Facebook Login API
var credentials = Credentials.Facebook(token);

Azure Active Directory

var token = "..."; // a string representation of a token obtained by logging in with Azure Active Directory
var credentials = Credentials.AzureAD(token);

Custom Auth

var token = "..."; // a string representation of a token obtained from your custom provider
var credentials = Credentials.Custom("myAuth", token, null);

Additional information can be passed to a custom auth provider in the form of a dictionary provided as the third parameter; see the API Reference for details.

Logging in the User

Now, with all the required parameters the user can be logged into the Realm Object Server:

var authURL = new Uri("http://my.realm-auth-server.com:9080");
var user = await User.LoginAsync(credentials, authURL);

Logging Out

Logging out of a synced Realm is simple:

user.LogOut();

When a user is logged out, the synchronization will stop. A logged out user can no longer open a Realm using a SyncConfiguration.

Configuring user persistence

By default, Realm will persist logged in users across application launches. You can modify that behavior by calling User.ConfigurePersistence. The available modes are

• Disabled: users will not be persisted by Realm. This means that you either need to store user credentials manually, or ask the user to login every time they launch the application.
• NotEncrypted: User credentials will be stored unencrypted. This option is not recommended for production applications as it provides a vector of attack for stealing user identities.
• Encrypted: User credentials are stored encrypted. If you choose to use that option, you must provide a valid encryptionKey.

By default, Realm uses Encrypted mode on iOS and stores the encryptionKey in the iOS Keychain. On Android, NotEncrypted is used because the AndroidKeyStore API is only supported on API level 18 and up. It is recommended that you opt in for Encrypted mode on Android and provide encryptionKey that is unique to your application or target at least API level 18 and store a unique per-user encryptionKey in the KeyStore.

Working with Users

For standalone Realms, RealmConfiguration is used to configure the options for a Realm. Synchronized Realms on the other hand, are configured using an extended configuration class called SyncConfiguration.

The configuration ties together an authenticated user and a sync server URL. The sync server URL may contain the tilde character (“~”) which will be transparently expanded to represent the user’s unique identifier. This scheme easily allows you to write your app to cater to its individual users. The location on disk for shared Realms is managed by the framework, but can be overridden if desired.

var serverURL = new Uri("realm://my.realm-server.com:9080/~/default");
var configuration = new SyncConfiguration(user, serverURL);

If you have not disabled user persistence, User.Current can be used to obtain the currently logged in user. If no users have logged in or all have logged out, it will return null. If there are more than one logged in users, a RealmException will be thrown.

var user = User.Current;

If there are likely to be multiple users logged in, you can get a collection of them by calling User.AllLoggedIn. This will be empty if no users have logged in.

var users = User.AllLoggedIn;

foreach (var user in users)
{
    // do something with the user
}

Opening a Synchronized Realm

Once a SyncConfiguration is constructed, synchronized Realm instances are created like normal Realms:

var realm = Realm.GetInstance(configuration);

Sync Sessions

A synced Realm’s connection to the Realm Object Server is represented by a Session object. Session objects can be retrieved by calling realm.GetSession().

The state of the underlying session can be retrieved using the State property. This can be used to check whether the session is active, not connected to the server, or in an error state.

Progress Notifications

Session objects allow your app to monitor the status of a session’s uploads to and downloads from the Realm Object Server by registering a subscriber on the IObservable instance, obtained by calling session.GetProgressObservable(direction, mode).

The subscription callback will be invoked periodically by the synchronization subsystem. As many subscribers as needed can be registered on a session object simultaneously. Subscribers can either be configured to report upload progress or download progress. Each time a subscriber is called, it will be passed a SyncProgress instance that will contain information about the current number of bytes already transferred, as well as the total number of transferable bytes (defined as the number of bytes already transferred plus the number of bytes pending transfer).

Each time a subscriber is registered, an IDisposable token will be returned. You must keep a reference to that token for as long as progress notifications are desired. To stop receiving notifications, call Dispose on the token.

There are two modes for the progress subscriptions:

• ReportIndefinitely - the subscription will stay active until Dispose is explicitly called and will always report the most up-to-date number of transferrable bytes. This type of callback could be used to control a network indicator UI that, for example, changes color or appears only when uploads or downloads are actively taking place.

var token = session.GetProgressObservable(ProgressDirection.Download, ProgressMode.ReportIndefinitely)
                   .Subscribe(progress =>
                   {
                       if (progress.TransferredBytes < progress.TransferableBytes)
                       {
                           // Show progress indicator
                       }
                       else
                       {
                           // Hide the progress indicator
                       }
                   });

• ForCurrentlyOutstandingWork - the subscription will capture the number of transferable bytes at the moment it is registered and always report progress relative to that value. Once the number of transferred bytes reaches or exceeds that initial value, the subscriber will automatically unregister itself. This type of subscription could, for example, be used to control a progress bar that tracks the progress of an initial download of a synced Realm when a user signs in, letting them know how long it is before their local copy is up-to-date.

var token = session.GetProgressObservable(ProgressDirection.Download, ProgressMode.ForCurrentlyOutstandingWork)
                   .Subscribe(progress =>
                   {
                       var progressPercentage = progress.TransferredBytes / progress.TransferableBytes;
                       progressBar.SetValue(progressPercentage);

                       if (progressPercentage == 1)
                       {
                           progressBar.Hide();
                       }
                   });

Note that those examples use the ObservableExtensions.Subscribe extension method to simplify subscribing. We recommend using the Reactive Extensions class library as it greatly simplifies working with observable sequences. For example, here’s a more advanced scenario, where both upload and download progress is tracked, throttled, and finally, dispatched on the main thread:

var uploadProgress = session.GetProgressObservable(ProgressDirection.Upload, ProgressMode.ReportIndefinitely);
var downloadProgress = session.GetProgressObservable(ProgressDirection.Download, ProgressMode.ReportIndefinitely);

var token = uploadProgress.CombineLatest(downloadProgress, (upload, download) =>
                          {
                              return new
                              {
                                  TotalTransferred = upload.TransferredBytes + download.TransferredBytes,
                                  TotalTransferable = upload.TransferableBytes + download.TransferableBytes
                              };
                          })
                          .Throttle(TimeSpan.FromSeconds(0.1))
                          .ObserveOn(SynchronizationContext.Current)
                          .Subscribe(progress =>
                          {
                              if (progress.TotalTransferred < progress.TotalTransferable)
                              {
                                  // Show spinner
                              }
                              else
                              {
                                  // Hide spinner
                              }
                          });

Access Control

The Realm Platform provides flexible access control mechanisms to restrict which users are allowed to sync against which Realm files. This can be used, for example, to create collaborative apps where multiple users write to the same Realm. It can also be used to share data in a publisher/subscriber scenario where a single writing user shares data with many users with read permissions.

There are three axes that control the access level (permissions) of a given Realm:

• Read indicates that the user is allowed to read from the Realm.
• Write indicates that the user is allowed to write to the Realm.
• Admin indicates that the user is allowed to change the permissions for the Realm.

Unless permissions are explicitly modified, only the owner (creator) of a Realm can access it. The only exception is admin users: They are always granted all permissions to all Realms on the server.

Please refer to the general Realm Object Server documentation on Access Control to learn more about the concept.

Retrieving Permissions

To get a collection of all the Permissions a user has been granted, use the User.GetGrantedPermissionsAsync method:

var permissions = await user.GetGrantedPermissionsAsync(Recipient.CurrentUser, millisecondTimeout: 2000);

// Permissions is a regular query
var writePermissions = permissions.Where(p => p.MayWrite);

// Queries are live and emit notifications
writePermissions.SubscribeForNotifications((sender, changes, error) =>
{
    // handle permission changes
});

To get permissions granted by a user, pass in Recipient.OtherUser. The millisecondTimeout argument controls the maximum time to wait for response from the server. When the timeout elapses, the last known state is returned, so even if the client is currently offline, some data may still be shown.

Modifying Permissions

Modifying the access control settings for a Realm file is performed by either applying permissions directly or offering them.

Granting Permissions

Permission changes can be applied (i.e. granted or revoked) via the User.ApplyPermissionsAsync method in order to directly increase or decrease other users’ access to a Realm.

var condition = PermissionCondition.UserId("some-user-id");
var realmUrl = "realm://my-server.com/~/myRealm";
await user.ApplyPermissionsAsync(condition, realmUrl, AccessLevel.Read);

There are two factory methods for PermissionCondition:

• UserId - use this to apply permissions based on a user’s Identity(the internal Id that Realm generates).
• Email - use this to change permissions by specifying a user’s email (username) in the Username/Password provider.

The last argument controls the AccessLevel that the user will be granted. Higher access implies all lower tiers, e.g. Write implies Read, Admin implies Read and Write. If AccessLevel.None is passed, this will revoke the user’s permissions for this Realm.

Offer/Response

A user can offer permissions to their Realm by sharing the opaque token returned by OfferPermissionsAsync:

var realmUrl = "realm://my-server.com/~/myRealm";
var expiration = DateTimeOffset.UtcNow.AddDays(7);
var token = await userA.OfferPermissionsAsync(realmUrl, AccessLevel.Write, expiresAt: expiration);

The optional expiresAt argument controls when the offer expires - i.e. using the token after that date will no longer grant permissions to that Realm. Users who have already consumed the token to obtain permissions will not lose their access after that date. If you want to revoke it, use ApplyPermissionsAsync.

Once a user has received a token, e.g. by sharing it via messaging app, or scanning a QR code, they can consume it to obtain the permissions offered:

var token = "...";
var realmUrl = await userB.AcceptPermissionOfferAsync(token);

// Use the realmUrl to open the Realm
var config = new SyncConfiguration(userB, new Uri(realmUrl));
var realm = await Realm.GetInstanceAsync(config);

Retrieving existing offers/changes

Sometimes, it may make sense to retrieve existing management objects, e.g. to invalidate an offer or to attach a change listener after an app has been restarted.

There are three object types created when using the above API:

• To get objects created by OfferPermissionsAsync, use the GetPermissionOffers method.
• To get objects created by AcceptPermissionOfferAsync, use the GetPermissionOfferResponses method.
• To get objects created by ApplyPermissionsAsync, use the GetPermissionChanges method.

All of these take a params argument of type ManagementObjectStatus:

• NotProcessed - get objects that haven’t been processed yet (likely because the client is offline).
• Success - get objects that have been processed successfully (permissions have been applied).
• Error - get objects that have been problematic.

All of these methods return an IQueryable that can be further filtered or observed (see Collection Notifications).

If you want to invalidate a PermissionOffer and prevent new users from consuming the token, use the InvalidateOfferAsync method:

// Get all offers that grant write permissions and have no expiration date
var offers = user.GetPermissionOffers(ManagementObjectStatus.Success)
                 .Where(s => s.MayWrite && s.ExpiresAt == null);

foreach (var offer in offers)
{
    await user.InvalidateOfferAsync(offer);
}

Error reporting

Certain sync-related APIs perform asynchronous operations that may fail and those will raise exceptions that can be observed in a try-catch block.

It is strongly recommended to also subscribe to the Session.Error event. Errors involving the global synchronization subsystem or specific sessions (which represent Realms opened for synchronization with the server) will be reported to this handler. When errors occur, the error handler will be invoked with ErrorEventArgs containing the Exception, as well as a Session object representing the session the error occurred on.

Session.Error += (session, errorArgs) =>
{
    // handle error
};

Errors

Realm Platform errors are represented by SessionExceptions. In addition to the standard exception properties, you have access to an ErrorCode that contains information about the type of the error and allows you to have strongly typed handling logic, e.g.:

Session.Error += (session, errorArgs) =>
{
    var sessionException = (SessionException)errorArgs.Exception;
    switch (sessionException.ErrorCode)
    {
        case ErrorCode.AccessTokenExpired:
        case ErrorCode.BadUserAuthentication:
            // Ask user for credentials
            break;
        case ErrorCode.PermissionDenied:
            // Tell the user they don't have permissions to work with that Realm
            break;
        case ErrorCode.Unknown:
            // Likely the app version is too old, prompt for update
            break;
        // ...
    }
};

Client Reset

If a Realm Object Server crashes and must be restored from a backup, there is a possibility that an app might need to carry out a client reset on a given synced Realm. This will happen if the local version of the Realm in question is greater than the version of that same Realm on the server (for example, if the application made changes after the Realm Object Server was backed up, but those changes weren’t synced back to the server before it crashed and had to be restored).

The client reset procedure is as follows: a backup copy of the local Realm file is made, and then the Realm files are deleted. The next time the app connects to the Realm Object Server and opens that Realm, a fresh copy will be downloaded. Changes that were made after the Realm Object Server was backed up but weren’t synced back to the server will be preserved in the backup copy of the Realm, but will not be present when the Realm is re-downloaded.

The need for a client reset is indicated by an error sent to Session.Error subscribers. You can check the error type by examining the result of sessionException.ErrorCode.IsClientResetError or safe-casting the exception to ClientResetException. This type contains an additional property - BackupFilePath - that contains the location of the backup copy of the Realm file once the client reset process is carried out, as well as a method - InitiateClientReset which can be called to initiate the client reset process.

If the method is called to manually initiate the client reset process, all instances of the Realm in question must first be closed by calling Dispose() before the method is invoked. However, doing so allows the Realm to be immediately re-opened after the client reset process is complete, allowing syncing to resume.

If InitiateClientReset is not called, the client reset process will automatically take place after the next time the app is launched, upon first obtaining a Realm instance. It is the app’s responsibility to persist the location of the backup copy if needed, so that the backup copy can be found later.

A Realm which needs to be reset can still be written to and read from, but no subsequent changes will be synced to the server until the client reset is complete and the Realm is re-downloaded. It is extremely important that your application listen for client reset errors and, at the very least, make provisions to save user data created or modified after a client reset is triggered so it can later be written back to the re-downloaded copy of the Realm.

The following example shows how the client reset APIs might be used to carry out a client reset:

void CloseRealmSafely()
{
    // Safely dispose the realm instances, possibly notify the user
}

void SaveBackupRealmPath(string path)
{
    // Persist the location of the backup realm
}

void SetupErrorHandling()
{
    Session.Error += (session, errorArgs)
    {
        var sessionException = (SessionException)errorArgs.Exception;
        if (sessionException.ErrorCode.IsClientResetError())
        {
            var clientResetException = (ClientResetException)errorArgs.Exception;
            CloseRealmSafely();
            SaveBackupRealmPath(clientResetException.BackupFilePath);
            clientResetException.InitiateClientReset();
        }

        // Handle other errors
    }
}

For more information about how the Realm Object Server handles client reset, please refer to our server documentation.

Migrations

Automatic migrations are supported for synced Realms. At present only additive changes are supported, such as adding a class or field to an existing class. Any non-additive changes will lead to an exception being thrown.

Migrations will automatically be triggered if needed. There is no need to set either a custom migration callback or a schema version number.

Conflict Resolution

Conflict resolution is documented in the Realm Object Server documentation.

Query-based synchronization

Query-based synchronization is a feature that allows a synchronized Realm to be opened in a such a way that it does not download all objects stored within the remote Realm on the server. Instead, a partially synced Realm allows you to specify what subset of objects you want synchronized to the local copy using queries.

To open a Realm in Query-based synchronization mode, simply set the IsPartial property on the SyncConfiguration before using it to open the Realm.

A partially synced Realm will contain no objects upon initially being created and opened. To specify objects for the Realm to fetch, call the Realm.SubscribeToObjects method and pass in the type of the objects you wish to fetch as a generic argument and a string containing a valid NSPredicate query. Support for LINQ queries will be added with a later beta.

The method will return an awaitable task, that upon completion will return a queryable collection containing all items that match the query. Similarly to other queryable collections returned by Realm, you can apply futher filtering or observe it for changes.

You can subscribe to any number of queries and the locally synced objects will be the union of all objects matching at least one query. You may modify objects within the results collection, and these changes will be synced up to the Realm Object Server.

Here’s some example code:

var children = await realm.SubscribeToObjects<Person>("Age < 18");

// We can further filter the collection with LINQ
var students = children.Where(c => c.EnrolledInSchool);

// We can subscribe for notifications as usual
students.SubscribeForNotifications((sender, changes, error) =>
{
    // Collection has changed either locally or remotely
});

// We can modify the local collection
realm.Write(() =>
{
    foreach (var student in students)
    {
        // Relationships are synchronized as well
        student.Reminders.Add(new Reminder
        {
            Date = SchoolYearStart,
            Title = "School year starts today! Good luck!"
        });
    }
});

Migrating From Realm Object Server 1.* to 2.*

If you were using a prior version of Realm alongside a version of Realm Object Server prior to 2.0, and you upgrade your application to use Realm Object Server 2.0 or later, you must write code in your application to handle migrating your local copies of synchronized Realms. The Realm Object Server 2.0 file format is incompatible with earlier versions of the Realm Object Server, and all Realms that were synced from an older version of the Realm Object Server must be re-downloaded.

When a synced Realm requiring migration is opened, the Realm file will be copied to a backup location and then deleted so that it can be re-downloaded from the Realm Object Server. After that an Incompatible​Synced​File​Exception will then be thrown.

If you wish to migrate any data from the backup location, you can use IncompatibleSyncedFileException.GetBackupRealmConfig(byte[]) to obtain a RealmConfiguration that can open the old Realm in order to recover any data.

var config = new SyncConfiguration(user, serverURL));
Realm realm;
try
{
    realm = Realm.GetInstance(config);
    // Realm successfully opened, proceed as usual
}
catch (IncompatibleSyncedFileException ex)
{
    // The old Realm was created with a previous version of the SDK. Migrate to the new one.
    var backupConfig = ex.GetBackupRealmConfig();
    var backupRealm = Realm.GetInstance(backupConfig);

    // Reopen the Realm using the original config - it will now be empty
    realm = Realm.GetInstance(config);

    // Migrate any data from backupRealm to realm
    realm.Write(() =>
    {
        foreach (var person in backupRealm.All("Person"))
        {
            // Either migrate manually or use AutoMapper or similar tool
            // to automate most of the process.
            realm.Add(new Person
            {
                Name = person.Name,
                Age = person.Age
            });
        }
    });
}

Current Limitations

Realm is generally trying to have as few constraints as possible and we are continuously adding new features based on feedback from the community. However, Realm still has a few limitations. These have been compiled below.

Please refer to our GitHub issues for a more comprehensive list of known issues.

General Limits

Realm aims to strike a balance between flexibility and performance. In order to accomplish this goal, realistic limits are imposed on various aspects of storing information in a realm. For example:

1. Class names must be between 0 and 57 bytes in length. UTF-8 characters are supported. An exception will be thrown at your app’s initialization if this limit is exceeded.
2. Property names must be between 0 and 63 bytes in length. UTF-8 characters are supported. An exception will be thrown at your app’s initialization if this limit is exceeded.
3. iOS Limitation: The total size of all open Realm files cannot be larger than the amount of memory your application would be allowed to map in iOS — this changes per device, and depends on how fragmented the memory space is at that point in time (there is a radar open about this issue: rdar://17119975). If you need to store more data, you can split into multiple Realm files, and open and close them as needed.

Threads

Although Realm files can be accessed by multiple threads concurrently, you cannot hand over Realms, Realm objects, queries, and results between threads. Read more about Realm’s threading.

File size & tracking of intermediate versions

You should expect a Realm database to take less space on disk than an equivalent SQLite database. If your Realm file is much larger than you expect, it may be because you have a RealmObject that is referring to an older version of the data in the database.

In order to give you a consistent view of your data, Realm only updates the active version accessed at the start of a run loop iteration. This means that if you read some data from the Realm and then block the thread on a long-running operation while writing to the Realm on other threads, the version is never updated and Realm has to hold on to intermediate versions of the data which you may not actually need, resulting in the file size growing with each write. The extra space will eventually be reused by future writes.

If you prefer to reclaim the space deterministically, refer to Compacting the Realm.

FAQ

Is Realm open source?

Yes! Realm’s internal C++ storage engine and the language SDKs over it are entirely open source and licensed under Apache 2.0. Realm also optionally includes a closed-source Realm Platform Extensions component, but that is not required to use Realm as an embedded database.

Building Realm in a CI environment

The Realm build tasks depend on the $(SolutionDir) property being set by MSBuild. This happens when building via the solution file which is why things work out of the box on Visual Studio. In CI environments (e.g. VSTS, Jenkins, Appveyor), often you invoke the msbuild command line tool for individual projects which leaves $(SolutionDir) undefined. To fix that, you’ll need to pass /p:SolutionDir=/path/to/solution/folder to the msbuild command invocation. In most CI environments, the solution directory will be the current folder, ., but this may not apply to all. Refer to your automation server’s documentation for more details.

I see a network call to Mixpanel when I build my app, what is that?

Realm collects anonymous analytics when you run the Realm assembly weaver on your assemblies containing RealmObject classes. This is completely anonymous and helps us improve the product by flagging which version of Realm you use and what OS you use, and what we can deprecate support for. This call does not run when your app is in production, or running on your user’s devices — only when your assemblies are woven by Fody during build. You can see exactly how & what we collect, as well as the rationale for it in our source code.

Does Realm work as a Portable (PCL) Library?

You need to use the iOS, Android, or Win32 version of Realm with your executable but we offer a PCL that you can use to compile against the Realm API with. This is the NuGet Bait and Switch Trick in action. If you add Realm to a PCL project via NuGet, and also add it to your executable, it will work.

Note that this PCL does not mean you can just use Realm on an arbitrary .NET platform. Realm relies on a native C++ core which has to be ported to each platform.

Troubleshooting

Crash Reporting

We encourage you to use a crash reporter in your application. Many Realm operations could potentially fail at runtime (like any other disk IO), so collecting crash reports from your application will help identify areas where either you (or us) can improve error handling and fix crashing bugs.

Most commercial crash reporters have the option of collecting logs. We strongly encourage you to enable this feature. Realm logs metadata information (but no user data) when throwing exceptions and in irrecoverable situations, and these messages can help debug when things go wrong.

Reporting Realm Issues

If you’ve found an issue with Realm, please either file an issue on GitHub or email us at help@realm.io with as much information as possible for us to understand and reproduce your issue.

The following information is very useful to us:

1. Goals.
2. Expected results.
3. Actual results.
4. Steps to reproduce.
5. Code sample that highlights the issue (full projects that we can compile ourselves are ideal).
6. Version of Realm, macOS or Windows & Visual Studio.
7. Xcode if targeting iOS, NDK if targeting Android.
8. Platform, OS version & architecture on which the bug happens (e.g., 64-bit iOS 8.1).
9. Crash logs & stack traces. See Crash Reporting above for details.

Getting an No properties in class exception

You may see a System.InvalidOperationException with the message “No properties in class, has linker stripped it?”.

There are two known causes:

1. You either have no woven RealmObjects, probably because something went wrong with Fody, or
2. Your RealmObjects had their properties stripped so appear to Realm to be empty.

In the first case, the exception will be thrown by RealmSchema. See Failing to Weave for more details.

In the second case, the exception will be thrown from ObjectSchema. We have had some users run into problems when they have the Linker Behaviour set to Link All and they lack the [Preserve(AllMembers = true)] attribute on the class declaration. The linker will only preserve members which are referenced explicitly in the code. This means that if you have a property that would be persisted but is not referenced anywhere, it might be removed causing the schema to mismatch that of the database.

By default, Realm builds the schema to describe all of your RealmObject subclasses in all your assemblies. This happens lazily and so is not triggered until your first call to GetInstance(). It will only do this a maximum of once per run, caching the result in memory.

For a given assembly, if you only wish to store some of your classes, you can specify a subset with ObjectClasses and use that configuration in GetInstance(myConf). That avoids the schema building for all and so will also avoid exceptions.

Otherwise, if you have unused classes, add the Preserve attribute.

Fody: Am unhandled exception occurred

This common build failure can easily be triggered when you have already built a project and just add a new RealmObject subclass.

Choosing Build or Run will not rebuild the project sufficiently to invoke the Fody Weaver.

Simply choose Rebuild on your project and it should build without error.

Failing to Weave

You may see a warning in the build log about classes not having been woven. This indicates that the Fody weaving package is not properly installed.

Firstly, check that the FodyWeavers.xml file contains an entry for RealmWeaver.

The installation will copy RealmWeaver.Fody.dll up into a Tools directly in your solution directory (this is usually a sibling to your project directories). It is not linked into any of the projects but needs to be in that location for Fody to find the DLL.

It is also possible that the installation of Fody has failed. This has been experienced with Visual Studio 2015 and versions of NuGet Package Manager prior to version 3.2. To diagnose this, use a text editor to check that your .csproj has a line importing Fody.targets, such as:

<Import Project="..\packages\Fody.1.29.3\build\portable-net+sl+win+wpa+wp\Fody.targets"
    Condition="Exists('..\packages\Fody.1.29.3\build\portable-net+sl+win+wpa+wp\Fody.targets')" />

Simply upgrading to a later version of NuGet Package Manager should fix this problem.

If this doesn’t work, there seems to be a problem with Fody and Microsoft.Bcl.Build.targets. Removing the following line from your .csproj file might help:

<Import Project="..\..\packages\Microsoft.Bcl.Build.1.0.21\build\Microsoft.Bcl.Build.targets" Condition="Exists('..\..\packages\Microsoft.Bcl.Build.1.0.21\build\Microsoft.Bcl.Build.targets')" />

For more details about this, see this StackOverflow answer.

Troubleshooting WriteAsync Issues

Inside WriteAsync, we check for a non-null SynchronizationContext.Current to indicate if you might be on the UI thread. This check may be confused by a well-established pattern of programming used where people also set Current in their worker threads, so they can use the Post method to run code on the UI thread. This pattern dates back to a 2007 MSDN blog posting.

It is not a problem if you have set SynchronisationContext.Current but it will cause WriteAsync to dispatch again on the thread pool, which may create another worker thread. So, if you are using Current in your threads, consider calling just Write instead of WriteAsync.

Realm Core Binary Fails to Download

When building Realm, part of the process includes downloading the core library as a static binary and integrating it into the Realm project. This is part of the wrappers building by Makefile.

It’s been reported that in certain instances, the core binary fails to download with the following error:

Downloading core failed. Please try again once you have an Internet connection.

This error can occur due to any of the following reasons:

1. Your IP address range is from a region that is on the list of United States embargoes. In order to comply with U.S. law, Realm has not been made available in that region. For more information, please see our license.
2. You are located in mainland China, and due to the country-wide firewall you are not able to properly access CloudFlare or Amazon AWS S3 services at the moment. Please see this issue on one of our other products for more information.
3. Amazon AWS S3 could be experiencing service issues. Please check the AWS Service Health Dashboard and try again later.