Começar a usar o Firebase Data Connect localmente

Observação: o Firebase Data Connect está no Acesso antecipado. O Data Connect está sujeito aos "Termos das ofertas pré-GA" na seção Termos específicos de serviço dos Termos de Serviço do Google Cloud Platform. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Observação: siga este guia de início rápido local se você quiser testar o Data Connect com um projeto de plano do Spark. Neste guia, você vai criar protótipos localmente com um emulador e um banco de dados local. Se você estiver pronto para adicionar Data Connect a um projeto do plano Blaze e configurar um serviço e um banco de dados do Cloud SQL, tente a introdução à produção.

Neste guia de início rápido, você vai aprender a criar Firebase Data Connect no seu aplicativo localmente sem configurar uma instância SQL de produção. Você vai:

• Adicione Firebase Data Connect ao seu projeto do Firebase.
• Configure um ambiente de desenvolvimento que inclua uma extensão do Visual Studio Code para trabalhar com uma instância local.
• Em seguida, vamos mostrar como:
  • Criar um esquema para um app de filmes
  • Definir as consultas e mutações que serão usadas no app
  • Teste suas consultas e mutações com dados de amostra em um emulador local
  • Gerar SDKs com tipagem forte e usá-los no seu app
  • Implante seu esquema, consultas e dados finais na nuvem (opcional, com um upgrade do plano Blaze).

Encontre um repositório de apps de início rápido e crie um app Data Connect com todos os recursos seguindo nosso codelab para Web. Os codelabs para Android e iOS serão lançados em breve.

Escolher um fluxo de desenvolvimento local

O Data Connect oferece duas maneiras de instalar ferramentas de desenvolvimento e trabalhar localmente.

Instalação automática (macOS ou Linux) Instalação manual (Windows)

Pré-requisitos

Para usar este guia de início rápido, você vai precisar do seguinte:

• um projeto do Firebase; Se você ainda não criou um, faça isso no console do Firebase.

Configurar o ambiente para desenvolvedores

1. Crie um novo diretório para seu projeto local.

2. Execute o comando abaixo no novo diretório que você criou.

     curl -sL https://firebase.tools/dataconnect | bash

   Esse script tenta configurar o ambiente de desenvolvimento para você e iniciar um ambiente de desenvolvimento integrado baseado em navegador. Esse ambiente de desenvolvimento integrado oferece ferramentas, incluindo uma extensão pré-empacotada do VS Code, para ajudar a gerenciar seu esquema e definir consultas e mutações a serem usadas no aplicativo, além de gerar SDKs fortemente tipados.

   Observação: se você já tiver a versão para computador do VS Code instalada, o script vai abri-lo automaticamente.
   Observação: se o script falhar, use as etapas de instalação manual.

Dica: se preferir, você pode configurar um alias anexando a linha a seguir ao seu perfil de shell (por exemplo, ~/.zshrc ou ~/.bash_profile). Isso permite atualizar localmente a ferramenta ou reiniciar o ambiente de desenvolvimento integrado baseado em navegador digitando dataconnect.

alias dataconnect='curl -sL https://firebase.tools/dataconnect | bash'

Configurar o diretório do projeto

Para configurar seu projeto local, inicialize o diretório do projeto. Na janela do ambiente de desenvolvimento integrado, no painel à esquerda, clique no ícone do Firebase para abrir a interface da extensão do Data Connect no VS Code:

1. Clique no botão Fazer login com o Google.
2. Clique no botão Conectar um projeto do Firebase e selecione o projeto que você criou anteriormente no console.
3. Clique no botão Run firebase init.

4. Clique no botão Start emulators.

   Observação: no Terminal integrado, verifique se os emuladores configurados foram inicializados. Quando estiverem em execução, a interface da extensão será atualizada com detalhes do emulador.

criar um esquema

No diretório do projeto do Firebase, no arquivo /dataconnect/schema/schema.gql, comece a definir um esquema do GraphQL sobre filmes.

Filme

Em Data Connect, os campos do GraphQL são mapeados para colunas. O filme tem id, title, imageUrl e genre. Data Connect reconhece tipos de dados primitivos: String e UUID.

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

# By default, a UUID id key will be created by default as primary key.
# If you want to specify a primary key, say title, which you can do through
# the @table(key: "title") directive
type Movie @table {
  id: UUID! @default(expr: "uuidV4()")
  title: String!
  imageUrl: String!
  genre: String
}

MovieMetadata

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

# Movie - MovieMetadata is a one-to-one relationship
type MovieMetadata @table {
  # This time, we omit adding a primary key because
  # you can rely on Data Connect to manage it.

  # @unique indicates a 1-1 relationship
  movie: Movie! @unique
  # movieId: UUID <- this is created by the above reference
  rating: Float
  releaseYear: Int
  description: String
}

O campo movie é mapeado para um tipo de Movie. Data Connect entende que essa é uma relação entre Movie e MovieMetadata e vai gerenciar essa relação para você.

Saiba mais sobre os esquemas do Data Connect na documentação

Adicionar dados às tabelas

No painel do editor do ambiente de desenvolvimento integrado, os botões do CodeLens vão aparecer sobre os tipos do GraphQL em /dataconnect/schema/schema.gql. Use os botões Add data e Run (Local) para adicionar dados ao seu banco de dados local.

Para adicionar registros às tabelas Movie e MovieMetadata:

1. Em schema.gql, clique no botão Add data acima da declaração de tipo Movie.
   
2. No arquivo Movie_insert.gql gerado, codifique os dados dos três campos.
3. Clique no botão Run (Local).
   
4. Repita as etapas anteriores para adicionar um registro à tabela MovieMetadata, fornecendo o id do seu filme no campo movieId, conforme solicitado na mutação MovieMetadata_insert gerada.

Para verificar rapidamente se os dados foram adicionados:

1. Em schema.gql, clique no botão Read data acima da declaração de tipo Movie.
2. No arquivo Movie_read.gql resultante, clique no botão Run (Local) para executar a consulta.

Saiba mais sobre as mutações do Data Connect na documentação

Definir a consulta

Agora a parte divertida: vamos definir as consultas necessárias no seu aplicativo. Como desenvolvedor, você está acostumado a escrever consultas SQL em vez de consultas GraphQL. Por isso, pode parecer um pouco diferente no início.

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/connector/queries.gql. Se você quiser receber todos os filmes, use uma consulta como esta.

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

# @auth() directives control who can call each operation.
# Anyone should be able to list all movies, so the auth level is set to PUBLIC
query ListMovies @auth(level: PUBLIC) {
  movies {
    id
    title
    imageUrl
    genre
  }
}

Execute a consulta usando o botão do CodeLens.

Um recurso muito interessante é a capacidade de tratar as relações do banco de dados como um gráfico. Como um registro MovieMetadata tem um campo movie que faz referência a um filme, é possível aninhar no campo e receber informações sobre as informações do filme. Tente adicionar o tipo gerado movieMetadata_on_movie à consulta ListMovies.

query ListMovies @auth(level: PUBLIC) {
  movies {
    id
    title
    imageUrl
    genre
    movieMetadata_on_movie {
        rating
    }
  }
}

Saiba mais sobre as consultas do Data Connect na documentação

Gerar SDKs e usá-los no seu app

No painel esquerdo do ambiente de desenvolvimento integrado, clique no ícone do Firebase para abrir a interface da extensão do Data Connect no VS Code:

1. Clique no botão Adicionar SDK ao app.

2. Na caixa de diálogo que aparece, selecione um diretório que contenha o código do app. O código do SDK Data Connect será gerado e salvo nele.

   Observação: se você ainda não tem um diretório de app, é possível criar e selecionar um novo diretório para o código do SDK por enquanto e vincular ao app mais tarde.

3. Selecione a plataforma do app e observe que o código do SDK é gerado imediatamente no diretório selecionado.

Usar os SDKs para chamar sua consulta de um app

É possível usar o SDK gerado por Data Connect para implementar uma chamada na consulta ListMovies. Em seguida, execute essa consulta localmente usando o emulador Data Connect.

Web

1. Adicione o Firebase ao seu app da Web.

2. No arquivo principal do app React:

   • importar o SDK gerado;
   • instruir o app a se conectar ao emulador do Data Connect
   • chame os métodos Data Connect.

   Você pode copiar o snippet a seguir e executá-lo como um app independente.

   import React from 'react';
   import ReactDOM from 'react-dom/client';
   
   import { connectDataConnectEmulator } from 'firebase/data-connect';
   
   // Generated queries.
   // Update as needed with the path to your generated SDK.
   import { listMovies, ListMoviesData } from '@movie-app/movies';
   
   const dataConnect = getDataConnect(connectorConfig);
   connectDataConnectEmulator(dataConnect, 'localhost', 9399);
   
   function App() {
     const [movies, setMovies] = useState<ListMoviesData['movies']>([]);
     useEffect(() => {
       listMovies.then(res => setMovies(res.data));
     }, []);
     return (
       movies.map(movie => <h1>{movie.title}</h1>);
     );
   }
   
   const root = ReactDOM.createRoot(document.getElementById('root'));
   root.render(<App />);    
   

Swift

1. Adicione o Firebase ao seu app para iOS.

2. Para usar o SDK gerado, configure-o como uma dependência no Xcode.

   Na barra de navegação superior do Xcode, selecione File > Add Package Dependencies > Add Local e escolha a pasta que contém o Package.swift gerado.

3. No representante principal do app:

   • importar o SDK gerado;
   • instruir o app a se conectar ao emulador do Data Connect
   • chame os métodos Data Connect.

   Você pode copiar o snippet a seguir e executá-lo como um app independente.

   import SwiftUI
   
   import FirebaseDataConnect
   // Generated queries.
   // Update as needed with the package name of your generated SDK.
   import <CONNECTOR-PACKAGE-NAME>
   
   let connector = DataConnect.moviesConnector
   
   // Connect to the emulator on "127.0.0.1:9399"
   connector.useEmulator()
   
   // (alternatively) if you're running your emulator on non-default port:
   // connector.useEmulator(port: 9999)
   
   struct ListMovieView: View {
   @StateObject private var queryRef = connector.listMovies.ref()
   
       var body: some View {
           VStack {
               Button {
                   Task {
                       do {
                           try await refresh()
                       } catch {
                           print("Failed to refresh: \(error)")
                       }
                   }
               } label: {
                   Text("Refresh")
               }
   
               // use the query results in a view
               ForEach(queryRef.data?.movies ?? [], id: \.self.id) { movie in
                       Text(movie.title)
                   }
               }
       }
       @MainActor
       func refresh() async throws {
           _ = try await queryRef.execute()
       }
   
       struct ContentView_Previews: PreviewProvider {
       static var previews: some View {
           ListMovieView()
       }
   }
   

Kotlin para Android

1. Adicione o Firebase ao seu app Android.

2. Para usar o SDK gerado, configure Data Connect como uma dependência no Gradle.

   Atualize plugins e dependencies no app/build.gradle.kts.

   plugins {
     // Use whichever versions of these dependencies suit your application.
     // The versions shown here were the latest as of December 03, 2024.
     // Note, however, that the version of kotlin("plugin.serialization") must,
     // in general, match the version of kotlin("android").
     id("com.android.application") version "8.7.3"
     id("com.google.gms.google-services") version "4.4.2"
     val kotlinVersion = "2.1.0"
     kotlin("android") version kotlinVersion
     kotlin("plugin.serialization") version kotlinVersion
   }
   
   dependencies {
     // Use whichever versions of these dependencies suit your application.
     // The versions shown here were the latest versions as of December 03, 2024.
     implementation("com.google.firebase:firebase-dataconnect:16.0.0-beta03")
     implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.9.0")
     implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.7.3")
   
     // These dependencies are not strictly required, but will very likely be used
     // when writing modern Android applications.
     implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.9.0")
     implementation("androidx.appcompat:appcompat:1.7.0")
     implementation("androidx.activity:activity-ktx:1.9.3")
     implementation("androidx.lifecycle:lifecycle-viewmodel-ktx:2.8.7")
     implementation("com.google.android.material:material:1.12.0")
   }
   

3. Na atividade principal do app:

   • importar o SDK gerado;
   • instruir o app a se conectar ao emulador do Data Connect
   • chame os métodos Data Connect.

   Você pode copiar o snippet a seguir e executá-lo como um app independente.

   import android.os.Bundle
   import android.widget.TextView
   import androidx.appcompat.app.AppCompatActivity
   import androidx.lifecycle.Lifecycle
   import androidx.lifecycle.lifecycleScope
   import androidx.lifecycle.repeatOnLifecycle
   import kotlinx.coroutines.launch
   
   
   private val connector = com.myapplication.MoviesConnector.instance
     .apply {
       // Connect to the emulator on "10.0.2.2:9399" (default port)
       dataConnect.useEmulator()
   
       // (alternatively) if you're running your emulator on non-default port:
       // dataConnect.useEmulator(port = 9999)
     }
   
   
   class MainActivity : AppCompatActivity() {
   
     override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)
       setContentView(R.layout.activity_main)
       val textView: TextView = findViewById(R.id.text_view)
   
       lifecycleScope.launch {
         lifecycle.repeatOnLifecycle(Lifecycle.State.STARTED) {
           
           val result = connector.listMovies.runCatching { execute { } }
           
           val newTextViewText = result.fold(
             onSuccess = {
               val titles = it.data.movies.map { it.title }
               "${titles.size} movies: " + titles.joinToString(", ")
             },
             onFailure = { "ERROR: ${it.message}" }
           )
           textView.text = newTextViewText
         }
       }
     }
   }
   

Flutter

1. Adicione o Firebase ao seu app Flutter.
2. Instale a CLI do FlutterFire dart pub global activate flutterfire_cli.
3. Execute flutterfire configure.

4. Na função principal do app:

   • importar o SDK gerado;
   • instruir o app a se conectar ao emulador do Data Connect
   • chame os métodos Data Connect.

   Você pode copiar o snippet a seguir e executá-lo como um app independente.

import 'package:firebase_core/firebase_core.dart';
import 'package:flutter/material.dart';
import 'firebase_options.dart';

// Generated queries.
// Update as needed with the path to your generated SDK

import 'movies_connector/movies.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  await Firebase.initializeApp(
    options: DefaultFirebaseOptions.currentPlatform,
  );
  
  MoviesConnector.instance.dataConnect
      .useDataConnectEmulator(Uri.base.host, 443, isSecure: true);
  
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
        home: Scaffold(
            body: Column(children: [
      ConstrainedBox(
        constraints: const BoxConstraints(maxHeight: 200),
        child: FutureBuilder(
            future: MoviesConnector.instance.listMovies().execute(),
            builder: (context, snapshot) {
              if (snapshot.connectionState == ConnectionState.done) {
                return ListView.builder(
                  scrollDirection: Axis.vertical,
                  itemBuilder: (context, index) => Card(
                      child: Text(
                    snapshot.data!.data.movies[index].title,
                  )),
                  itemCount: snapshot.data!.data.movies.length,
                );
              }
              return const CircularProgressIndicator();
            }),
      )
    ])));
  }
}

Implantar o esquema e a consulta na produção

Depois de configurar localmente o app, você pode implantar o esquema, os dados e as consultas na nuvem. Você precisa de um projeto do plano Blaze para configurar uma instância do Cloud SQL.

1. Navegue até a seção "Data Connect" do console Firebase e crie uma instância de teste sem custo financeiro do Cloud SQL.

   Observação: o provisionamento da instância do Cloud SQL para PostgreSQL pode levar até 15 minutos. Não será possível implantar até que a instância esteja pronta.
   Observação: se você quiser usar chaves de criptografia gerenciadas pelo cliente (CMEK), escolha Usar a instância do Cloud SQL e selecione um banco de dados do Cloud SQL com CMEK.

2. No Terminal integrado do ambiente de desenvolvimento integrado (IDE, na sigla em inglês), execute firebase init dataconnect e selecione o ID da região/serviço que você acabou de criar no console.

3. Selecione "Y" quando for solicitado "O arquivo dataconnect/dataconnect.yaml já existe. Quer substituir?".

4. Na janela do ambiente de desenvolvimento integrado, na interface da extensão do VS Code, clique no botão Deploy to production.

5. Depois de implantar, acesse o console Firebase para verificar se o esquema, as operações e os dados foram enviados para a nuvem. Você pode conferir o esquema e executar as operações no console também. A instância do Cloud SQL para PostgreSQL será atualizada com o esquema e os dados gerados de implantação final.

Próximas etapas

Revise o projeto implantado e conheça mais ferramentas:

• Adicione dados ao banco de dados, inspecione e modifique os esquemas e monitore o serviço do Data Connect no console do Firebase.

Acesse mais informações na documentação. Por exemplo, como você concluiu o guia de início rápido:

• Saiba mais sobre o desenvolvimento de esquema, consulta e mutação.
• Saiba como gerar SDKs de cliente e chamar consultas e mutações do código do cliente para Web, Android, iOS e Flutter.