Referência de comandos da CLI do Firebase para o Data Connect

A CLI Firebase é uma ferramenta que permite gerenciar e configurar produtos e serviços do Firebase na linha de comando.

A CLI fornece comandos que podem ser usados para realizar várias tarefas do Data Connect, como criar um novo projeto do Data Connect, inicializar um diretório de trabalho local correspondente, configurar o emulador do Data Connect, listar recursos do Data Connect, gerar SDKs de cliente e muito mais.

Configurar comandos

Adicionar Data Connect a um projeto do Firebase

firebase init

Use firebase init para configurar uma nova configuração de projeto local. Esse fluxo de trabalho cria ou atualiza arquivos de configuração do Firebase no diretório.

firebase init

O fluxo firebase init orienta você na configuração de um serviço e banco de dados, e, opcionalmente, na instalação do emulador Data Connect e na configuração de SDKs gerados.

Configuração do serviço e do banco de dados

Se você selecionar dataconnect para a configuração do produto, a CLI vai solicitar um novo nome e local do serviço e se você quer vincular uma instância do Cloud SQL para PostgreSQL ou criar uma nova.

Se uma instância existente estiver vinculada, a CLI vai verificar se há configurações compatíveis, como a autenticação do IAM e endereços IP públicos.

Configuração de Local Emulator Suite

O fluxo da CLI oferece a configuração de emuladores, incluindo o emulador Data Connect.

Comandos do emulador Data Connect

Iniciar o emulador Data Connect

emulators:start/exec

firebase emulators:start/exec

Use a versão Local Emulator Suite do emulador Data Connect no modo interativo com start ou no modo não interativo com exec.

Exportar e importar dados locais do PostgreSQL

Para oferecer suporte a prototipagem e testes locais e integração contínua, é possível exportar os dados armazenados em uma instância de banco de dados local e importá-los entre iterações de desenvolvimento e execuções de teste.

As exportações são armazenadas como instantâneos do seu banco de dados PostgreSQL local.

O Data Connect oferece três abordagens para exportação/importação:

  • Exportação/importação automática configurada no firebase.json para fornecer backups de snapshots no encerramento e na inicialização do emulador
  • Exportação/importação manual usando a CLI
  • Exportação/importação manual usando a interface da extensão do VS Code

Exportação e importação automáticas configuradas no firebase.json

Para fazer backup de dados entre sessões de desenvolvimento, especifique um local de backup automático durante a sequência firebase init. Esse local é armazenado no firebase.json no campo emulators.dataconnect.dataDir. Todas as alterações de dados feitas são salvas automaticamente aqui entre as execuções do emulador. Por isso, ele é útil durante testes e análises locais.

Exportação manual: emulators:export e emulators:start/exec --import

Enquanto o emulador Data Connect estiver em execução, em um terminal separado, execute o comando firebase emulators:export para salvar um snapshot dos seus dados. Em seguida, você pode iniciar o emulador usando o flag --import para esse snapshot.

# Export data from local emulator from a separate terminal
firebase emulators:export --only dataconnect <export_directory>

# Import data from local directory, here using emulators:exec
firebase emulators:exec ./<your-test-script>.sh --only dataconnect --import <import_directory>

Exportação/importação manual: extensão do VS Code

Na interface da extensão do VS Code, enquanto o emulador está em execução, use o botão Export emulator data para exportar os dados do banco de dados atual. O local de exportação padrão é o diretório exportedData na raiz do diretório do projeto.

É possível importar esses dados usando a CLI, conforme descrito na seção anterior. Você também pode importar esses dados antes de iniciar o emulador pelo VS Code. Para isso, clique no link Configure emulator e defina Import Path.

Comandos de gerenciamento de esquemas e conectores

Esta seção contém informações de referência da CLI para comandos usados para gerenciar esquemas e conectores.

Para saber como usar casos e práticas recomendadas relacionadas a esses comandos, consulte o guia de gerenciamento de esquemas e conectores.

Implantar esquemas e conectores

deploy

firebase deploy

Esse comando implanta recursos para serviços do Data Connect indexados em firebase.json. Uma migração de esquema e uma atualização do conector são realizadas, se necessário.

Comando Descrição

firebase deploy

Flag Descrição

–-only dataconnect

Implante esquemas e conectores para todos os serviços do Data Connect para este projeto, mas não implante outros recursos de produtos do Firebase.

–-only dataconnect:serviceId

Implante o esquema e os conectores para o serviço do Data Connect especificado.

–-only dataconnect:serviceId:connectorId

Implante um único conector para o serviço do Data Connect especificado.

–-only dataconnect:serviceId:schema

Implante o esquema do serviço do Data Connect especificado.

Com as flags –-only, é possível transmitir valores separados por vírgulas para implantar qualquer subconjunto de recursos.

firebase deploy --only dataconnect:service1:schema,dataconnect:service2

Listar serviços, esquemas e conectores do Data Connect

dataconnect:services:list

firebase dataconnect:services:list

Esse comando mostra informações básicas sobre os serviços, esquemas e conectores implantados em um projeto.

Comparar e migrar esquemas SQL

Quando você executa firebase deploy, a CLI realiza uma comparação de esquema SQL antes de implantar atualizações. Também é possível realizar a comparação e atualizar diretamente com um conjunto de comandos dataconnect:sql.

dataconnect:sql:diff

firebase dataconnect:sql:diff

Esse comando compara o esquema local de um serviço com o esquema atual do banco de dados do Cloud SQL correspondente. Ele mostra os comandos que seriam executados para migrar o banco de dados para o novo esquema.

Comando Descrição

firebase dataconnect:sql:diff

Flag/parâmetro Descrição

serviceId

Especifique o serviço. Se omitido, mostra a diferença de todos os serviços no firebase.json.

dataconnect:sql:migrate

firebase dataconnect:sql:migrate

Esse comando aplica mudanças de esquema local ao banco de dados do Cloud SQL de um serviço.

Ao configurar um novo projeto Data Connect local com o arquivo dataconnect.yaml padrão, o comportamento do comando dataconnect:sql:migrate é solicitar as mudanças necessárias e, em seguida, as opcionais antes de executar as mudanças. É possível modificar esse comportamento para sempre incluir ou ignorar mudanças opcionais atualizando a configuração dataconnect.yaml, conforme discutido em migrar um esquema no modo estrito ou compatível.

Em ambientes interativos, a CLI mostra cada instrução SQL de migração (e se ela é destrutiva) e solicita as mudanças que você quer aplicar. Transmitir a flag --force é equivalente a aceitar todas as solicitações.

Em ambientes não interativos:

  • Sem --force, apenas mudanças não destrutivas são feitas. Se houver mudanças destrutivas, a CLI será abortada sem que nenhuma mudança seja feita.
  • Com --force, todas as mudanças são feitas. Se isso incluir alterações destrutivas, elas serão impressas e você será solicitado a continuar, a menos que a flag --force seja fornecida.
Comando Descrição

firebase dataconnect:sql:migrate

Flag Descrição

serviceId

Migrar o banco de dados para o serviço especificado. O serviceId é inferido se o projeto tiver apenas um serviço.

–-force

Aceitar automaticamente as solicitações.

Assim como com outras flags --only, é possível fornecer vários serviços separados por vírgulas.

Migrar um esquema no modo restrito ou compatível

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 estrito exige que o esquema do banco de dados corresponda exatamente ao esquema do aplicativo antes que o esquema do aplicativo possa ser implantado. A validação do modo compatível exige que o esquema do banco de dados seja compatível com o esquema do aplicativo. Isso significa que os elementos no banco de dados que não são usados pelo esquema do aplicativo não são modificados.

Esses modos de validação de esquema e as práticas recomendadas para migração de esquema são abordados no guia de gerenciamento de esquemas e conectores.

O modo de validação é definido usando a chave schemaValidation no arquivo dataconnect.yaml. Se schemaValidation não for especificado, a CLI vai aplicar mudanças compatíveis e solicitar que você as execute antes de fazer mudanças rígidas. Consulte a referência de configuração.

Gerenciar mudanças nos conectores

Quando você executa firebase deploy, a CLI inicia uma atualização dos conectores aplicáveis. O CLI analisa as mudanças em cada conector e emite um conjunto de mensagens de avaliação em relação às mudanças do conector que podem causar um comportamento inesperado (as mensagens estão no nível de aviso) ou falhas (as mensagens estão no nível de falha) em versões anteriores do código do cliente.

Avaliação de impacto Cenário
Nível de alerta (compatível com o fio, pode mudar o comportamento)
  • Remova um campo nullable de uma consulta sem uma anotação @retired.
Nível de ruptura (fio incompatível, pode romper clientes)
  • Mudar uma variável anulável para não nula sem um valor padrão.
  • Mudar o tipo de dados de um campo para algo compatível com JSON (por exemplo, Int para Float).
  • Mudar uma coluna não nula para anulável.
  • Remoção de uma variável anulável sem uma anotação @retired.
  • Remoção de uma variável não nula com um valor padrão sem uma anotação @retired.
Nível de interrupção (incompatível com o fio, interromperá os clientes)
  • Remoção de uma operação sem uma anotação @retired.
  • Remova um campo não nulo de uma consulta sem uma anotação @retired.
  • Adicionar uma variável não nula sem um valor padrão.
  • Mudar o tipo de dados de um campo para algo incompatível (por exemplo, String para Int).
  • Remoção de uma variável não nula sem um valor padrão e sem uma anotação @retired.

Em ambientes interativos, a CLI mostra cada avaliação do conector e solicita as mudanças que você quer aplicar. Transmitir a flag --force é equivalente a aceitar todas as avaliações.

Em ambientes não interativos:

  • Se apenas avaliações de nível de aviso (possíveis mudanças de comportamento) ocorrerem, todos os conectores serão implantados e os avisos serão registrados no terminal.
  • Se ocorrerem avaliações de nível de interrupção, nenhum conector será implantado e avisos serão registrados no terminal. É possível modificar com a sinalização --force.

Código de autorização de auditoria

O Data Connect ajuda a auditar sua estratégia de autorização analisando o código do conector quando você implanta no servidor usando firebase deploy da CLI Firebase. Use essa auditoria para revisar sua base de código.

Ao implantar os conectores, a CLI vai gerar avaliações para o código de operação atual, modificado e novo no conector.

Para operações modificadas e novas, a CLI emite avisos e solicita confirmação quando você usa determinados níveis de acesso nas novas operações ou modifica operações existentes para usar esses níveis de acesso.

Os avisos e solicitações sempre ocorrem para:

  • PUBLIC

Além disso, avisos e solicitações ocorrem nos seguintes níveis de acesso quando você não os aumenta com filtros usando auth.uid:

  • USER
  • USER_ANON
  • USER_EMAIL_VERIFIED

Para mais informações sobre autorização, consulte o guia de autorização e atestado.

Comandos do SDK

Gerar SDKs

dataconnect:sdk:generate

firebase dataconnect:sdk:generate

Esse comando gera os SDKs tipados declarados em connector.yaml.

Consulte também os guias para trabalhar com os SDKs da Web, os SDKs do Android e os SDKs do iOS.

Comando Descrição

firebase dataconnect:sdk:generate

Flag Descrição

--watch

Mantém o processo em execução e gera novos SDKs sempre que você salva mudanças nos arquivos GQL do esquema e do conector.

Se a geração falhar, os erros serão impressos no stdout, o código gerado não será alterado e o comando continuará sendo executado.

–-only connectorId:platform

Gerar SDKs apenas para uma plataforma e um conector.

Com as flags –only, é possível transmitir valores separados por vírgulas.

firebase dataconnect:sdk:generate –-only connector1, connector1:kotlin

Comandos de gerenciamento do Cloud SQL

Conceder papéis do SQL para o Cloud SQL

O Data Connect opera na sua própria instância do PostgreSQL hospedada no Cloud SQL. Os comandos de função SQL ajudam a gerenciar as permissões nas tabelas do banco de dados.

dataconnect:sql:setup

firebase dataconnect:sql:setup

Esse comando configura as permissões globais iniciais para tabelas no seu banco de dados.

O fluxo de provisionamento e gerenciamento de banco de dados padrão pressupõe que seu projeto use um novo banco de dados (greenfield). Quando você invoca firebase deploy, Data Connect mostra as mudanças de esquema do banco de dados a serem feitas e executa todas as migrações após a aprovação. Se esse for seu fluxo preferido, dataconnect:sql:setup vai solicitar que você conceda permissões, incluindo as de propriedade do esquema superuser.

Para bancos de dados existentes (brownfield), você pode ter seu próprio fluxo de trabalho para migrar esquemas e manter a propriedade do esquema. Se esse for o fluxo de sua preferência, rejeite a solicitação dataconnect:sql:setup para que o Data Connect processe as migrações do SQL. Como resultado da recusa, o Data Connect só vai ter acesso read e write às tabelas do banco de dados, mas as migrações e as propriedades do esquema vão continuar sendo sua responsabilidade.

Para mais discussões e casos de uso, consulte Gerenciar serviços e bancos de dados.

dataconnect:sql:grant

firebase dataconnect:sql:grant

Em alguns casos, convém acessar o banco de dados diretamente para consultar ou atualizar os dados gerados pelos seus apps Data Connect. Para fazer isso, conceda uma das funções definidas nesta seção ao usuário ou à conta de serviço necessária.

Para saber mais sobre os papéis concedidos, consulte Papéis de usuário do PostgreSQL.

Papel Função SQL Permissões Uso Concedível
leitor firebasereader_<db_name>_<schema_name> Acesso somente leitura ao banco de dados.

Pode realizar operações SELECT em todas as tabelas do esquema especificado.		 Ideal para usuários ou serviços que exigem a recuperação de dados, mas não a modificação. Sim
escritor firebasewriter_<db_name>_<schema_name> Acesso de leitura e gravação ao banco de dados.

Pode executar operações SELECT, INSERT, UPDATE, DELETE e TRUNCATE em todas as tabelas do esquema.		 Adequado para usuários ou serviços que precisam modificar dados no banco de dados. Sim
proprietário firebaseowner_<db_name>_<schema_name> Proprietário do esquema.

Tem todos os privilégios em todas as tabelas e sequências do esquema.		 Esse papel, em combinação com o papel roles/cloudsql.client do IAM, concede permissão para realizar a migração no banco de dados.

Por exemplo, ao chamar firebase dataconnect:sql:migrate.		 Sim
superusuário cloudsqlsuperuser Função de superusuário integrada com privilégios totais no banco de dados.

Além das permissões de proprietário, ela pode criar esquemas, excluir esquemas, instalar extensões e realizar outras tarefas administrativas.

Acessado na CLI fazendo login como "firebasesuperuser".		 É necessário para instalar extensões, criar o esquema inicial e conceder a qualquer uma das funções SQL concedíveis a outros usuários.

Se um usuário que não é administrador precisar de privilégios de superusuário, a migração vai falhar e pedir que o usuário solicite ao administrador do banco de dados (ou seja, um usuário com roles/cloudsql.admin) que execute os comandos SQL privilegiados.		 Concedida a usuários com roles/cloudsql.admin e não pode ser concedida diretamente pela CLI Firebase
Comando Descrição

firebase dataconnect:sql:grant

Flag/parâmetro Descrição

-R, --role role

O papel do SQL a ser concedido: proprietário, gravador ou leitor.

-E, --email email_address

E-mail de um usuário ou de uma conta de serviço para conceder o papel.

Opções globais

As opções globais a seguir se aplicam a todos os comandos:

  • --json alterna a saída da CLI para JSON para análise por outras ferramentas.
  • --noninteractive e --interactive substituem, conforme necessário, a detecção automática de ambientes que não são TTY.