Menu Docs
Página inicial do Docs
/
MongoDB Atlas
/
Atlas Device SDKs
/
SDK do Flutter
/
Realm Database
/
Dados do modelo

Atualizar um esquema de objeto de Realm - SDK Flutter

Nesta página

  • Versão do esquema
  • Atualize esquemas automaticamente
  • Adicionar uma propriedade
  • Excluir uma propriedade
  • Migre esquemas manualmente
  • Excluir um tipo de objeto
  • Renomear uma propriedade
  • Outras tarefas de migração
  • Atualizando o esquema de um domínio sincronizado

Você pode alterar o esquema de um objeto do Realm após criá-lo pela primeira vez. Dependendo do tipo de alterações feitas no esquema, elas podem ser aplicadas automaticamente ou exigir uma atualização manual para o novo esquema. As atualizações manuais do esquema são chamadas de migrações no Realm.

Você pode atualizar automaticamente um esquema de Objeto de Realm quando adicionar ou excluir uma propriedade de um modelo de Objeto de Realm . Para obter mais informações, consulte a seção Atualizar esquema automaticamente.

Você deve realizar uma migração manual para todas as outras alterações de esquema. Para obter mais informações, consulte a seção Migrar esquema manualmente.

Dica

Ignorar migração durante o desenvolvimento

Ao desenvolver ou depurar seu aplicação, talvez você prefira excluir o Realm em vez de migrá-lo. Utilize o arquivo LocalConfiguration.shouldDeleteIfMigrationNeeded propriedade para excluir o banco de dados de dados automaticamente quando uma incompatibilidade de esquema exige uma migração.

Importante

Modificar Propriedades do Esquema de um Domínio Sincronizado

O conteúdo desta página se aplica somente aos domínios locais. A migração do esquema funciona de forma diferente para o Realm usando o Atlas Device Sync para sincronizar dados com o MongoDB Atlas. Consulte a seção Atualização do esquema de um domínio Realm .

Versão do esquema

Uma versão do esquema de esquema de domínio identifica o estado de um esquema de território em algum momento no tempo. Realm controla a versão do esquema de cada realm e usa-o para mapear os objetos em cada realm para o esquema correto.

As versões de esquema são inteiros ascendentes que você pode incluir opcionalmente na configuração do território ao abrir um realm. Se um aplicativo cliente não especificar um número de versão quando abrir um domínio, o domínio assumirá como padrão a versão 0.

As migrações manuais devem atualizar um realm para uma versão superior do esquema. O Realm exibe um erro se um aplicativo cliente abrir um realm com uma versão do esquema inferior à versão atual do realm ou se a versão do esquema especificada for igual à versão atual do realm, mas incluir esquemas de objetos diferentes.

Atualize esquemas automaticamente

O Realm pode migrar automaticamente propriedades adicionadas e excluídas. Você deve atualizar a versão do esquema quando fizer essas alterações.

Adicionar uma propriedade

Para adicionar uma propriedade a um esquema:

  1. Adicione a nova propriedade à classe RealmModel do objeto.

  2. Regenerar o RealmObject.

  3. Defina uma versão do esquema para o objeto de Configuração do Realm.

Exemplo

Um domínio que utiliza esquema versão 1 tem um tipo de objeto Person com uma propriedade firstName e lastName . O desenvolvedor decide adicionar uma propriedade age na classe _Person RealmModel.

Para alterar o Realm para que fique em conformidade com o esquema Person atualizado, o desenvolvedor define a versão do esquema do realm como 2.

@RealmModel()
class _Person {
  late String firstName;
  late String lastName;
  late int age;
}
final config = Configuration.local([Person.schema], schemaVersion: 2);
final realm = Realm(config);

Excluir uma propriedade

Para excluir uma propriedade de um esquema:

  1. Remova a propriedade da classe RealmModel do objeto.

  2. Regenerar o RealmObject.

  3. Na configuração do remo, inclua o RealmObject.schema regenerado e incremente o schemaVersion.

Excluir uma propriedade não afeta os objetos existentes.

Exemplo

Um domínio que utiliza esquema versão 1 tem um tipo de objeto Person com uma propriedade weight. O desenvolvedor decide remover a propriedade do esquema.

Para migrar o realm para estar em conformidade com o esquema de Person atualizado, o desenvolvedor define a versão do esquema do realm como 2.

final config = Configuration.local([Person.schema], schemaVersion: 2);
final realm = Realm(config);

Migre esquemas manualmente

Para atualizações de esquema mais complexas, o Realm exige que você migre manualmente instâncias antigas de um determinado objeto para o novo esquema.

Ao abrir o realm com o esquema atualizado, você deve fazer o seguinte no Configuration do realm:

  • Aumentar a propriedade schemaVersion.

  • Defina a lógica de migração em um migrationCallback propriedade da configuração de um realm . O retorno de chamada de migração possui os seguintes parâmetros:

    • migration: Uma instância do Migration com acesso ao domínio atual, ao domínio para o qual você está migrando e a métodos para ajudar na operação de migração.

    • oldSchemaVersion: o número da versão de esquema anterior do realm no dispositivo.

As seções a seguir explicam como realizar várias operações de migração.

Excluir um tipo de objeto

Para excluir todos os objetos de um tipo do seu realm, passe uma representação de string do nome do esquema de objeto para Migration.deleteType().

Isso será útil se a versão anterior de um esquema tiver um tipo de objeto de Realm, mas a nova versão do esquema não.

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);

Renomear uma propriedade

Renomear uma propriedade de esquema com 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);

Outras tarefas de migração

Para realizar outras migrações do esquema de domínio, use as seguintes propriedades do objeto Migration em sua função de retorno de chamada de migração:

  • Migration.oldRealm: A região tal como existia pouco antes da migração com a versão do esquema anterior. Você deve usar a API dinâmica do oldRealm para acessar seus objetos porque não é possível usar queries baseadas em tipo padrão. A API dinâmica permite localizar objetos de Realm por meio de uma representação de string de seu nome de classe.

  • Migration.newRealm: O domínio tal como existe após a migração. Ao final do retorno de chamada de migração, você deve migrar todos os dados afetados pela atualização de esquema do oldRealm para o newRealm. Qualquer dado afetado pela atualização do esquema que não for migrado será perdido.

Para localizar instâncias de um objeto em um antigo realm no novo realm, use Migration.findInNewRealm(). Para acessar as propriedades dos objetos do esquema antigo, use a 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);

Atualizando o esquema de um domínio sincronizado

Atualizar o esquema de um domínio sincronizado é um processo separado de atualizar o esquema de um domínio somente local.

Os domínios sincronizados não têm versões de esquema e migram automaticamente objetos para o esquema mais recente. Os domínios sincronizados suportam apenas alterações de esquema ininterruptas.

Saiba como modificar as propriedades do esquema de um domínio sincronizado.

Voltar

Anotações da propriedade

Próximo

Dados geoespaciais