Schema Versions & Migrations - .NET SDK
On this page
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 { [ ] [ ] 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 { [ ] [ ] 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
.
Migrations must update a realm to a higher schema version. Realm Database will throw an error if a client application opens a realm with a schema version that is lower than the realm's current version or if the specified schema version is the same as the realm's current version but includes different object schemas.
Migrate a Schema
To learn how to perform a migration, see Modify an Object Schema - .NET SDK.