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 oferece 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.

Comandos de configuração

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 seu diretório.

firebase init

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

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

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

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

Observação: o provisionamento de uma nova instância do Cloud SQL durante o fluxo pode levar até 15 minutos.

Observação: se você quiser usar chaves de criptografia gerenciadas pelo cliente (CMEK), vincule um banco de dados do Cloud SQL com CMEK.

Configuração do 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 controlado por script com exec.

Exportar e importar dados locais do PostgreSQL

Para oferecer suporte a prototipagem e testes locais, além de 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 snapshots 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 seu 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 seu 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 seu firebase.json no campo emulators.dataconnect.dataDir. Todas as mudanças de dados que você fizer serão salvas automaticamente aqui entre as execuções do emulador. Isso é útil durante testes e explorações 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, inicie o emulador usando o snapshot com a flag --import.

# 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>

Observação: um diretório de importação especificado durante a importação manual com a flag emulators:start --import da CLI tem precedência sobre o diretório de backup padrão configurado em firebase.json.

Observação: a importação e a exportação manuais são uma boa maneira de propagar testes com dados em CI/CD.

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 Exportar dados do emulador para exportar o conteúdo atual do banco de dados. O local de exportação padrão é o diretório exportedData na raiz do diretório do projeto.

Observação: para modificar esse local de exportação, antes de iniciar o emulador usando a extensão, clique no link Configurar emulador.

É 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 Configurar emulador e defina o Caminho de importação.

Comandos de gerenciamento de esquemas e conectores

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

Observação: é possível limitar o acesso a bancos de dados do PostgreSQL concedendo mais ou menos papéis elevados a usuários individuais. O comportamento dos seguintes comandos pode variar dependendo da função do usuário atual. Consulte Comandos de gerenciamento do Cloud SQL.

Para casos de uso e práticas recomendadas relacionadas a esses comandos, consulte o guia de gerenciamento de esquema e conector.

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 de 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 neste projeto, mas não implante outros recursos de produtos do Firebase.
	--only dataconnect:serviceId	Implanta o esquema e os conectores para o serviço especificado do Data Connect.
	--only dataconnect:serviceId:connectorId	Implanta um único conector para o serviço especificado do Data Connect.
	--only dataconnect:serviceId:schema	Implanta o esquema do serviço especificado do Data Connect.

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

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

Ao executar firebase deploy, a CLI faz uma comparação de esquema SQL antes de implantar as atualizações. Você também pode fazer a comparação e a atualização 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 correspondente do Cloud SQL. Ele imprime os comandos que seriam executados para migrar o banco de dados para seu novo esquema.

Comando	Descrição
firebase dataconnect:sql:diff	Flag/Parameter	Descrição
	serviceId	Especifique o serviço. Se omitido, vai imprimir o diff de todos os serviços em firebase.json.

dataconnect:sql:migrate

firebase dataconnect:sql:migrate

Esse comando aplica mudanças no esquema local a um 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 alterações. É 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 todos os comandos.

Em ambientes não interativos:

• Sem o --force, apenas mudanças não destrutivas são feitas. Se houver mudanças destrutivas, a CLI vai ser interrompida sem fazer alterações.
• Com --force, todas as mudanças são feitas. Se isso incluir mudanças destrutivas, elas serão impressas, e você vai receber uma solicitação para continuar, a menos que a flag --force seja fornecida.

Comando	Descrição
firebase dataconnect:sql:migrate	Flag	Descrição
	serviceId	Migra 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 do --only, é possível fornecer vários serviços separados por vírgulas.

Migrar um esquema no modo estrito ou compatível

As migrações de esquema Data Connect têm dois modos diferentes de validação de esquema: restrito 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 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 do banco de dados que não são usados pelo esquema do aplicativo permanecem inalterados.

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 esquema e conector.

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 pedir confirmação antes de executar mudanças estritas. Consulte a referência de configuração.

Gerenciar mudanças em conectores

Ao executar firebase deploy, a CLI inicia uma atualização dos conectores aplicáveis. A CLI analisa as mudanças em cada conector e emite um conjunto de mensagens de avaliação sobre as mudanças que podem causar comportamento inesperado (mensagens de nível de aviso) ou falhas (mensagens de nível de falha) em versões anteriores do código do cliente.

Observação :as listas a seguir não são completas. Consulte as mensagens de saída da CLI para avisos e erros aplicáveis ao seu conector.

Avaliação de impacto	Cenário
Nível de alerta (compatível com fio, pode mudar o comportamento)	Remover um campo anulável de uma consulta sem uma anotação @retired.
Mudança incompatível (fiação incompatível, pode quebrar 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. Remover uma variável anulável sem uma anotação @retired. Remover uma variável não nula com um valor padrão sem uma anotação @retired.
Nível de interrupção (fiação incompatível, vai interromper clientes)	Remover uma operação sem uma anotação @retired. Remover 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). Remover 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 no 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 os avisos serão registrados no terminal. É possível substituir com a flag --force.

Auditoria do código de autorização

O Data Connect ajuda você a auditar sua estratégia de autorização analisando o código do conector ao implantar 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 existente, 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 quando modifica as operações atuais para usar esses níveis de acesso.

Observação: os avisos de operação sem segurança são suprimidos se você anotar a diretiva @auth na operação com o argumento insecureReason.

Os avisos e solicitações sempre ocorrem para:

• PUBLIC

Além disso, avisos e solicitações aparecem 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 SDKs da Web, SDKs do Android e SDKs do iOS.

Comando	Descrição
firebase dataconnect:sdk:generate	Flag	Descrição
	--assistir	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 em stdout, o código gerado não será alterado, e o comando vai continuar sendo executado.
	--only connectorId:platform	Gere 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 permissões nas tabelas do banco de dados.

dataconnect:sql:setup

firebase dataconnect:sql:setup

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

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

Para bancos de dados legados (brownfield), talvez você tenha seu próprio fluxo de trabalho para migrar esquemas e queira manter a propriedade deles. Se esse for seu fluxo preferido, recuse o comando dataconnect:sql:setup para que o Data Connect não processe as migrações de SQL para você. Como resultado da recusa, o Data Connect só terá acesso de read e write às tabelas do banco de dados, mas as propriedades e migrações de esquema continuarão sendo de sua responsabilidade.

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

dataconnect:sql:grant

firebase dataconnect:sql:grant

Em alguns casos, talvez seja necessário acessar seu 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 mais detalhes sobre as funções concedidas, consulte Funções de usuário do PostgreSQL.

Observação: além de definir papéis do PostgreSQL com a CLI Firebase, você precisará atribuir o papel do IAM roles/cloudsql.client. Consulte o guia para gerenciar serviços e bancos de dados.

Papel	Função SQL	Permissões	Uso	Grantable
leitor	firebasereader_<db_name>_<schema_name>	Acesso somente leitura ao banco de dados. Pode realizar operações SELECT em todas as tabelas no esquema especificado.	Ideal para usuários ou serviços que precisam recuperar dados, mas não modificá-los.	Sim
escritor	firebasewriter_<db_name>_<schema_name>	Acesso de leitura e gravação ao banco de dados. Pode realizar 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 no 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, ele pode criar e excluir esquemas, instalar extensões e realizar qualquer outra tarefa administrativa. Acessado na CLI fazendo login como "firebasesuperuser".	Necessário para instalar extensões, criar o esquema inicial e conceder qualquer uma das funções SQL concedíveis a outros usuários. Se um usuário sem privilégios de administrador precisar de privilégios de superusuário, a migração vai falhar e pedir que ele solicite ao administrador do banco de dados (ou seja, um usuário com roles/cloudsql.admin) para executar os comandos SQL privilegiados.	Concedida a usuários com roles/cloudsql.admin e não pode ser concedida diretamente pela CLI Firebase.

Observação: esses papéis do SQL são diferentes dos papéis do IAM do Cloud SQL. Os papéis do IAM controlam quem pode acessar um banco de dados. As funções do SQL controlam quais operações você pode realizar com esse acesso e quais tabelas podem ser modificadas.

Comando	Descrição
firebase dataconnect:sql:grant	Flag/Parameter	Descrição
	-R, --role role	A função do SQL a ser concedida, uma destas opções: proprietário, gravador ou leitor.
	-E, --email email_address	E-mail de um usuário ou conta de serviço a que você quer conceder o papel.

Opções globais

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

• --json muda 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 não TTY.