Schema Versions & Migrations - .NET SDK

Overview

A migration transforms an existing realm and its objects from its current Realm Schema version to a newer one. Application data models typically change over time to accommodate new requirements and features. Migrations give you the flexibility to automatically update your existing application data whenever a client application upgrades to a newer version.

Consider the following example, in which we have a RealmObject called "Person":

public class Person : RealmObject
{
    [PrimaryKey]
    [MapTo("_id")]
    public ObjectId Id { get; set; }
    public string FullName { get; set; }
    public int Age { get; set; }
}

Suppose we now want to split up the FullName property into two separate properties, FirstName and LastName:

public class Person : RealmObject
{
    [PrimaryKey]
    [MapTo("_id")]
    public ObjectId Id { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public int Age { get; set; }
}

At this point, there is a mismatch between the model and any saved data, and an exception will be thrown when you try to open the realm.

Schema Version

The schema version identifies the state of a Realm Schema at some point in time. Realm Database tracks the schema version of each realm and uses it to map the objects in each realm to the correct schema.

Schema versions are integers that you may include in the realm configuration when you open a realm. If a client application does not specify a version number when it opens a realm then the realm defaults to version 0.

Migrate a Schema

To learn how to perform a migration, see Modify an Object Schema - .NET SDK.