Começar a usar o Firebase Data Connect localmente

Neste guia de início rápido, você vai aprender a criar Firebase Data Connect no 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, incluindo extensões do Visual Studio Code, para trabalhar com uma instância local.
  • Em seguida, vamos mostrar como:
    • Use as ferramentas de extensão do VS Code com Gemini Code Assist para:
      • Criar um esquema para um app
      • Crie consultas e mutações administrativas para preencher seu banco de dados local.
      • Ajudar você a implementar consultas e mutações para seu app em um conector implantável
    • Teste suas consultas e mutações com dados de amostra em um emulador local
    • Gere SDKs fortemente tipados e use-os no seu app
    • Implante o esquema e o conector finais na nuvem (opcional, com um upgrade do plano Blaze).

Escolher um fluxo de desenvolvimento local

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

Pré-requisitos

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

Configurar o ambiente para desenvolvedores

  1. Crie um novo diretório para seu projeto local.
  2. Abra o VS Code no novo diretório.
  3. Instale a extensão do Firebase Data Connect no Visual Studio Code Marketplace.

Configurar o diretório do projeto

Para configurar seu projeto local, inicialize o diretório dele. Na janela do IDE, no painel à esquerda, clique no ícone do Firebase para abrir a interface da extensão Data Connect 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 Executar firebase init.

  4. Clique no botão Iniciar emuladores.

criar um esquema

No diretório do projeto do Firebase, no arquivo /dataconnect/schema/schema.gql, comece a definir um esquema do GraphQL sobre, por exemplo, avaliações de filmes.

Usar Gemini Code Assist para criar um esquema

Para criar um esquema de app de avaliação de filmes usando Gemini Code Assist:

  1. Clique no ícone da extensão Data Connect VS Code para abrir a barra lateral.
  2. Clique em Testar o Gemini com @FirebaseDataConnect. A janela de chat Gemini Code Assist é aberta.
  3. Clique na interface de chat e comece a digitar @FirebaseDataConnect para filtrar os comandos relevantes.

  4. Selecione o comando /generate_schema e, no prompt, conclua o comando, pedindo ao Gemini para criar um esquema para o app que você está desenvolvendo.

    Exemplo:

    @FirebaseDataConnect /generate_schema I want to build an app to track movie reviews from multiple users

  5. Depois de alguns instantes, um esquema recomendado vai aparecer. Analise o esquema.

  6. Para adicionar o código a schema.gql:

    1. Clique no botão Inserir na parte de baixo do arquivo.
    2. Ou, para inserir o código na posição do cursor, clique no botão + na parte de cima da resposta do chat.

Filme

Em Data Connect, os campos do GraphQL são mapeados para colunas. O filme tem id, title, imageUrl e genre. O 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 da IDE, você verá botões do CodeLens aparecerem sobre os tipos GraphQL em /dataconnect/schema/schema.gql. Você pode usar os botões Adicionar dados e Executar (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 Adicionar dados acima da declaração de tipo Movie.
    Botão &quot;Adicionar dados&quot; do CodeLens para o Firebase Data Connect
  2. No arquivo Movie_insert.gql gerado, codifique os dados para os três campos.
  3. Clique no botão Executar (local).
    Botão &quot;Executar&quot; do CodeLens para o Firebase Data Connect
  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. De volta ao schema.gql, clique no botão Ler dados acima da declaração do tipo Movie.
  2. No arquivo Movie_read.gql resultante, clique no botão Executar (local) para executar a consulta.

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

Definir uma consulta

Agora, para mais diversão, defina as consultas necessárias no aplicativo. Como desenvolvedor, você está acostumado a escrever consultas SQL em vez de GraphQL, então isso pode parecer um pouco diferente no início.

No entanto, o GraphQL é muito mais conciso e seguro em relação a tipos do que o SQL bruto. Além disso, nossa extensão do VS Code facilita a experiência de desenvolvimento, tanto para consultas quanto para mutações.

Para criar uma consulta usando Gemini Code Assist:

  1. Clique no ícone da extensão Data Connect VS Code para abrir a barra lateral.
  2. Clique em Testar o Gemini com @FirebaseDataConnect. A janela de chat Gemini Code Assist é aberta.
  3. Clique na interface de chat e comece a digitar @FirebaseDataConnect para filtrar os comandos relevantes.

  4. Selecione o comando /generate_operation e, no prompt, complete o comando pedindo ao Gemini para criar uma consulta.

    Exemplo:

    @FirebaseDataConnect /generate_operation List all movies with titles start with "A".

  5. Depois de alguns instantes, uma consulta recomendada vai aparecer. Revise a consulta.

  6. Para adicionar o código a queries.gql:

    1. Clique no botão Inserir na parte de baixo do arquivo.
    2. Ou, para inserir o código na posição do cursor, clique no botão + na parte de cima da resposta do chat.

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

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 Data Connect 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 seu app. O código do SDK Data Connect será gerado e salvo lá.

  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

Use o SDK gerado pelo Data Connect para implementar uma chamada à sua 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 seu app React:

    • importe o SDK gerado
    • instruir o app para se conectar ao emulador Data Connect
    • chamar métodos Data Connect.
    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 iOS.

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

    Na barra de navegação superior do Xcode, selecione Arquivo > Adicionar dependências de pacote > Adicionar local e escolha a pasta que contém o Package.swift gerado.

  3. No delegado principal do app:

    • importe o SDK gerado
    • instruir o app para se conectar ao emulador Data Connect
    • chamar métodos Data Connect.
    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 ?? []) { 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 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 seu app/build.gradle.kts.

    plugins {
  // Use whichever versions of these dependencies suit your application.
  // The versions shown here were the latest as of March 14, 2025.
  // Note, however, that the version of kotlin("plugin.serialization") must,
  // in general, match the version of kotlin("android").
  id("com.android.application") version "8.9.0"
  id("com.google.gms.google-services") version "4.4.2"
  val kotlinVersion = "2.1.10"
  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 March 14, 2025.
  implementation("com.google.firebase:firebase-dataconnect:16.0.0-beta04")
  implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.1")
  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.10.1")
  implementation("androidx.lifecycle:lifecycle-viewmodel-ktx:2.8.7")
  implementation("com.google.android.material:material:1.12.0")
}

  3. Na atividade principal do app:

    • importe o SDK gerado
    • instruir o app para se conectar ao emulador Data Connect
    • chamar métodos Data Connect.
    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:
    • importe o SDK gerado
    • instruir o app para se conectar ao emulador Data Connect
    • chamar métodos Data Connect.
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 seu esquema e consulta na produção

Depois de configurar o ambiente local no app, você pode implantar o esquema e o conector na nuvem. Você precisa de um projeto do plano Blaze para configurar uma instância do Cloud SQL.

  1. Acesse a seção "Data Connect" do console Firebase e crie uma instância de teste sem custos financeiros do Cloud SQL.

  2. No Terminal integrado ao IDE, execute firebase init dataconnect e selecione a Região/ID do serviço que você acabou de criar no console.

  3. Selecione Y quando aparecer a mensagem O arquivo dataconnect/dataconnect.yaml já existe. Substituir?.

  4. Na janela do IDE, na interface da extensão do VS Code, clique no botão Implantar na produção.

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

Próximas etapas

Revise o projeto implantado e descubra 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: