Modify an Object Schema - Node.js SDK
Note
Modify Schema Properties of a Synced Realm
The following page demonstrates how to modify schema properties of a local realm. Learn how to modify schema properties of a synced realm.
Tip
Bypass Migration During Development
When developing or debugging your application, you may prefer to delete
the realm instead of migrating it. Use the
deleteRealmIfMigrationNeeded flag to delete the database
automatically when a schema mismatch would require a migration.
Never release an app to production with this flag set to true.
Add a Property
To add a property to a schema, add the new property to the object's class and
set a schemaVersion of the realm's configuration object.
Example
A realm using schema version 1 has a Person object type with a
firstName, and lastName property. The developer decides to add an
age property to the Person class.
To migrate the realm to conform to the updated Person schema, the
developer sets the realm's schema version to
2.
Delete a Property
To delete a property from a schema, remove the property from the object's class
and set a schemaVersion of the realm's configuration object. Deleting a property will not impact existing
objects.
Example
A realm using schema version 1 has a Dog object type with a
weight property. The developer decides to remove the property from the
schema.
To migrate the realm to conform to the updated Dog schema, the
developer sets the realm's schema version to
2.
Rename a Property
To rename an object property, change the property name in the object schema and then open the realm with an incremented schema version and a migration function that updates existing objects to use the new property name.
Migrations do not allow you to directly rename a property. Instead you can create a new property with the updated name, copy the value from the old property, and then delete the old property.
Example
A realm using schema version 1 has a Person object type. The
original schema had a firstName and lastName field. The developer
later decides that the Person class should use a combined fullName
field and removes the separate firstName and lastName fields.
To migrate the realm to conform to the updated Person schema, the
developer sets the realm's schema version to
2 and defines a migration function to set the value of fullName based
on the existing firstName and lastName properties.
Important
Synced Realms
Synced realms only support non-breaking - also called additive - changes to ensure that older clients can sync with newer clients. Because full renames require you to delete the old property, you cannot rename a synchronized property without requiring a client reset. Instead, consider adding the renamed property without deleting the old property. Alternately, use mapTo to store data using the existing internal name, but let your code use a different name.
Modify a Property Type
To modify a property's type, set the property type of the field that you wish to
modify to the new data type. Then, set a schemaVersion, and a migration
callback function of the realm's configuration Object.
Note
Synchronized realms only support non-breaking changes, to ensure that older clients can sync with newer clients. This means that synchronized realms do not support modifying the type of a property of a schema.
Example
A realm using schema version 1 has a Dog object type. The
original schema had an _id with a property type of Object ID. The
developer later decides that the Dog class's _id field should be of
type string, and updates the schema.
To migrate the realm to conform to the updated Dog schema, the
developer sets the realm's schema version to
2 and defines a migration function to convert the Object ID type to a
string type.