Implantar e gerenciar esquemas e conectores do Data Connect

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

  • Um banco de dados 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 da verdade para seus dados, o esquema Data Connect é como seus conectores podem ver esses dados e os conectores declaram as APIs que seus clientes podem usar para acessar esses dados.

Ao implantar o serviço Data Connect com a CLI, você migrará seu esquema SQL e, em seguida, atualizará o esquema Data Connect e 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 esquema

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 de validação de esquema diferentes: restrito e compatível.

  • 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 exclua 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 as 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. Realização de 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 de 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 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 recursos selecionados

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

firebase deploy --only dataconnect:serviceId:schema

Você também pode 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 alterações interruptivas e destrutivas, talvez não seja possível recuperar totalmente os dados excluídos.

Migrar esquemas de banco de dados

Se você está prototipando rapidamente, testando esquemas e sabe que suas alterações de esquema são destrutivas, planeje o uso de ferramentas Data Connect para verificar as alterações 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ê será solicitado a aprovar as alterações.

firebase dataconnect:sql:migrate [serviceId]

Em ambientes interativos, as instruções de migração SQL e as 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.

É possível ajustar esse comportamento modificando 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"

Outra opção é definir o comportamento como STRICT para que todas as alterações 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 seus projetos do 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
    • Como tornar um campo anulável no esquema não anulável (ou seja, 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 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