Começar a usar o Firebase Data Connect

Neste guia de início rápido, você aprenderá a:

• Adicionar o Firebase Data Connect ao seu projeto do Firebase
• Configure um ambiente de desenvolvimento, incluindo uma extensão do Visual Studio Code para trabalhar com uma instância de produção.
• Depois, você vai aprender a:
  • Crie um esquema usando um exemplo de app de e-mails.
  • Defina consultas e mutações para o esquema.
  • Use SDKs gerados automaticamente para chamar essas consultas e mutações dos seus clientes.
  • Implante o protótipo final na produção.

Pré-requisitos

Para usar este guia de início rápido, você precisará dos itens a seguir.

• Linux, macOS ou Windows
• Visual Studio Code

Adicionar o Data Connect ao projeto e criar uma fonte de dados

1. Crie um projeto do Firebase, caso ainda não tenha feito.
   1. No Console do Firebase, clique em Adicionar projeto e siga as instruções na tela.

2. Faça upgrade do seu projeto para o plano Blaze. Isso permite criar uma instância do Cloud SQL para PostgreSQL.

3. Navegue até a seção Conexão de dados do Console do Firebase e siga o fluxo de trabalho de configuração do produto.

4. Selecione um local para o banco de dados do Cloud SQL para PostgreSQL.

5. Anote os nomes e IDs do projeto, do serviço e do banco de dados para confirmação mais tarde.

6. Siga o fluxo de configuração restante e clique em Concluído.

Escolher e configurar um ambiente de desenvolvimento

Você vai começar a usar o Data Connect criando protótipos de um app no Visual Studio Code.

Outra opção é instalar um banco de dados PostgreSQL local para desenvolvimento local com o emulador do Data Connect. Essa configuração é abordada no final deste guia de início rápido.

O Data Connect oferece suporte para duas experiências de desenvolvimento para prototipagem:

• Se você é um desenvolvedor da Web ou do Android Kotlin, pode prototipar esquemas e operações localmente ao se conectar à sua instância do Cloud SQL para PostgreSQL ou, como opção, executar o PostgreSQL localmente.

• Se você é um desenvolvedor da Web, use o IDX para fazer protótipos em um espaço de trabalho do IDX usando um modelo IDX pré-configurado com o PostgreSQL, a extensão VS Code com o emulador do Data Connect e o código de início rápido configurado para você.

Configurar seu projeto local

Instale a CLI seguindo as instruções normais.

Em seguida, ative o experimento do Firebase Data Connect.

firebase experiments:enable dataconnect

Para configurar seu projeto local, inicializaremos o diretório do projeto e atualizaremos alguns arquivos de configuração necessários para a geração do código.

Configurar o diretório do projeto

Inicialize o diretório do seu projeto.

Qualquer fluxo criará arquivos firebase.json e .firebaserc e subdiretórios dataconnect, incluindo arquivos dataconnect.yaml e connector.yaml importantes no diretório de trabalho local.

Configurar onde o código do SDK é gerado

O Data Connect gera automaticamente o código do SDK enquanto você edita o esquema.

Para especificar para onde os SDKs são gerados, atualize o arquivo do conector inicial em dataconnect/connector/connector.yaml.

connectorId: "my-connector"
authMode: "PUBLIC"
generate:
  javascriptSdk:
    outputDir: "../../js-email-generated"
    package: "@email-manager/emails"
    packageJsonDir: "../../"
  kotlinSdk:
    outputDir: "../kotlin-email-generated"
    package: com.myemailapplication

Conheça o kit de ferramentas do Data Connect

O kit de ferramentas do Data Connect é um componente da extensão VS Code do Firebase que ajuda no desenvolvimento de esquemas e no gerenciamento de consultas e mutações diretamente no Visual Studio Code.

Para conferir os recursos do Toolkit:

1. Abra o diretório do projeto do Firebase no VS Code, caso ainda não tenha feito isso.
2. No painel à esquerda do VS Code, clique no ícone do Firebase para abrir a interface da extensão do Firebase VS Code.

Durante todo o trabalho de desenvolvimento, observe que o Toolkit permite interagir com seu ambiente local e com seus recursos de produção. Neste guia de início rápido, você vai interagir com seu ambiente de produção.

A interface da extensão oferece vários recursos úteis:

Na barra lateral primária do VS Code:

Barra lateral principal

• Um painel Config, que permite fazer login no Google e selecionar um projeto do Firebase.
• Um painel do Firebase Data Connect, que permite controlar o emulador integrado e implantar recursos na produção.
• Um painel FDC Explorer, que lista consultas implícitas geradas automaticamente e mutações com base no seu esquema

No painel inferior do VS Code:

Painel inferior

• Uma guia Execução do Conexão de dados, com ferramentas para permitir a transmissão de dados em solicitações, imitar a autenticação e exibir os resultados.

Antes de começarmos a desenvolver um app, confira alguns recursos da extensão.

Criar um esquema e uma consulta do Data Connect

A configuração foi concluída. Agora podemos começar a desenvolver com o Data Connect.

Começar a usar o GraphQL para estimar usuários e e-mails Você vai atualizar as fontes nos seguintes idiomas:

• /dataconnect/schema/schema.gql
• /dataconnect/connector/queries.gql

Começar a desenvolver um esquema

No diretório do projeto do Firebase, anote a pasta dataconnect. É aqui que você define seu modelo de dados para um banco de dados do Cloud SQL usando GraphQL.

No arquivo /dataconnect/schema/schema.gql, comece a definir um esquema que inclua usuários e e-mails.

Usuário

No Data Connect, os campos do GraphQL são mapeados para colunas. Os usuários têm um uid, name e o e-mail address. O Data Connect reconhece vários tipos de dados primitivos: String e Date.

Copie o snippet a seguir ou remova a marca de comentário das linhas correspondentes no arquivo.

# File `/dataconnect/schema/schema.gql`

type User @table(key: "uid") {
   uid: String!
   name: String!
   address: String!
}

Por padrão, o Firebase Data Connect adicionará uma chave UUID id se nenhuma for fornecida. No entanto, nesse caso, você quer que uid seja a chave primária, o que pode ser feito com a diretiva @table(key: "uid").

E-mail

Agora que você tem usuários, pode modelar e-mails. Aqui você pode adicionar campos (ou colunas) típicos para dados de e-mail. Desta vez, omitimos a adição de uma chave primária porque você pode confiar no Data Connect para gerenciá-la.

# File `/dataconnect/schema/schema.gql`

type Email @table {
   subject: String!
   date: Date!
   text: String!
   from: User!
}

O campo from é mapeado para um tipo de User. A Conexão de dados entende que essa é uma relação entre Email e User e vai gerenciá-la para você.

Implantar seu esquema para produção

Como você está usando a extensão VS Code do Firebase para trabalhar com o banco de dados de produção, é necessário implantar o esquema antes de continuar.

1. É possível usar a extensão VS Code do Firebase para implantar.
   • Na IU da extensão, no painel do Firebase Data Connect, clique em Implantar.

2. Como alternativa, é possível usar a CLI do Firebase.

   firebase deploy
   

3. No fluxo da extensão ou da CLI, pode ser necessário analisar as alterações no esquema e aprovar modificações potencialmente destrutivas. Você será solicitado a:

   • Revisar mudanças no esquema usando firebase dataconnect:sql:diff
   • Quando as mudanças forem satisfatórias, aplique-as usando o fluxo iniciado por firebase dataconnect:sql:migrate.

Conferir as extensões de esquema geradas

À medida que você edita seu esquema de e-mail, o Data Connect gera automaticamente extensões, consultas, mutações, filtros e relações de tabela de esquema. É possível visualizar esse código gerado de duas maneiras.

• Consulte uma lista de mutações e consultas implícitas geradas na interface da extensão do Firebase no painel FDC Explorer.
• É possível ver todo o código gerado local nas origens no diretório .dataconnect/schema.

Executar uma mutação para adicionar dados à sua tabela

Os botões do CodeLens aparecem sobre os tipos do GraphQL em /dataconnect/schema/schema.gql.

Consultas e mutações de tempo de desenvolvimento

As operações associadas a esses botões do CodeLens são ações rápidas e úteis, neste caso, adicionar dados à tabela. O Data Connect usa mutações GraphQL para descrever como e quem pode operar no banco de dados. Com esse botão, é criada uma operação de tempo de desenvolvimento para rápida propagação de dados.

Depois de implantar o esquema na produção, use os botões do CodeLens Executar (produção) para realizar essas ações no back-end.

Criar uma consulta para listar e-mails

Agora a parte divertida: as consultas. Como desenvolvedor, você está acostumado a escrever consultas SQL em vez de consultas GraphQL, então isso pode parecer um pouco diferente no início. No entanto, o GraphQL é muito mais conciso e seguro de tipos do que o SQL bruto. Nossa extensão do VS Code facilita a experiência de desenvolvimento.

Comece a editar o arquivo /dataconnect/connector/queries.gql. Se quiser receber todos os e-mails, use uma consulta como esta.

# File `/dataconnect/connector/queries.gql`

query listEmails @auth(level: PUBLIC) {
  emails {
    id, subject, text, date
    from {
      name
    }
  }
}

Um recurso muito interessante aqui é a capacidade de tratar as relações do banco de dados como um gráfico. Como um e-mail tem um campo from que se refere a um usuário, você pode aninhar no campo e receber informações sobre o usuário.

Diretiva @auth

A diretiva @auth não está sendo usada ao máximo neste exemplo, mas o conceito é muito eficiente. É assim que você decide a política de autorização para operações no banco de dados.

Essa consulta é bastante direta. Os recursos realmente interessantes da Conexão de dados começam a brilhar quando você realiza junções mais complexas com relações de muitos para muitos. Você aprenderá mais sobre isso ao explorar ferramentas e documentação.

Testar a consulta

Agora que criamos essa consulta, verifique se ela funciona antes de integrá-la ao código do cliente. Uma parte da experiência do desenvolvedor do Data Connect é a capacidade de iterar e testar rapidamente os resultados da consulta com o painel Execução do Data Connect.

Você pode fornecer os argumentos necessários para a consulta e, em seguida, clicar no botão CodeLens acima do nome da consulta. Isso executa a consulta e exibe os resultados para que você possa ver que está funcionando conforme o esperado.

Gerar código do SDK cliente e consultar dados de um app cliente

Para encerrar o ciclo de desenvolvimento, integre essa consulta ao código do cliente.

É possível escrever um cliente para demonstrar a chamada da consulta e o processamento das respostas do serviço do Data Connect.

1. Localize fontes geradas automaticamente no local especificado anteriormente no arquivo connector.yaml.

2. Adicione o Firebase ao seu projeto, registre o app e instale o SDK principal do Firebase relevante:

   • Para JavaScript, siga estas instruções.
   • No Kotlin, siga estas instruções.

3. Se você não estiver usando o IDX, poderá configurar um cliente que pode ser chamado na linha de comando.

const { initializeApp } = require("firebase/app");
const {
  connectDataConnectEmulator,
  getDataConnect,
} = require("firebase/data-connect");
const { listEmails, connectorConfig } = require("@email-manager/emails");

// TODO: Replace the following with your app's Firebase project configuration
const firebaseConfig = {
  //...
};

const app = initializeApp(firebaseConfig);
const dc = getDataConnect(app, connectorConfig);

// Remove the following line to connect directly to production
connectDataConnectEmulator(dc, "localhost", 9399);

listEmails().then(res => {
  console.log(res.data.emails);
  process.exit(0);
});
    

    node clientTest.js
    

class MainActivity : ComponentActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    lifecycleScope.launch {
      val connector = MyConnector.instance
      connector.dataConnect.useEmulator() // Remove to connect to production
      try {
        println(connector.listEmails.execute().data.emails)
      } catch (e: Throwable) {
        println("ERROR: $e")
      }
    }
  }
}
    

Implantar o protótipo completo na produção

Você trabalhou em uma iteração de desenvolvimento. Agora é possível implantar esquema, dados, consultas e mutações no servidor com a interface da extensão do Firebase ou a CLI do Firebase, assim como você fez com o esquema.

Depois de implantado, o serviço do Data Connect estará pronto para processar as operações dos clientes. A instância do Cloud SQL para PostgreSQL será atualizada com o esquema e os dados gerados finais implantados.

Instalar o PostgreSQL localmente (opcional)

Instalar o PostgreSQL localmente e integrá-lo ao emulador permite criar protótipos em um ambiente de desenvolvimento totalmente local.

Instale uma nova instância do PostgreSQL ou use uma atual.

Instale o PostgreSQL

Instale o PostgreSQL versão 15.x seguindo as instruções para sua plataforma.

• macOS (em inglês) Faça o download e instale o Postgres.app.
• Windows:use o instalador do EDB na página de downloads do PostgreSQL.
• Docker: extraia e execute a imagem pgvector/pgvector:15, que vem com suporte ao PostgreSQL 15.x e a vetores.
• Linux:recomendamos usar o Docker com a imagem anterior, mas também é possível seguir instruções alternativas para distribuições conhecidas.

Anote o nome do host, a porta, o nome de usuário, a senha e os parâmetros relacionados gerados durante a sequência de instalação.

Para se conectar à instância do PostgreSQL, o emulador precisa de:

• Estes parâmetros de configuração
• O nome do banco de dados do dataconnect.yaml e um banco de dados com o nome correspondente inicializado na instância local.

Atualizar o .firebaserc com a string de conexão

Use os detalhes de configuração local do PostgreSQL, incluindo o nome de usuário e a senha do PostgreSQL, para que uma string de conexão seja adicionada à chave a seguir no arquivo .firebaserc.

{
  "projects": {},
  ...,
  ...,
  "dataconnectEmulatorConfig": {
    "postgres": {
      "localConnectionString": "postgresql://postgresusername:postgrespassword@localhost:5432?sslmode=disable"
    }}
}

Conectar-se à instância local do PostgreSQL

Com essa configuração concluída, para se conectar ao seu banco de dados local:

1. No painel à esquerda do VS Code, clique no ícone do Firebase para abrir a interface da extensão do Firebase VS Code.
2. Clique no botão Conectar ao PostgreSQL local.

Próximas etapas