diff --git a/source/includes/baas-server-migration-note.rst b/source/includes/baas-server-migration-note.rst new file mode 100644 index 0000000000..50b4f89ec8 --- /dev/null +++ b/source/includes/baas-server-migration-note.rst @@ -0,0 +1,22 @@ +You can update your data model after you define it. The process of changing your +Realm object schemas depends on whether you are working with a synced realm or +an unsynced (local-only) realm. + +Update a Data Model in a Synced Realm +------------------------------------- +If your app uses Atlas Device Sync to synchronize data with MongoDB Atlas, and +you are working with a synced realm, schema changes are handled differently. + +Synced realms: + +- Support making non-breaking and breaking changes. For more information, refer to :ref:`Breaking Changes ` in the App Services documentation. +- Support server-side versioning. Device SDKs do not currently support client-side + schema versioning in synced realms. +- Automatically migrate objects to the latest server-side schema version without + requiring a manual migration. + +When working with a synced realm, you can update your schema in Atlas App Services +and Device Sync will update the local realm file automatically the next time it +connects. For more information on making server-side schema changes and handling +the differences between the server-side schema and your client data model, refer +to the :ref:`Update a Data Model ` page in the App Services documentation. diff --git a/source/includes/tip-bypass-migration.rst b/source/includes/tip-bypass-migration.rst new file mode 100644 index 0000000000..6deb7e8aad --- /dev/null +++ b/source/includes/tip-bypass-migration.rst @@ -0,0 +1,10 @@ +.. tip:: Bypass Migration During Development + + When **developing or debugging** your application, you may prefer to delete the + realm instead of migrating it. Use the + :realm-react-sdk:`BaseConfiguration.deleteRealmIfMigrationNeeded + ` property to delete the database automatically + when a schema mismatch requires a migration. + + Ensure that this property is always set to ``false`` for production apps. + **Never release an app to production with this property set to true.** \ No newline at end of file diff --git a/source/sdk/dotnet/model-data/change-an-object-model.txt b/source/sdk/dotnet/model-data/change-an-object-model.txt index 87bd9ea4f4..d9eb63a7ab 100644 --- a/source/sdk/dotnet/model-data/change-an-object-model.txt +++ b/source/sdk/dotnet/model-data/change-an-object-model.txt @@ -10,19 +10,18 @@ Change an Object Model - .NET SDK .. contents:: On this page :local: :backlinks: none - :depth: 2 + :depth: 3 :class: singlecol .. _dotnet-schema-version: -Overview --------- -A **migration** transforms an existing realm and its objects from its -current :ref:`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. +.. include:: /includes/baas-server-migration-note.rst + +Update a Data Model in an Unsynced (Local-Only) Realm +----------------------------------------------------- + +Data Model Changes +~~~~~~~~~~~~~~~~~~ Consider the following example, in which we have a ``RealmObject`` called "Person": @@ -40,7 +39,7 @@ 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 :ref:`Realm Schema ` at some point in time. Realm tracks the schema @@ -62,7 +61,7 @@ the realm defaults to version ``0``. :ref:`object schemas `. Migrate a Schema ----------------- +~~~~~~~~~~~~~~~~ .. _dotnet-og-schema: @@ -91,7 +90,7 @@ A realm using schema version ``1`` has a ``Person`` object type: .. _dotnet-add-a-property: Add a Property --------------- +`````````````` The following example adds a ``LastName`` property to the :ref:`original Person schema `: @@ -103,7 +102,7 @@ The following example adds a ``LastName`` property to the .. _dotnet-delete-a-property: Delete a Property ------------------ +````````````````` The following example uses a combined ``FullName`` property instead of the separate ``FirstName`` and @@ -117,7 +116,7 @@ The following example uses a combined .. _dotnet-rename-a-property: Modify a Property Type or Rename a Property -------------------------------------------- +``````````````````````````````````````````` The following example modifies the ``Age`` property in the :ref:`original Person schema ` by @@ -129,18 +128,8 @@ renaming it to ``Birthday`` and changing the type to ``DateTimeOffset``: .. _dotnet-migration-function: -Migration Functions -------------------- - -.. tip:: Bypass Migration During Development - - When developing or debugging your application, you may prefer to delete - the realm instead of migrating it. Use the - :dotnet-sdk:`ShouldDeleteIfMigrationNeeded ` - 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``. +Create a Migration Function +``````````````````````````` To migrate the realm to conform to the updated ``Person`` schema, set the realm's :ref:`schema version ` to @@ -152,3 +141,5 @@ properties and the value of ``Birthday`` based on ``Age``: :language: csharp :emphasize-lines: 3, 21, 25, 31 :linenos: + +.. include:: /includes/tip-bypass-migration.rst \ No newline at end of file diff --git a/source/sdk/flutter/realm-database/model-data/update-realm-object-schema.txt b/source/sdk/flutter/realm-database/model-data/update-realm-object-schema.txt index 56cf951558..fc560ae6cf 100644 --- a/source/sdk/flutter/realm-database/model-data/update-realm-object-schema.txt +++ b/source/sdk/flutter/realm-database/model-data/update-realm-object-schema.txt @@ -8,10 +8,14 @@ Update a Realm Object Schema - Flutter SDK .. contents:: On this page :local: :backlinks: none - :depth: 2 + :depth: 3 :class: singlecol -You can change the schema of a Realm object after you first create it. +.. include:: /includes/baas-server-migration-note.rst + +Update a Data Model in an Unsynced (Local-Only) Realm +----------------------------------------------------- + Depending on the type of changes you make to the schema, the changes can be either automatically applied or require a manual update to the new schema. Manual schema updates are called **migrations** in Realm. @@ -24,25 +28,10 @@ You must perform a manual migration for all other schema changes. For more information, refer to the :ref:`Manually Migrate Schema section `. -.. tip:: Bypass Migration During Development - - When developing or debugging your application, you may prefer to delete - the realm instead of migrating it. Use the - :flutter-sdk:`LocalConfiguration.shouldDeleteIfMigrationNeeded ` - property to delete the database automatically when a schema mismatch - requires a migration. - -.. important:: Modify Schema Properties of a Synced Realm - - The contents on this page only apply to local realms. - Schema migration functions differently for Realm using Atlas Device Sync - to synchronize data with MongoDB Atlas. - Refer to the :ref:`Updating the Schema of a Synced Realm section `. - .. _flutter-schema-version: Schema Version --------------- +~~~~~~~~~~~~~~ A **schema version** identifies the state of a :ref:`realm schema ` at some point in time. Realm tracks the @@ -64,7 +53,7 @@ object schemas. .. _flutter-automatically-update-schema: Automatically Update Schema ---------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~ Realm can automatically migrate added and deleted properties. You must update the schema version when you make these changes. @@ -72,7 +61,7 @@ You must update the schema version when you make these changes. .. _flutter-add-a-property: Add a Property -~~~~~~~~~~~~~~ +`````````````` To add a property to a schema: @@ -101,7 +90,7 @@ To add a property to a schema: .. _flutter-delete-a-property: Delete a Property -~~~~~~~~~~~~~~~~~ +````````````````` To delete a property from a schema: @@ -128,7 +117,7 @@ Deleting a property does not impact existing objects. .. _flutter-manually-migrate-schema: Manually Migrate Schema ------------------------ +~~~~~~~~~~~~~~~~~~~~~~~ For more complex schema updates, Realm requires you to manually migrate old instances of a given object to the new schema. @@ -152,7 +141,7 @@ The following sections explain how to perform various migration operations. .. _flutter-delete-object-type: Delete an Object Type -~~~~~~~~~~~~~~~~~~~~~ +````````````````````` To delete all objects of a type from your realm, pass a string representation of the object schema's name to :flutter-sdk:`Migration.deleteType() `. @@ -166,7 +155,7 @@ but the new version of the schema does not. .. _flutter-rename-property: Rename a Property -~~~~~~~~~~~~~~~~~ +````````````````` Rename a schema property with :flutter-sdk:`Migration.renameProperty() `. @@ -177,7 +166,7 @@ Rename a schema property with :flutter-sdk:`Migration.renameProperty() .. _flutter-other-migration-tasks: Other Migration Tasks -~~~~~~~~~~~~~~~~~~~~~ +````````````````````` To perform other realm schema migrations, use the following properties of the ``Migration`` object in your migration callback function: @@ -200,16 +189,4 @@ use the :flutter-sdk:`RealmObjectBase.dynamic `. +.. include:: /includes/tip-bypass-migration.rst \ No newline at end of file diff --git a/source/sdk/java/model-data/modify-an-object-schema.txt b/source/sdk/java/model-data/modify-an-object-schema.txt index bcc458fd63..176b6c24ca 100644 --- a/source/sdk/java/model-data/modify-an-object-schema.txt +++ b/source/sdk/java/model-data/modify-an-object-schema.txt @@ -10,7 +10,7 @@ Change an Object Model - Java SDK .. contents:: On this page :local: :backlinks: none - :depth: 2 + :depth: 3 :class: singlecol .. tabs:: @@ -169,12 +169,13 @@ Change an Object Model - Java SDK You can make changes to the schema of a synchronized realm by modifying the :ref:`JSON Schema ` - defined in your application's backend. Synchronized realms do - not require migration functions, since breaking changes to - synchronized schemas cause synchronization errors. Sync - handles non-breaking changes to synchronized realm schemas - automatically. As a result, both old versions of your schema and - new versions can synchronize as users upgrade their applications. + defined in your application's backend, or by changing the schema + in your Atlas App Services app. + + Synchronized realms do not require migration functions. Breaking + changes made on the client cause synchronization errors, but non-breaking + changes are handled automatically. As a result, either version of your + schema can synchronize as users upgrade their applications. To learn more about schema changes to synchronized realms, see :ref:`synced schema changes `. diff --git a/source/sdk/kotlin/realm-database/schemas/change-an-object-model.txt b/source/sdk/kotlin/realm-database/schemas/change-an-object-model.txt index ece22a5c6b..0cd60464a3 100644 --- a/source/sdk/kotlin/realm-database/schemas/change-an-object-model.txt +++ b/source/sdk/kotlin/realm-database/schemas/change-an-object-model.txt @@ -8,39 +8,19 @@ Change an Object Model - Kotlin SDK .. contents:: On this page :local: :backlinks: none - :depth: 2 + :depth: 3 :class: singlecol -.. include:: /includes/note-modify-schema-properties-of-synced-realms.rst -Overview --------- +.. include:: /includes/baas-server-migration-note.rst -You can make changes to your object schema after you -:ref:`create your Realm object model `. -Depending on the type of changes you make to the schema, the changes can be -automatically applied or require a manual update to the new schema. - -- Realm will automatically update a Realm :ref:`object schema ` when you add or - delete a property from a Realm object model. - You only need to update the schema version. -- For all other schema changes, you must manually migrate old instances - of a given object to the new schema. - -.. tip:: Bypass Migration During Development - - When developing or debugging your application, you may prefer to :ref:`delete - the realm ` instead of migrating it. Use the - `deleteRealmIfMigrationNeeded <{+kotlin-local-prefix+}io.realm.kotlin/-realm-configuration/-builder/delete-realm-if-migration-needed.html>`__ - 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``. +Update a Data Model in an Unsynced (Local-Only) Realm +----------------------------------------------------- .. _kotlin-schema-version: Schema Version --------------- +~~~~~~~~~~~~~~ A **schema version** identifies the state of a :ref:`realm schema` at some point in time. @@ -64,7 +44,7 @@ realm, then the realm defaults to version ``0``. .. _kotlin-migrations: Migration ---------- +~~~~~~~~~ Schema updates are called **migrations** in Realm. A migration updates a realm and any objects it @@ -92,16 +72,15 @@ automatically :ref:`Sync ` with another realm. Device Sync documentation. Automatically Update Schema ---------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If your schema update adds or removes properties, -Realm can perform the migration automatically. -You only need to increment the ``schemaVersion``. +If your schema update adds or removes properties, Realm can perform the migration +automatically. You only need to increment the ``schemaVersion``. .. _kotlin-add-a-property: Add a Property -~~~~~~~~~~~~~~ +`````````````` To add a property to a schema: @@ -137,7 +116,7 @@ set values for the new property through a :ref:`migration function ` at some point in time. Realm tracks the @@ -38,7 +43,7 @@ the realm defaults to version ``0``. .. _node-migrations: Migrations ----------- +~~~~~~~~~~ A **migration** is a function that updates a realm and any objects it contains from one schema version to a newer @@ -69,7 +74,7 @@ in the migration function to further customize property values. .. _node-add-a-property: 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 :js-sdk:`realm's configuration object @@ -107,7 +112,7 @@ set a ``schemaVersion`` of the :js-sdk:`realm's configuration object .. _node-delete-a-property: Delete a Property ------------------ +````````````````` To delete a property from a schema, remove the property from the object's class and set a ``schemaVersion`` of the :js-sdk:`realm's configuration object @@ -136,7 +141,7 @@ objects. .. _node-rename-a-property: Rename a Property ------------------ +````````````````` To rename an object property, change the property name in the object schema and then open the realm with an incremented :ref:`schema version @@ -179,7 +184,8 @@ property, and then delete the old property. 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 :js-sdk:`realm's configuration Object @@ -213,3 +219,5 @@ callback function of the :js-sdk:`realm's configuration Object .. literalinclude:: /examples/Migrations/LocalMigration/LocalMigration-modify-property-type.js :language: javascript :emphasize-lines: 3, 12 + +.. include:: /includes/tip-bypass-migration.rst \ No newline at end of file diff --git a/source/sdk/react-native/model-data/change-an-object-model.txt b/source/sdk/react-native/model-data/change-an-object-model.txt index e0cf9b1ca3..005cbdd49c 100644 --- a/source/sdk/react-native/model-data/change-an-object-model.txt +++ b/source/sdk/react-native/model-data/change-an-object-model.txt @@ -7,10 +7,13 @@ Change an Object Model - React Native SDK .. contents:: On this page :local: :backlinks: none - :depth: 2 + :depth: 3 :class: singlecol -.. include:: /includes/note-modify-schema-properties-of-synced-realms.rst +.. include:: /includes/baas-server-migration-note.rst + +Update a Data Model in an Unsynced (Local-Only) Realm +----------------------------------------------------- When updating your object schema, you must increment the schema version and perform a migration. @@ -28,20 +31,10 @@ in a ``migration`` function. This might include changes such as: - Changing a field's type - Converting from an object to an embedded object -.. tip:: Bypass Migration During Development - - When developing or debugging your application, you may prefer to delete the - realm instead of migrating it. Use the - :realm-react-sdk:`BaseConfiguration.deleteRealmIfMigrationNeeded - ` property to delete the database automatically - when a schema mismatch requires a migration. - - Never release an app to production with this property set to ``true``. - .. _react-native-schema-version: Schema Version --------------- +~~~~~~~~~~~~~~ A **schema version** identifies the state of a :ref:`realm schema ` at some point in time. Realm tracks the @@ -63,7 +56,7 @@ realm defaults to version ``0``. .. _react-native-migrations: Migrations ----------- +~~~~~~~~~~ A **migration** is a function that updates a realm and any objects it contains from one :ref:`schema version ` to a newer version. @@ -84,7 +77,7 @@ in the migration function to further customize property values. .. _react-native-add-a-property: 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 ``Configuration`` object. @@ -118,7 +111,7 @@ set a ``schemaVersion`` of the ``Configuration`` object. .. _react-native-delete-a-property: 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-react-sdk:`Configuration @@ -156,7 +149,7 @@ impact existing objects. .. _react-native-rename-a-property: Rename a Property ------------------ +````````````````` To rename an object property, change the property name in the object schema and then create a realm configuration with an incremented :ref:`schema version @@ -210,7 +203,7 @@ property, and then delete the old property. 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`` @@ -252,4 +245,6 @@ callback function of the :realm-react-sdk:`Configuration .. literalinclude:: /examples/generated/react-native/js/change-an-object-model-test.snippet.modify-a-property-type.jsx :language: javascript - :emphasize-lines: 6, 18, 29 \ No newline at end of file + :emphasize-lines: 6, 18, 29 + +.. include:: /includes/tip-bypass-migration.rst \ No newline at end of file diff --git a/source/sdk/swift/model-data/change-an-object-model.txt b/source/sdk/swift/model-data/change-an-object-model.txt index 408875fba8..22d44c881d 100644 --- a/source/sdk/swift/model-data/change-an-object-model.txt +++ b/source/sdk/swift/model-data/change-an-object-model.txt @@ -10,10 +10,12 @@ Change an Object Model - Swift SDK :depth: 2 :class: singlecol -.. include:: /includes/note-modify-schema-properties-of-synced-realms.rst -Overview --------- + +.. include:: /includes/baas-server-migration-note.rst + +Update a Data Model in an Unsynced (Local-Only) Realm +----------------------------------------------------- When you update your object schema, you must increment the schema version and perform a migration. @@ -37,21 +39,13 @@ in a ``migrationBlock``. This might include changes such as: - Changing a field's type - Converting from an object to an embedded object -.. tip:: Bypass Migration During Development - - When developing or debugging your application, you may prefer to delete - the realm instead of migrating it. Use the - :swift-sdk:`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``. +.. include:: /includes/tip-bypass-migration.rst .. _ios-schema-versions-and-migrations: .. _ios-schema-version: Schema Version --------------- +~~~~~~~~~~~~~~ A **schema version** identifies the state of a :ref:`Realm Schema ` at some point in time. Realm tracks the schema @@ -92,12 +86,12 @@ manual migration, you can define new and deleted properties when they are added or removed from your schema. Automatically Update Schema ---------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. _ios-add-a-property: Add a Property -~~~~~~~~~~~~~~ +`````````````` Realm can automatically migrate added properties, but you must specify an updated schema version when you make @@ -165,7 +159,7 @@ these changes. .. _ios-delete-a-property: 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 @@ -235,7 +229,7 @@ will not impact existing objects. .. _ios-perform-a-schema-migration: Manually Migrate Schema ------------------------ +~~~~~~~~~~~~~~~~~~~~~~~ For more complex schema updates, Realm requires a manual migration for old instances of a given object to the new schema. @@ -243,7 +237,7 @@ migration for old instances of a given object to the new schema. .. _ios-rename-a-property: Rename a Property -~~~~~~~~~~~~~~~~~ +````````````````` To rename a property during a migration, use the :swift-sdk:`Migration.renameProperty(onType:from:to:) @@ -275,7 +269,8 @@ during the rename operation. .. _ios-modify-properties: Modify Properties -~~~~~~~~~~~~~~~~~~ +````````````````` + .. tip:: You can use the :swift-sdk:`deleteRealmIfMigrationNeeded ` @@ -385,7 +380,7 @@ Realm type in the realm. .. _ios-convert-to-an-embedded-object: Convert from Object to EmbeddedObject -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +````````````````````````````````````` :ref:`Embedded objects ` cannot exist independently of a parent object. When changing an Object to an @@ -410,8 +405,10 @@ or multiple backlinks raises the following exceptions: .. _ios-additional-migration-examples: Additional Migration Examples ------------------------------ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Please check out the additional migration examples on the :github:`realm-swift repo `. + +.. include:: /includes/tip-bypass-migration.rst \ No newline at end of file