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

O esquema SQL é a fonte de verdade dos seus dados, o Data Connect esquema é como os conectores podem visualizar 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ê migra o esquema SQL, atualiza o esquema Data Connect e, em seguida, atualiza cada um dos conectores.

Conceitos importantes de implantação

Para entender totalmente 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. Data Connect ajuda a migrar os esquemas durante a implantação, seja trabalhando com um novo banco de dados ou precisando adaptar um banco de dados atual de forma não destrutiva.

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

  • A validação do 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 Connectserã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 ele possa ser atualizado. Todas as outras mudanças 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 do banco de dados que não são usados pelo esquema do aplicativo permanecem inalterados. Portanto, após a implantação, o banco de dados poderá conter elementos não utilizados:

    • Esquemas
    • Tabelas
    • Colunas

Implantações de conector

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

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

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 do conector que podem alterar o comportamento do cliente (as mensagens são de nível de aviso) ou podem ou vão interromper (as mensagens são de nível de interrupção) versões anteriores do código do cliente.

Exemplo:

  • As mudanças de 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 de conector que podem ou vão interromper os clientes incluem a mudança 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 em o 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 Firebase.

Um fluxo de implantação recomendado envolve:

  1. Listar esquemas e conectores implantados no momento 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 Data Connect com firebase dataconnect:sql:diff.
    2. Se necessário, execute a migração do esquema SQL com dataconnect:sql:migrate.
  3. Realizar implantações de esquema e conexão executando firebase deploy, apenas para o esquema, apenas para os conectores ou combinações de recursos.

Implantar e gerenciar Data Connect recursos

É 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 Data Connect implantações de outros produtos no projeto.

Implantação normal

firebase deploy --only dataconnect

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

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

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

Implantação da flag --force

firebase deploy --only dataconnect --force

Se as validações do conector ou do esquema SQL não forem relevantes, você poderá executar 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 para 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 realizar uma reversão manual, faça o check-out de uma versão anterior do código e implante-o. Se a implantação original incluiu mudanças interruptivas destrutivas, talvez não seja possível recuperar totalmente os dados excluídos.

Migrar esquemas de banco de dados

Se você estiver prototipando rapidamente, experimentando esquemas e souber que as mudanças de 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 de esquema SQL

É possível verificar as mudanças:

firebase dataconnect:sql:diff

É possível transmitir uma lista de serviços separados 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 imprimir os comandos SQL que seriam executados para corrigir essa diferença.

Aplique as alterações

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

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 exigidas pelo esquema do aplicativo e, em seguida, solicitar 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

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

Gerenciar atualizações de conector com a CLI

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

Como esperado, 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 o 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 interruptivas. É possível substituir e implantar definindo 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 Data Connect projetos.

Minimizar mudanças interruptivas

  • O Firebase recomenda manter os arquivos de esquema e conector Data Connect no controle de origem.
  • Evite mudanças interruptivas sempre que possível. Alguns exemplos comuns de mudanças interruptivas incluem:
    • Remover um campo do esquema
    • 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 os 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.

Use 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 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 houver 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 que você execute 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 dataconnect.yaml.

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

  • DROP SCHEMA, DROP TABLE e DROP COLUMN são considerados instruções 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 contiver 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