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 subjacente com um esquema SQL próprio
  • um esquema de aplicativo Data Connect (declarado nos arquivos .gql)
  • vários conectores (declarados nos arquivos .gql e configurados nos arquivos connector.yaml).

O esquema SQL é a fonte de verdade dos 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á o esquema SQL, atualizará o esquema Data Connect e atualizará cada um dos seus conectores.

Conceitos importantes de implantação

Para entender totalmente a implantação, é importante observar os conceitos principais 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 você a migrar seus esquemas durante a implantação, seja trabalhando com um novo banco de dados ou precisando adaptar um banco de dados atual sem destruição.

As migrações de esquema Data Connect têm dois modos diferentes de validação de esquema: restrito e compatível.

  • A validação no modo estrito exige que o esquema do banco de dados corresponda exatamente ao esquema do aplicativo antes que ele 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 no modo compatível exige que o esquema do banco de dados seja compatível com o esquema do aplicativo antes que ele possa ser atualizado. Todas as mudanças adicionais que descartam esquemas, tabelas ou colunas são opcionais.

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

    • Esquemas
    • Tabelas
    • Colunas

Implantações de conectores

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 prejudicar os usuários atuais.

O Data Connect integra a análise de mudanças incompatíveis nas atualizações do conector à CLI Firebase.

A CLI analisa as mudanças em cada conector em relação ao seu esquema e emite um conjunto de mensagens de avaliação sobre as mudanças no conector que podem alterar o comportamento do cliente (mensagens de nível de aviso) ou podem ou vão interromper (mensagens de nível de interrupção) versões anteriores do código do cliente.

Exemplo:

  • As mudanças no conector que podem alterar o comportamento do cliente incluem a remoção de um campo anulável de uma consulta sem uma anotação de esquema @retired.
  • As mudanças no conector que podem ou vão prejudicar os clientes incluem a alteração de uma variável de operação anulável para não anulável sem um valor padrão ou a mudança do tipo de dados de um campo para algo incompatível (por exemplo, String para Int).

Uma lista mais extensa de cenários de nível de aviso e de interrupção é fornecida no guia de referência da CLI.

Siga 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 no momento com firebase dataconnect:services:list.
  2. Gerenciar atualizações de esquema.
    1. Verifique se há diferenças entre o esquema SQL do banco de dados do Cloud SQL e o esquema local do Data Connect com firebase dataconnect:sql:diff.
    2. Se necessário, faça a migração do esquema SQL com dataconnect:sql:migrate.
  3. Realizar implantações de esquema e conexão executando firebase deploy, apenas para seu esquema, apenas para seus conectores ou combinações de recursos.

Implantar e gerenciar recursos do Data Connect

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

firebase dataconnect:services:list

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

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

Implantação normal

firebase deploy --only dataconnect

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

Ele valida se o novo esquema não interrompe nenhum conector atual. Siga as práticas recomendadas ao fazer mudanças incompatíveis.

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

Implantação de flags --force

firebase deploy --only dataconnect --force

Se você não se importa com as validações de conector ou esquema SQL, execute o comando novamente com --force para ignorá-las.

A implantação --force ainda verifica se o esquema SQL corresponde ao esquema Data Connect, avisa 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 mudanças de esquema em um serviço específico:

firebase deploy --only dataconnect:serviceId:schema

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

firebase deploy --only dataconnect:serviceId:connectorId

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

firebase deploy --only dataconnect:serviceId

Reverter uma implantação

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

Migrar esquemas de banco de dados

Se você estiver prototipando rapidamente, testando esquemas e souber que as mudanças no esquema são destrutivas, planeje usar as ferramentas Data Connect para verificar as mudanças e supervisionar como as atualizações são realizadas.

Diferenciar mudanças no esquema SQL

Você pode 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 correspondente do Cloud SQL. Se houver uma diferença, ele vai imprimir os comandos SQL que seriam executados para corrigir isso.

Aplique as alterações

Quando você estiver satisfeito e pronto para implantar as mudanças na instância do Cloud SQL do esquema, execute 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, as instruções de migração SQL e os comandos de ação são mostrados.

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 necessárias no esquema do banco de dados pelo esquema do aplicativo e pedir que você aprove operações opcionais que descartam 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"

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.

Atualizar conectores

Ao executar firebase deploy, a CLI inicia uma atualização dos conectores aplicáveis e emite mensagens de avaliação aplicáveis nos níveis de aviso (pode afetar o comportamento do cliente) e de interrupção (possivelmente ou certamente interrompendo).

Gerenciar atualizações de conector com a CLI

A CLI tem um comportamento um pouco diferente no modo interativo e no modo não interativo.

Como você já deve esperar, no modo interativo, a CLI solicita que você aceite todas as mensagens. É possível substituir e forçar a implantação do conector com a flag --force.

# Prompts for acceptance for any warning-level or breaking-level changes prior
# to deploying connectors.
firebase deploy --only dataconnect
# Will deploy connectors without prompting.
firebase deploy --only dataconnect --force

No modo não interativo, a CLI vai implantar seu conector desde que não haja avaliações de nível de interrupção. Caso contrário, o script será encerrado com um registro de mudanças interrompidas. Para substituir e implantar, defina a flag --force.

# Will deploy connectors with warning-level changes. If any breaking changes
# are present, the deploy will fail and output any breaking changes
firebase deploy --only dataconnect --non-interactive
# Will deploy the connectors from the previous step, if the same issues are present.
firebase deploy --only dataconnect --non-interactive --force

Para mais informações, consulte o guia de referência da CLI.

Práticas recomendadas para gerenciar esquemas e conectores

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

Minimizar mudanças significativas

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

Use o modo estrito ao trabalhar com novos bancos de dados

Se você estiver usando o 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 permaneça exatamente alinhado ao 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 mudanças em um banco de dados que contém dados de produção, recomendamos executar as migrações de esquema no modo compatível para garantir que os dados atuais não sejam descartados. É possível especificar schemaValidation: "COMPATIBLE" no seu dataconnect.yaml.

No modo de compatibilidade, apenas as mudanças necessárias na migração de esquema são aplicadas ao seu 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 está 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