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.
• Em seguida, mostraremos como:
  • Crie um esquema para um app de e-mails e implante na produção.
  • Defina consultas e mutações para o esquema.
  • 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 seu projeto e criar uma fonte de dados

1. Crie um projeto do Firebase, caso ainda não tenha feito isso.
   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 CloudSQL para PostgreSQL.

5. Anote os nomes e IDs do projeto, serviço e banco de dados para confirmar 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 com o Data Connect prototipando um app no Visual Studio Code.

Opcionalmente, você pode 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 a duas experiências de desenvolvimento para prototipagem:

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

• Se você é um desenvolvedor da Web, pode usar o IDX para criar protótipos em um espaço de trabalho do IDX usando um modelo IDX pré-configurado com o PostgreSQL, uma extensão do VS Code com o emulador do Data Connect e o código do guia 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, inicialize o diretório do projeto.

Configurar o diretório do projeto

Inicialize o diretório do seu projeto.

No painel à esquerda do VS Code, clique no ícone do Firebase para abrir a interface da extensão do Firebase VS Code.

Na interface da extensão do Firebase:

1. Verifique se você fez login.
2. Confirme se o fluxo de configuração do Data Connect, incluindo o provisionamento do banco de dados, está concluído usando o console do Google Cloud.
3. Clique no botão Executar firebase init.
4. Verifique a guia Terminal no painel inferior do VS Code para conferir os comandos.
5. Selecione Data Connect como um recurso para usar neste diretório.
6. Quando solicitado, forneça os IDs do projeto, do serviço e do banco de dados do projeto do Data Connect criado anteriormente no console.

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

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.

Comece a usar o GraphQL para modelar usuários e e-mails. Você atualizará as fontes em:

• /dataconnect/schema/schema.gql
• /dataconnect/default-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 o 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 um 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, uid deve ser a chave primária, o que pode ser feito com a diretiva @table(key: "uid").

E-mail

Agora que você tem usuários, é possível modelar e-mails. Aqui é possível 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!
   sent: Date!
   text: String!
   from: User!
}

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

Implante o esquema na produção

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

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

2. Como alternativa, você pode usar a CLI do Firebase.

   firebase deploy
   

3. No fluxo de extensão ou da CLI, talvez seja necessário analisar as alterações no esquema e aprovar modificações potencialmente destrutivas. Será solicitado que você:

   • Revisar mudanças no esquema usando firebase dataconnect:sql:diff
   • Quando estiver tudo pronto, aplique as mudanças usando o fluxo iniciado por firebase dataconnect:sql:migrate.

Executar mutações para adicionar dados às tabelas

No painel do editor do VS Code, é possível conferir os botões do CodeLens nos tipos do GraphQL em /dataconnect/schema/schema.gql.

Consultas e mutações do tempo de desenvolvimento

As operações sem nome associadas a esses botões do CodeLens são ações rápidas e úteis. Neste caso, elas adicionam dados à tabela. O Data Connect usa mutações GraphQL para descrever como e quem pode operar no banco de dados. O uso desse botão cria uma operação de tempo de desenvolvimento para uma rápida propagação de dados.

Como você implantou o esquema na produção, é possível usar os botões Adicionar dados do CodeLens nos botões schema.gql e Executar (produção) nos arquivos gerados resultantes para executar essas ações no back-end.

Para adicionar registros às tabelas User e Email:

1. Em schema.gql, clique no botão Adicionar dados acima da declaração de tipo User.
2. No arquivo User_insert.gql que é gerado, codifique os dados para os três campos.
3. Clique no botão Executar (produção).
   
4. Repita as etapas anteriores para adicionar um registro à tabela Email, fornecendo o uid do usuário no campo fromUid, conforme solicitado na mutação Email_insert gerada.

Escreva uma consulta para listar e-mails

Agora a parte divertida são 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 começo. No entanto, o GraphQL é muito mais conciso e seguro do que o SQL bruto. E nossa extensão do VS Code facilita a experiência de desenvolvimento.

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

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

query ListEmails @auth(level: NO_ACCESS) {
  emails {
    id, subject, text, sent
    from {
      name
    }
  }
}

Execute a consulta usando o botão CodeLens próximo.

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

Implantar seu protótipo completo para produção

Você trabalhou em uma iteração de desenvolvimento. Agora é possível implantar o esquema, os dados e as consultas no servidor com a IU da extensão do Firebase ou a CLI do Firebase, da mesma forma que fez com o esquema.

Depois de implantado, o serviço do Data Connect estará pronto para processar operações de 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.

Você pode instalar uma nova instância do PostgreSQL ou usar uma atual.

Instale o PostgreSQL

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

• macOS: Faça o download e instale o Postgres.app.
• Windows:use o instalador EDB da 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.

Observe o nome do host, a porta, o nome de usuário e 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:

• Estes parâmetros de configuração
• O nome do banco de dados da dataconnect.yaml e um banco de dados com 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 locais 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 VS Code, no painel esquerdo, 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