Puedes cambiar el esquema de un objeto de Realm después de crearlo. Según el tipo de cambios que realices, estos pueden aplicarse automáticamente o requerir una actualización manual del nuevo esquema. Las actualizaciones manuales del esquema se denominan migraciones en Realm.
Puede actualizar automáticamente un esquema de objeto de Realm al agregar o eliminar una propiedad de un modelo de objeto de Realm. Para obtener más información, consulte Sección Actualizar esquema automáticamente.
Debe realizar una migración manual para todos los demás cambios de esquema. Para obtener más información, consulte la sección Migración manual del esquema.
Tip
Evitar la migración durante el desarrollo
Al desarrollar o depurar su aplicación, puede que prefiera eliminar el dominio en lugar de migrarlo. Utilice LocalConfiguration.shouldDeleteIfMigrationNeeded. propiedad para eliminar la base de datos automáticamente cuando una falta de coincidencia de esquema requiere una migración.
Importante
Modificar las propiedades del esquema de un dominio sincronizado
El contenido de esta página solo se aplica a los dominios locales. La migración de esquemas funciona de forma diferente para dominios que utilizan Atlas Device Sync para sincronizar datos con MongoDB Atlas.Consulte la sección "Actualizar el esquema de un dominio sincronizado".
Versión del esquema
Una versión de esquema identifica el estado de un esquema de dominio en un momento dado. Realm rastrea la versión de esquema de cada dominio y la utiliza para asignar los objetos de cada dominio al esquema correcto.
Las versiones del esquema son números enteros ascendentes que se pueden incluir opcionalmente en la configuración del dominio al abrirlo. Si una aplicación cliente no especifica un número de versión al abrir un dominio, este se configura de forma predeterminada como la versión. 0.
Las migraciones manuales deben actualizar un dominio a una versión de esquema superior. El dominio genera un error si una aplicación cliente abre un dominio con una versión de esquema inferior a la actual, o si la versión de esquema especificada coincide con la actual, pero incluye esquemas de objetos diferentes.
Actualizar automáticamente el esquema
Realm puede migrar automáticamente las propiedades añadidas y eliminadas. Debe actualizar la versión del esquema al realizar estos cambios.
Agregar una propiedad
Para agregar una propiedad a un esquema:
Añade la nueva propiedad a la clase
RealmModeldel objeto.Establezca una versión de esquema en el objeto de configuración del reino.
Ejemplo
Un reino que usa la versión de esquema 1 tiene un tipo de objeto Person con propiedades firstName y lastName. El desarrollador decide añadir una propiedad age a la clase RealmModel _Person.
Para cambiar el reino para que se ajuste al Person esquema actualizado, el desarrollador establece la versión del esquema del reino 2 en.
() class _Person { late String firstName; late String lastName; late int age; }
final config = Configuration.local([Person.schema], schemaVersion: 2); final realm = Realm(config);
Eliminar una propiedad
Para eliminar una propiedad de un esquema:
Eliminar la propiedad de la clase
RealmModeldel objeto.En la configuración del reino, incluya el
RealmObject.schemaregenerado e incremente elschemaVersion.
Eliminar una propiedad no afecta a los objetos existentes.
Ejemplo
Un dominio que usa la versión de esquema 1 tiene un tipo de objeto Person con una propiedad weight. El desarrollador decide eliminar la propiedad del esquema.
Para migrar el reino para Person que se ajuste al esquema actualizado, el desarrollador establece la versión del esquema del reino 2 en.
final config = Configuration.local([Person.schema], schemaVersion: 2); final realm = Realm(config);
Migrar esquema manualmente
Para actualizaciones de esquema más complejas, Realm requiere que migre manualmente instancias antiguas de un objeto determinado al nuevo esquema.
Al abrir el reino con el esquema actualizado, debe hacer lo siguiente en el Configuration del reino:
Incrementa la propiedad
schemaVersion.Defina la lógica de migración en una propiedad migrationCallback de la configuración de un dominio. La devolución de llamada de migración tiene los siguientes parámetros:
Las siguientes secciones explican cómo realizar diversas operaciones de migración.
Eliminar un tipo de objeto
Para eliminar todos los objetos de un tipo de su reino, pase una representación de cadena del nombre del esquema del objeto a Migration.deleteType().
Esto es útil si la versión anterior de un esquema tiene un tipo de objeto Realm, pero la nueva versión del esquema no.
final configWithoutPerson = Configuration.local([Car.schema], schemaVersion: 2, migrationCallback: ((migration, oldSchemaVersion) { // Between v1 and v2 we removed the Person type migration.deleteType('Person'); })); final realmWithoutPerson = Realm(configWithoutPerson);
Cambiar el nombre de una propiedad
Cambie el nombre de una propiedad de esquema con Migration.renameProperty().
final configWithRenamedAge = Configuration.local([Person.schema, Car.schema], schemaVersion: 2, migrationCallback: ((migration, oldSchemaVersion) { // Between v1 and v2 we renamed the Person 'age' property to 'yearsSinceBirth' migration.renameProperty('Person', 'age', 'yearsSinceBirth'); })); final realmWithRenamedAge = Realm(configWithRenamedAge);
Otras tareas de migración
Para realizar otras migraciones de esquema de reino, utilice las siguientes propiedades del objeto Migration en su función de devolución de llamada de migración:
Migration.oldRealm: El dominio tal como existía justo antes de la migración con la versión anterior del esquema. Debe usar
oldRealmla API dinámica de para acceder a sus objetos, ya que no se pueden usar consultas estándar basadas en tipos. La API dinámica permite encontrar objetos de dominio mediante una representación de cadena de su nombre de clase.Migration.newRealm: El dominio tal como existe después de la migración. Al finalizar la devolución de llamada de migración, debe migrar todos los datos afectados por la actualización del esquema
oldRealmdenewRealma. Se perderán todos los datos afectados por la actualización del esquema que no se migren.
Para encontrar instancias de un objeto de un dominio antiguo en el nuevo dominio, utilice Migration.findInNewRealm(). Para acceder a las propiedades de los objetos del esquema antiguo, utilice la API RealmObjectBase.dynamic.
final configWithChanges = Configuration.local([Person.schema, Car.schema], schemaVersion: 2, migrationCallback: ((migration, oldSchemaVersion) { // Dynamic query for all Persons in previous schema final oldPeople = migration.oldRealm.all('Person'); for (final oldPerson in oldPeople) { // Find Person instance in the updated realm final newPerson = migration.findInNewRealm<Person>(oldPerson); if (newPerson == null) { // That person must have been deleted, so nothing to do. continue; } // Use dynamic API to get properties from old schema and use in the // new schema newPerson.fullName = "${oldPerson.dynamic.get<String>("firstName")} ${oldPerson.dynamic.get<String>("lastName")}"; // convert `id` from ObjectId to String final oldId = oldPerson.dynamic.get<ObjectId>("id"); newPerson.id = oldId.toString(); } })); final realmWithChanges = Realm(configWithChanges);
Actualización del esquema de un reino sincronizado
Actualizar el esquema de un realm sincronizado es un proceso separado de la actualización del esquema de un realm sólo local.
Los dominios sincronizados no tienen versiones de esquema y migran automáticamente los objetos al esquema más reciente. Los dominios sincronizados solo admiten cambios de esquema permanentes.
Aprenda a modificar las propiedades del esquema de un reino sincronizado.