Atualize seu modelo de dados

Mudanças de última hora

Alterações de esquema significativas são difíceis porque os clientes mais antigos (aqueles que não foram atualizados para seu novo código e esquema) ainda precisam acessar os dados por meio da definição de esquema antiga. Os clientes atualizados precisam trabalhar com as novas alterações de esquema.

Referência rápida sobre mudanças significativas versus não significativas

Uma alteração significativa é uma alteração feita no esquema do lado do servidor que requer uma ação adicional com a qual lidar. Uma alteração de esquema no lado do servidor exige que você encerre a sincronização no backend e, em seguida, reative a sincronização. As alterações de esquema significativas resultam na impossibilidade de os clientes abrirem um domínio ou na ocorrência de perda de dados quando os documentos do lado do servidor não conseguem sincronizar com aplicativos do lado do cliente. Eles impedem que os aplicativos se recuperem automaticamente de uma redefinição do cliente.

Uma alteração não significativa é uma alteração que você pode fazer no esquema do lado do servidor ou no modelo de objeto sem exigir ação adicional em seu aplicativo. Também conhecidas como alterações cumulativas, elas se aplicam automaticamente a domínios sincronizados.

Observação

Aplicar alterações não significativas ao cliente pode exigir migração

Quando você somente faz alterações não significativas no esquema do lado do servidor, nenhuma ação adicional é necessária. No entanto, se você tentar aplicar essas alterações ao seu modelo de objeto de cliente, talvez seja necessário realizar uma migração. Se o dispositivo do cliente tiver um arquivo de domínio existente, você deverá realizar uma migração. Para obter detalhes, consulte a página Modificar um esquema de objeto no SDK de sua preferência.

O diagrama a seguir mostra os tipos de alterações de esquema que você pode fazer e o processo pelo qual você passa para realizar a alteração. Cada uma dessas alterações é explicada em mais detalhes na tabela e nas seções abaixo.

Esta tabela resume cada tipo de alteração e se é uma alteração significativa ou não.

Tipo de alteração	Esquema do lado do servidor	Modelo de objeto do lado do cliente
Adicionar um tipo de objeto	Não significativas	Não significativas
Adicionar um valor padrão em uma propriedade	Não significativas	Não significativas
Adicionar uma propriedade obrigatória	Não significativas	Não significativas
Adicionar uma propriedade opcional	Não significativas	Não significativas
Remover um tipo de objeto	Significativa	Não significativas
Remover uma propriedade opcional ou obrigatória	Significativa	Não significativas
Alterar um nome de tipo de objeto	Significativa*	Significativa*
Alterar um nome de propriedade	Significativa*	Significativa*
Alterar o tipo de propriedade, mas manter o nome	Significativa	Significativa
Alterar o status da propriedade entre opcional e obrigatório	Significativa	Significativa

Dica

Renomear uma propriedade

Embora renomear uma propriedade ou objeto seja uma alteração significativa, alguns dos SDKs do Realm oferecem uma solução alternativa para remapear o nome da propriedade. Consulte Alterar o nome de uma propriedade para obter mais detalhes.

Adicionar um tipo de objeto

Você pode adicionar um tipo de objeto ao esquema do lado do servidor ou ao modelo de objeto do cliente sem nenhum cuidado adicional.

Se você quiser adicionar um tipo de objeto ao esquema do lado do servidor e ao modelo de objeto do cliente, poderá adicionar o tipo de objeto ao modelo de objeto e usar o Modo de desenvolvimento para permitir que o App Services lide com as atualizações do esquema do lado do servidor. Ou você pode adicionar manualmente o tipo de objeto ao modelo e ao esquema.

Adicionar um valor padrão em uma propriedade

Você pode adicionar um valor padrão na propriedade exigida de um objeto. Quando você insere um documento Atlas sem esta propriedade exigida na coleção, os clientes do Realm definem a propriedade para o valor padrão. No entanto, a mesma propriedade no documento Atlas permanece vazia até que um cliente faça alterações na propriedade ou atualize o documento diretamente no Atlas.

Para obter mais informações sobre como os valores-padrão são úteis ao modificar documentos existentes do Atlas , consulte a seção Adicione uma propriedade exigida.

Adicionar uma propriedade obrigatória

Você pode adicionar uma propriedade obrigatória ao modelo de objeto do cliente e usar o Modo de desenvolvimento para permitir que os App Services deduzam as atualizações do esquema do lado do servidor. Ou você pode adicionar manualmente a propriedade exigida tanto para o modelo de cliente como para o esquema Atlas. No entanto, você deve considerar tornar a propriedade opcional para evitar a necessidade de modificar documentos do Atlas existentes.

Adicionar uma propriedade opcional

Se você quiser adicionar uma propriedade opcional ao esquema do lado do servidor e ao modelo de objeto do cliente, poderá adicionar a propriedade opcional ao modelo de objeto e usar o Modo de desenvolvimento para permitir que App Services infira as atualizações do esquema do lado do servidor. Ou você pode adicionar manualmente a propriedade opcional ao modelo e ao esquema.

Remover um tipo de objeto

Você pode remover um objeto do modelo de objeto do cliente como uma alteração não significativa. Se você remover o objeto do esquema do lado do servidor, será uma alteração significativa. Por esse motivo, recomendamos que você remova o tipo de objeto apenas do modelo de objeto do lado do cliente e o deixe no lugar no esquema do lado do servidor.

Remover uma propriedade

Você pode remover uma propriedade opcional ou obrigatória do modelo de objeto do lado do cliente e deixá-la no lugar no esquema do lado do servidor. Esta é uma mudança não significativa no modelo de objeto.

Se você remover uma propriedade do esquema do lado do servidor, será uma alteração significativa. Por esse motivo, recomendamos que você remova a propriedade apenas do modelo de objeto do lado do cliente e a deixe no lugar no esquema do lado do servidor.

Para manter a compatibilidade com versões anteriores, a remoção de uma propriedade de um modelo de objeto do lado do cliente não exclui a propriedade do banco de dados. Em vez disso, os novos objetos mantêm a propriedade removida e o App Services define o valor como um valor vazio apropriado, como null para propriedades anuláveis, um 0 para valores inteiros ou uma string vazia para uma string de valores.

Alterar o nome de um objeto

Alterar o nome de um objeto tanto no esquema do lado do servidor quanto no modelo de objeto do lado do cliente é uma alteração significativa. No entanto, alguns SDKs oferecem uma API para mapear um novo nome de objeto para um nome existente no esquema. Isso permite renomear um objeto no cliente, mas não altera o nome do objeto no servidor. Dessa forma, você evita desencadear uma migração. O mapeamento de nome de objeto é suportado nos seguintes SDKs:

• Kotlin

• Java

• .NET

• Flutter

Se o mapeamento de nome não for uma opção, considere implementar uma estratégia de coleção de parceiros, na qual você mantém a coleção e o esquema existentes e cria uma nova coleção com o novo esquema.

Se você optar por alterar o nome do objeto em vez de usar a estratégia de coleção de parceiros, deverá encerrar a sincronização, atualizar manualmente o esquema e reativar a sincronização. Além disso, o aplicativo cliente deve executar uma redefinição do cliente para restaurar a sincronização. No modo de redefinição de cliente padrão, o cliente tenta recuperar quaisquer alterações não sincronizadas antes de redefinir.

Alterar o nome de uma propriedade

Alterar o nome de uma propriedade tanto no esquema do lado do servidor quanto no modelo de objeto do lado do cliente é uma alteração significativa. No entanto, alguns SDKs oferecem uma API para mapear um novo nome de propriedade para um nome existente no esquema. Isso permite que você renomeie uma propriedade no cliente, mas não altere o nome da propriedade no servidor. Dessa forma, você evita desencadear uma migração. O mapeamento de nome da propriedade é suportado nos seguintes SDKs:

• Flutter: Remapear uma propriedade

• Java: renomear um campo

• Kotlin: remapear uma propriedade

• .NET: renomear uma propriedade

• Node.js: remapear uma propriedade

• React Native: remapear uma propriedade

• Swift: remapear uma propriedade

Se o mapeamento de nome não for uma opção, considere implementar uma estratégia de coleção de parceiros, na qual você mantém a coleção e o esquema existentes e cria uma nova coleção com o novo esquema.

Se você optar por alterar o nome da propriedade em vez de usar a estratégia de coleta de parceiros, deverá encerrar a sincronização, atualizar manualmente o esquema e reativar a sincronização. Além disso, o aplicativo cliente deve executar uma redefinição do cliente para restaurar a sincronização. No modo de redefinição de cliente padrão, o cliente tenta recuperar quaisquer alterações não sincronizadas antes de redefinir.

Ao encerrar e reativar a sincronização, você também deve atualizar os documentos existentes do Atlas para habilitá-los à sincronização com seus aplicativos cliente. Sem esse cuidado adicional, esses documentos não são sincronizados e pode aparecer no cliente que os dados foram perdidos. Você pode resolver esse problema de duas maneiras:

• Altere o nome do campo antigo em cada documento para corresponder ao novo esquema

• Adicione um novo campo a cada documento com um nome que corresponda ao novo esquema e copie o valor do campo antigo nele

Depois de fazer essas alterações, os documentos apropriados sincronizam com o aplicativo do cliente.

Alterar um tipo de propriedade, mas manter o nome

Alterar o tipo de uma propriedade é uma mudança radical tanto no esquema do lado do servidor quanto no modelo de objeto do lado do cliente.

Em vez de alterar o tipo de uma propriedade, considere implementar a estratégia de coleção de parceiros, na qual você mantém a coleção e o esquema existentes e cria uma nova coleção com o novo esquema.

Se você optar por alterar o tipo da propriedade em vez de usar a estratégia de coleção de parceiros, deverá encerrar a sincronização, atualizar manualmente o esquema e reativar a sincronização. Além disso, o aplicativo do cliente deve executar uma redefinição do cliente para restaurar a sincronização. No modo de redefinição de cliente padrão, o cliente tenta recuperar quaisquer alterações não sincronizadas antes de redefinir.

Ao encerrar e reativar a sincronização, você também deve atualizar os documentos existentes do Atlas para habilitá-los à sincronização com seus aplicativos cliente. Sem esse cuidado adicional, esses documentos não são sincronizados e pode aparecer no cliente que os dados foram perdidos. Você pode resolver esse problema de duas maneiras:

• Altere o tipo de campo antigo em cada documento para corresponder ao novo esquema

• Adicione um novo campo a cada documento com o tipo que corresponde ao novo esquema e copie o valor do campo antigo para ele, transformando seu tipo

Depois de fazer essas alterações, os documentos apropriados devem sincronizam novamente com o aplicativo do cliente.

Alterar o status de uma propriedade entre opcional e obrigatório

Alterar o status de uma propriedade entre opcional e obrigatório é uma alteração de interrupção no esquema do lado do servidor e no modelo de objeto do lado do cliente.

Em vez de alterar o status de uma propriedade, considere implementar a estratégia de coleção de parceiros, na qual você mantém a coleção e o esquema existentes e cria uma nova coleção com o novo esquema.

Se você optar por alterar o status da propriedade em vez de usar a estratégia de collection de parceiros, deverá encerrar a sincronização, atualizar manualmente o esquema e reativar a sincronização. Além disso, o aplicativo do cliente deve executar uma reinício do cliente para restaurar a sincronização. No modo de reinício do cliente padrão, o cliente tenta recuperar quaisquer alterações não sincronizadas antes de redefinir.

Usando a estratégia de coleção de parceiros

Uma coleção de parceiros é uma coleção que contém os mesmos dados que a coleção original, mas que tem a nova definição de esquema em vigor. As coleções de parceiros usam gatilhos de banco de dados para garantir os fluxos de dados em ambas as direções, o que significa que, quando uma coleção é gravada, a outra também é gravada (com as modificações de dados necessárias para o novo esquema).

Para implementar uma alteração significativa no esquema usando a estratégia de coleção de parceiros, consulte Fazer alterações importantes no esquema.