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 CLI do Firebase.
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.

Configurar o diretório do projeto local

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

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
```
Clique no ícone do Firebase no painel esquerdo do Visual Studio Code para abrir a tela da extensão Data Connect VS Code.
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 às 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 do GraphQL fornece SDKs fortemente tipados e uma API flexível para buscar os dados exatos de que seu 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 de maneira eficaz. É 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

Adicione o Firebase ao seu app da Web.

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';

Instrumente seu 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

Adicione o Firebase ao seu app iOS.
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.

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

Instrumente seu 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

Adicione o Firebase ao seu app Android.

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")
}

Na atividade principal do app:

Receba uma instância de conector do SDK gerado:

private val connector = com.myapplication.MoviesConnector.instance

Instrumente seu 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

Adicione o Firebase ao app Flutter.
Instale a CLI do flutterfire dart pub global activate flutterfire_cli.
Execute flutterfire configure.

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';

Instrumente seu 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:

Confira as informações sobre preços e teste sem custos financeiros na página Preços. Seu projeto pode se qualificar para uma das opções de teste do Firebase Data Connect.
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.

Dica: é possível configurar a região do Cloud SQL, o nome da instância e o nome do banco de dados do PostgreSQL em dataconnect.yaml antes da implantação.

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:

Confira um repositório de apps de guia de início rápido e crie um app Data Connect completo seguindo nosso codelab para Web, codelab para iOS ou codelab para Android.
Adicione dados ao banco de dados, inspecione os esquemas e monitore o serviço do Data Connect no console do Firebase.
Configure o servidor MCP do Firebase com ferramentas de desenvolvimento com tecnologia de IA, como o Gemini Code Assist.
Saiba mais sobre o desenvolvimento de esquemas, consultas e mutações.
Saiba mais sobre como o Data Connect gerencia o esquema do PostgreSQL.
Saiba mais sobre os SDKs de cliente para Web, Android, iOS e Flutter, além dos SDKs Admin para Node.js.