Docs Menu

Schema Versions & Migrations - .NET SDK

On this page

  • Overview
  • Schema Version
  • Migrate a Schema

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.

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.

Important
Increment Versions Monotonically

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.

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

Give Feedback
MongoDB logo
© 2021 MongoDB, Inc.

About

  • Careers
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2021 MongoDB, Inc.