Começar a usar o Firebase Data Connect

Este guia de início rápido ensina a usar o Firebase Data Connect para conectar seus apps da Web e para dispositivos móveis a um banco de dados PostgreSQL. Você vai:

  • Configure o diretório do projeto Firebase Data Connect local com o VS Code e a Firebase CLI.
  • Gere esquemas, consultas e mutações do Data Connect com base nas suas ideias de apps em linguagem natural.
  • Use os SDKs fortemente tipados nos seus apps para executar consultas e mutações de Data Connect.
  • Provisione uma instância do Cloud SQL para PostgreSQL, um esquema do Data Connect, consultas e mutações (requer um plano Blaze).

Configurar o diretório do projeto local

É possível instalar ferramentas de desenvolvimento local para Data Connect de duas maneiras.

  1. Em um diretório de projeto, execute o seguinte comando.

    O script instala a CLI do Firebase e a extensão Data Connect do VS Code, além de orientar você em firebase init dataconnect para configurar o projeto. Se você não tiver o VS Code para computador instalado, o script vai abrir o programa em um navegador.

    curl -sL https://firebase.tools/init/dataconnect | editor=true bash

  2. Clique no ícone do Firebase no painel esquerdo do Visual Studio Code para abrir a tela da extensão Data Connect VS Code.

  3. Clique em Iniciar emuladores para executar o emulador com um banco de dados PGlite local.

Esquema de revisão

O Firebase Data Connect usa GraphQL para definir seu modelo de dados. A diretiva @table mapeia um tipo GraphQL para uma tabela do PostgreSQL. Os campos no mapa de tipos correspondem a colunas do PostgreSQL. É possível definir relações entre tabelas usando campos que referenciam outros tipos de @table, incluindo relações de muitos para muitos usando tabelas de junção com chaves primárias compostas.

Na configuração padrão, você encontra os arquivos de esquema Data Connect no diretório dataconnect/schema/. Confira dois exemplos de tabelas do esquema de modelo de filme. Seu esquema pode ser diferente se você usou o Gemini para gerá-lo.

type Movie @table {
  # Every table has an implicit primary key field that looks something like:
  #  id: UUID! @default(expr: "uuidV4()")
  title: String!
  imageUrl: String!
  genre: String
}

type Review @table(key: ["movie", "user"]) {
  user: User!
  movie: Movie!
  rating: Int
  reviewText: String
  reviewDate: Date! @default(expr: "request.time")
}

Saiba mais sobre os esquemas do Data Connect

Desenvolver consultas e mutações

O Firebase Data Connect usa GraphQL para consultas e mutações. Você define esses arquivos em .gql e os chama por nome no app. A sintaxe GraphQL fornece SDKs fortemente tipados e uma API flexível para buscar os dados exatos de que o app precisa.

Propagar dados no banco de dados

Com o emulador em execução, é possível inserir dados iniciais nele. Você pode usar o arquivo dataconnect/seed_data.gql fornecido ou escrever suas próprias mutações.

Use o botão Executar (local) do CodeLens no VS Code para executar as mutações e preencher seu banco de dados PGlite local.

Botão "Executar" do CodeLens para o Firebase Data Connect

Analisar consultas e mutações

Na configuração padrão, você encontra as consultas e mutações do Data Connect no diretório dataconnect/example/.

É possível consultar dados relacionais com precisão usando consultas aninhadas.

query ListMovies @auth(level: PUBLIC, insecureReason: "Anyone can list all movies and their reviews.") {
  movies {
    title imageUrl genre
    reviews_on_movie {
      rating reviewDate
      user { username }
    }
  }
}

O Data Connect ajuda você a criar consultas e mutações seguras com o Firebase Auth.

Para manter a segurança do app, os apps para Web e dispositivos móveis só podem acessar consultas e mutações do Data Connect com diretivas @auth. Consultas e mutações podem acessar com segurança o UID do Firebase Auth usando uma expressão como {field}_expr: "auth.uid".

mutation AddReview($movieId: UUID!, $rating: Int!, $reviewText: String!) @auth(level: USER) {
  review_upsert(
    data: {
      userId_expr: "auth.uid"
      movieId: $movieId
      rating: $rating
      reviewText: $reviewText
    }
  )
}

Saiba mais sobre consultas do Data Connect Saiba mais sobre mutações do Data Connect Saiba mais sobre a autenticação do Data Connect

Gerar consultas e mutações

Você não precisa ser um especialista em GraphQL para usar o Data Connect com eficiência. É possível gerar consultas e mutações Data Connect com base em descrições em linguagem natural.

Em qualquer arquivo .gql, digite # para iniciar um comentário e descrever uma consulta ou mutação. Em seguida, use o botão Gerar/refinar operação do CodeLens para gerar a operação GraphQL.

Botão "Gerar" do CodeLens para o Firebase Data Connect

Usar o SDK gerado no seu app

O firebase init dataconnect configura automaticamente SDKs seguros para apps no seu projeto. Se necessário, adicione o SDK manualmente com o botão Adicionar SDK ao app na extensão do VS Code ou executando firebase init dataconnect:sdk.

Web

  1. Adicione o Firebase ao seu app da Web.

  2. No arquivo principal do seu app React:

    • Importe o SDK gerado:
    // Update as needed with the path to your generated SDK.
import { listMovies, ListMoviesData } from '@dataconnect/generated';
    • Instrua o app para se conectar ao emulador Data Connect:
    import { connectDataConnectEmulator } from 'firebase/data-connect';

const dataConnect = getDataConnect(connectorConfig);
connectDataConnectEmulator(dataConnect, 'localhost', 9399);
    • Chamar métodos Data Connect.
    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 do Data Connect e o SDK gerado:

      import FirebaseDataConnect
// Generated queries.
// Update as needed with the package name of your generated SDK.
import <CONNECTOR-PACKAGE-NAME>

let connector = DataConnect.moviesConnector

    • Instrua o app para se conectar ao emulador Data Connect:

      // 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)

    • Chame os métodos Data Connect:

      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:

    • Receba uma instância de conector do SDK gerado:
    private val connector = com.myapplication.MoviesConnector.instance
    • Instrua o app para se conectar ao emulador Data Connect:
    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)
  }
    • Chamar métodos Data Connect.
    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:
    // Generated queries.
// Update as needed with the path to your generated SDK

import 'movies_connector/movies.dart';
    • Instrua o app para se conectar ao emulador Data Connect:
    void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp(
    options: DefaultFirebaseOptions.currentPlatform,
  );
  
  MoviesConnector.instance.dataConnect
      .useDataConnectEmulator(Uri.base.host, 443, isSecure: true);
  
  runApp(const MyApp());
}
    • Chamar métodos Data Connect.
    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 para a produção

Para implantar seu esquema, consultas e mutações na produção:

  1. Faça upgrade do projeto do Firebase para usar o plano Blaze.

  2. Clique no botão Implantar em produção na extensão Data Connect do VS Code ou execute em um terminal:

    firebase deploy --only dataconnect

    Depois da implantação, acesse o console Firebase para conferir seu esquema e executar consultas e mutações.

Saiba mais sobre dataconnect.yaml Saiba mais sobre como o Data Connect funciona com o Cloud SQL

Próximas etapas

Agora que você concluiu o guia de início rápido, confira algumas próximas etapas: