Implantar e gerenciar esquemas e conectores do Data Connect

Um serviço Firebase Data Connect tem três componentes principais:

  • Um banco de dados do PostgreSQL com o próprio esquema SQL
  • um esquema de aplicativo Data Connect (declarado nos arquivos .gql)
  • vários conectores (declarados nos arquivos .gql).

O esquema SQL é a fonte de verdade dos seus dados. O esquema Data Connect é como os conectores podem acessar esses dados, e os conectores declaram as APIs que os clientes podem usar para acessar esses dados.

Ao implantar o serviço Data Connect com a CLI, você vai migrar o esquema SQL, atualizar o esquema Data Connect e, em seguida, atualizar cada um dos conectores.

Conceitos importantes de implantação

Para entender completamente a implantação, é importante observar os principais conceitos sobre esquemas e conectores.

Implantações de esquemas

A implantação de um esquema Data Connect afeta o esquema SQL do seu banco de dados do Cloud SQL. O Data Connect ajuda a migrar seus esquemas durante a implantação, seja para trabalhar com um novo banco de dados ou para adaptar um banco de dados existente sem causar danos.

As migrações de esquema Data Connect têm dois modos diferentes de validação de esquema: strict e compatible.

  • A validação do modo restrito exige que o esquema do banco de dados exatamente corresponda ao esquema do aplicativo antes que o esquema do aplicativo possa ser atualizado. Todas as tabelas ou colunas que não forem usadas no esquema Data Connect serão excluídas do banco de dados.

  • A validação do modo compatível exige que o esquema do banco de dados seja compatível com o esquema do aplicativo antes que o esquema do aplicativo possa ser atualizado. Qualquer outra mudança que excluir esquemas, tabelas ou colunas é opcional.

    Compatível significa que as migrações de esquema afetam apenas as tabelas e colunas referenciadas no esquema do aplicativo. Os elementos no banco de dados que não são usados pelo esquema do aplicativo não são modificados. Portanto, após a implantação, o banco de dados pode conter os seguintes itens não utilizados:

    • Esquemas
    • Tabelas
    • Colunas

Implantações de conectores

As consultas e mutações Data Connect não são enviadas pelo código do cliente e executadas no servidor. Em vez disso, quando implantadas, essas operações Data Connect são armazenadas no servidor, como Cloud Functions. Isso significa que a implantação pode interromper os usuários atuais.

Seguir o fluxo de trabalho de implantação

É possível trabalhar em um projeto Data Connect em um diretório de projeto local e no console do Firebase.

Um fluxo de implantação recomendado envolve:

  1. Listar os esquemas e conectores implantados atualmente com firebase dataconnect:services:list.
  2. Gerenciar atualizações de esquema.
    1. Verifique as diferenças de esquema SQL entre o banco de dados do Cloud SQL e o esquema local do Data Connect com firebase dataconnect:sql:diff.
    2. Se necessário, realize a migração do esquema SQL com dataconnect:sql:migrate.
  3. Realize implantações de esquema e conexão executando firebase deploy, para apenas o esquema, apenas os conectores ou combinações de recursos.

Implantar e gerenciar recursos do Data Connect

É recomendável verificar os recursos de produção antes de realizar implantações.

firebase dataconnect:services:list

Ao trabalhar em um diretório de projeto local, geralmente você usa o comando firebase deploy para implantar o esquema e os conectores na produção, com feedback interativo.

Usando qualquer comando deploy, a flag --only dataconnect permite separar as implantações de Data Connect de outros produtos no seu projeto.

Implantação normal

firebase deploy --only dataconnect

Nessa implantação normal, a CLI Firebase tenta implantar o esquema e os conectores.

Ele valida que o novo esquema não quebra nenhum conector existente. Siga as práticas recomendadas ao fazer mudanças importantes.

Ele também verifica se o esquema SQL já foi migrado antes de atualizar o esquema Data Connect. Caso contrário, o processo vai solicitar automaticamente as etapas necessárias para migrar os esquemas.

Implantação da flag --force

firebase deploy --only dataconnect --force

Se nem o conector nem as validações do esquema SQL forem um problema, você poderá executar o comando novamente com --force para ignorá-las.

O deployment de --force ainda verifica se o esquema SQL corresponde ao esquema Data Connect, alerta sobre incompatibilidade e solicita.

Implantar os recursos selecionados

Para implantar com um controle mais granular, use a flag --only com o argumento serviceId. Para implantar apenas as mudanças de esquema de um serviço específico:

firebase deploy --only dataconnect:serviceId:schema

Também é possível implantar todos os recursos para um conector e serviço especificados.

firebase deploy --only dataconnect:serviceId:connectorId

Por fim, é possível implantar o esquema e todos os conectores para um único serviço.

firebase deploy --only dataconnect:serviceId

Reverter uma implantação

Para fazer um rollback manual, confira uma versão anterior do código e implante-a. Se a implantação original incluiu mudanças prejudiciais, talvez não seja possível recuperar totalmente os dados excluídos.

Migrar esquemas de banco de dados

Se você estiver criando protótipos rapidamente, experimentando esquemas e sabendo que as mudanças no esquema são destrutivas, planeje usar ferramentas Data Connect para verificar as mudanças e supervisionar como as atualizações são realizadas.

Comparar mudanças de esquema SQL

É possível verificar as mudanças:

firebase dataconnect:sql:diff

É possível transmitir uma lista de serviços separada por vírgulas.

O comando compara o esquema local de um serviço com o esquema atual do banco de dados do Cloud SQL correspondente. Se houver uma diferença, ele vai mostrar os comandos SQL que seriam executados para corrigir essa diferença.

Aplique as alterações

Quando você estiver satisfeito e pronto para implantar as alterações na instância do esquema do Cloud SQL, emita o comando firebase dataconnect:sql:migrate. Você vai receber uma solicitação para aprovar as mudanças.

firebase dataconnect:sql:migrate [serviceId]

Em ambientes interativos, instruções de migração SQL e solicitações de ação são exibidas.

Migrar no modo estrito ou compatível

Em um projeto novo, o modo de validação de esquema padrão é aplicado. O comportamento do comando migrate é aplicar todas as mudanças de esquema de banco de dados necessárias ao esquema do aplicativo e solicitar que você aprove operações opcionais que excluem esquemas, tabelas ou colunas para forçar o esquema do banco de dados a corresponder exatamente ao esquema do aplicativo.

Para ajustar esse comportamento, modifique o arquivo dataconnect.yaml. Remova o comentário da chave schemaValidation e declare COMPATIBLE para que apenas as mudanças necessárias sejam aplicadas nas migrações.

schemaValidation: "COMPATIBLE"

Ou defina o comportamento como STRICT para que todas as mudanças de esquema sejam aplicadas e o esquema do banco de dados seja forçado a corresponder ao esquema do aplicativo.

schemaValidation: "STRICT"

Consulte a referência da CLI Data Connect para mais informações.

Práticas recomendadas para gerenciar esquemas e conectores

O Firebase recomenda algumas práticas a serem seguidas nos projetos Data Connect.

Minimizar mudanças importantes

  • O Firebase recomenda manter os arquivos de conector e esquema Data Connect no controle de origem.
  • Evite mudanças drásticas sempre que possível. Alguns exemplos comuns de mudanças importantes incluem:
    • Como remover um campo do esquema
    • Tornar um campo anulável no esquema não anulável (por exemplo, Int -> Int!)
    • Renomear um campo no esquema.
  • Se você precisar remover um campo do esquema, considere dividi-lo em algumas implantações para minimizar o impacto:
    • Primeiro, remova todas as referências ao campo nos conectores e implante a mudança.
    • Em seguida, atualize seus apps para usar os SDKs recém-gerados.
    • Por fim, remova o campo no arquivo .gql do esquema, migre o esquema SQL e implante mais uma vez.

Usar o modo estrito ao trabalhar com novos bancos de dados

Se você estiver usando Data Connect com um novo banco de dados e estiver desenvolvendo ativamente o esquema do aplicativo, e quiser garantir que o esquema do banco de dados continue exatamente de acordo com o esquema do aplicativo, especifique schemaValidation: "STRICT" no dataconnect.yaml.

Isso garante que as mudanças opcionais também sejam aplicadas.

Use o modo compatível quando tiver dados de produção no banco de dados

Se você estiver fazendo alterações em um banco de dados que contém dados de produção, recomendamos que execute as migrações de esquema no modo compatível para garantir que os dados atuais não sejam excluídos. Você pode especificar schemaValidation: "COMPATIBLE" no dataconnect.yaml.

No modo compatível, apenas as mudanças de migração de esquema necessárias são aplicadas ao banco de dados.

  • DROP SCHEMA, DROP TABLE e DROP COLUMN são considerados comandos opcionais e não serão gerados para seu plano, mesmo que o esquema do banco de dados contenha esquemas, tabelas ou colunas não definidos no esquema do aplicativo.
  • Se a tabela do banco de dados tiver uma coluna não nula que não esteja incluída no esquema do aplicativo, a restrição NOT NULL será removida para que os dados ainda possam ser adicionados à tabela com os conectores definidos.

A seguir