Comienza a usar Firebase Data Connect de forma local

En esta guía de inicio rápido, aprenderás a compilar Firebase Data Connect en tu aplicación de forma local sin configurar una instancia de SQL de producción. Harás lo siguiente:

  • Agrega Firebase Data Connect a tu proyecto de Firebase.
  • Configura un entorno de desarrollo que incluya extensiones de Visual Studio Code para trabajar con una instancia local.
  • Luego, te mostraremos cómo hacer lo siguiente:
    • Usa las herramientas de extensión de VS Code, con Gemini Code Assist, para hacer lo siguiente:
      • Crea un esquema para una app
      • Crea consultas y mutaciones administrativas para propagar tu base de datos local
      • Ayudarte a implementar consultas y mutaciones para tu app en un conector implementable
    • Prueba tus consultas y mutaciones con datos de muestra en un emulador local
    • Genera SDKs con escritura segura y úsalos en tu app
    • Implementa tu esquema y conector finales en la nube (opcional, con una actualización al plan Blaze).

Elige un flujo de desarrollo local

Data Connect te ofrece dos formas de instalar herramientas de desarrollo y trabajar de forma local.

Requisitos previos

Para usar esta guía de inicio rápido, necesitarás lo siguiente.

Configura el entorno de desarrollo

  1. Crea un directorio nuevo para tu proyecto local.

  2. Para configurar un entorno de desarrollo Data Connect y un IDE basado en el navegador, ejecuta el siguiente comando en el directorio nuevo que creaste.

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

    Esta secuencia de comandos intenta la instalación. El IDE instalado proporciona herramientas, incluidas extensiones de VS Code preempaquetadas, para ayudarte a administrar tu esquema y definir consultas y mutaciones que se usarán en tu aplicación.

Configura el directorio de tu proyecto

Para configurar tu proyecto local, inicializa el directorio del proyecto. En la ventana del IDE, en el panel de la izquierda, haz clic en el ícono de Firebase para abrir la IU de la extensión de VS Code de Data Connect:

  1. Haz clic en el botón Acceder con Google.
  2. Haz clic en el botón Conectar un proyecto de Firebase y selecciona el proyecto que creaste anteriormente en la consola.
  3. Haz clic en el botón Run firebase init.

  4. Haz clic en el botón Start emulators.

Crea un esquema

En el directorio de tu proyecto de Firebase, en el archivo /dataconnect/schema/schema.gql, comienza a definir un esquema de GraphQL sobre, por ejemplo, reseñas de películas.

Usa Gemini Code Assist para compilar un esquema

Para crear un esquema de app de reseñas de películas con Gemini Code Assist, haz lo siguiente:

  1. Haz clic en el ícono de la extensión Data Connect de VS Code para abrir su barra lateral.
  2. Haz clic en Build your schema and queries with AI. Se abrirá la ventana de chat de Gemini Code Assist.
  3. En la parte inferior de la ventana de chat, asegúrate de que el modo Agente esté activado.
  4. Haz clic en el cuadro de chat que se encuentra en la parte inferior de la ventana de chat y comienza a escribir una descripción en lenguaje natural del tipo de app que estás creando.
  5. Presiona Intro y Gemini mostrará el comando del servidor de MCP que ejecutará para comenzar a desarrollar el esquema.
  6. Haz clic en Aceptar. Después de unos segundos, aparecerá un esquema recomendado. Revisa el esquema.

  7. Para agregar el código a schema.gql, haz lo siguiente:

    1. Espera a que Gemini Code Assist te solicite el archivo que deseas actualizar.
    2. Haz clic en Aceptar para modificar el archivo o en Ver cambios antes de confirmar.

Película

En Data Connect, los campos de GraphQL se asignan a columnas. La película tiene id, title, imageUrl y genre. Data Connect reconoce los tipos de datos primitivos: String y UUID.

Copia el siguiente fragmento o quita los comentarios de las líneas correspondientes en el archivo.

# 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

Es posible que veas una definición de tipo como la siguiente. También puedes copiar el siguiente fragmento o quitar los comentarios de las líneas correspondientes en el archivo predeterminado.

# 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
}

Ten en cuenta que el campo movie se asigna a un tipo de Movie. Data Connect comprende que esta es una relación entre Movie y MovieMetadata, y la administrará por ti.

Obtén más información sobre los esquemas de Data Connect en la documentación

Agrega datos a tus tablas

En el panel del editor del IDE, verás que aparecen botones de CodeLens sobre los tipos de GraphQL en /dataconnect/schema/schema.gql. Puedes usar los botones Add data y Run (Local) para agregar datos a tu base de datos local.

Para agregar registros a las tablas Movie y MovieMetadata, haz lo siguiente:

  1. En schema.gql, haz clic en el botón Agregar datos que se encuentra sobre la declaración de tipo Movie.
    Botón Agregar datos de CodeLens para Firebase Data Connect
  2. En el archivo Movie_insert.gql que se genera, codifica de forma rígida los datos de los tres campos.
  3. Haz clic en el botón Ejecutar (local).
    Botón Run de CodeLens para Firebase Data Connect
  4. Repite los pasos anteriores para agregar un registro a la tabla MovieMetadata y proporciona el id de tu película en el campo movieId, como se te solicita en la mutación MovieMetadata_insert generada.

Para verificar rápidamente que se agregaron los datos, haz lo siguiente:

  1. De vuelta en schema.gql, haz clic en el botón Leer datos sobre la declaración de tipo Movie.
  2. En el archivo Movie_read.gql resultante, haz clic en el botón Ejecutar (local) para ejecutar la consulta.

Obtén más información sobre las mutaciones de Data Connect en la documentación

Cómo definir una consulta

Ahora, para que sea más divertido, define las consultas que necesitarás en tu aplicación. Como desarrollador, estás acostumbrado a escribir consultas en SQL en lugar de consultas en GraphQL, por lo que esto puede parecer un poco diferente al principio.

Sin embargo, GraphQL es mucho más conciso y seguro en cuanto a tipos que el SQL sin procesar. Además, nuestra extensión de VS Code facilita la experiencia de desarrollo, tanto para las consultas como para las mutaciones.

Para crear una consulta con Gemini Code Assist, sigue estos pasos:

  1. Haz clic en el ícono de la extensión Data Connect de VS Code para abrir su barra lateral.
  2. Haz clic en Build your schema and queries with AI. Se abrirá la ventana de chat de Gemini Code Assist.
  3. En la parte inferior de la ventana de chat, asegúrate de que el modo Agente esté activado.
  4. Haz clic en el cuadro de chat que se encuentra en la parte inferior de la ventana de chat y comienza a escribir una descripción en lenguaje natural del tipo de operación que deseas desarrollar.
  5. Presiona Intro y Gemini mostrará el comando del servidor de MCP que ejecutará para comenzar a desarrollar la operación.
  6. Haz clic en Aceptar. Después de unos segundos, aparecerá una consulta recomendada. Revisa la búsqueda.

  7. Para agregar el código a queries.gql, haz lo siguiente:

    1. Espera a que Gemini Code Assist te solicite el archivo que deseas actualizar.
    2. Haz clic en Aceptar para modificar el archivo o en Ver cambios antes de confirmar.

Ejecuta la consulta con el botón de CodeLens cercano.

Obtén más información sobre las consultas de Data Connect en la documentación

Genera SDKs y úsalos en tu app

En el panel izquierdo del IDE, haz clic en el ícono de Firebase para abrir la IU de la extensión de VS Code de Data Connect:

  1. Haz clic en el botón Add SDK to app.

  2. En el diálogo que aparece, selecciona un directorio que contenga el código de tu app. Allí se generará y guardará el código del SDK de Data Connect.

  3. Selecciona la plataforma de tu app y, luego, observa que el código del SDK se genera de inmediato en el directorio seleccionado.

Usa los SDKs para llamar a tu búsqueda desde una app

Puedes usar el SDK que generó Data Connect para implementar una llamada a tu consulta de ListMovies. Luego, puedes ejecutar esta consulta de forma local con el emulador Data Connect.

Web

  1. Agrega Firebase a tu app web.

  2. En el archivo principal de tu app de React, haz lo siguiente:

    • Importa el SDK generado
    • Instrumenta tu app para que se conecte al emulador de Data Connect
    • Llama a los 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. Agrega Firebase a tu app para iOS.

  2. Para usar el SDK generado, configúralo como una dependencia en Xcode.

    En la barra de navegación superior de Xcode, selecciona File > Add Package Dependencies > Add Local y elige la carpeta que contiene el Package.swift generado.

  3. En el delegado principal de tu app, haz lo siguiente:

    • Importa el SDK generado
    • Instrumenta tu app para que se conecte al emulador de Data Connect
    • Llama a los 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. Agrega Firebase a tu app para Android.

  2. Para usar el SDK generado, configura Data Connect como una dependencia en Gradle.

    Actualiza plugins y dependencies en tu 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. En la actividad principal de tu app, haz lo siguiente:

    • Importa el SDK generado
    • Instrumenta tu app para que se conecte al emulador de Data Connect
    • Llama a los 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. Agrega Firebase a tu app de Flutter.
  2. Instala la CLI de FlutterFire dart pub global activate flutterfire_cli.
  3. Ejecuta flutterfire configure.
  4. En la función principal de tu app, haz lo siguiente:
    • Importa el SDK generado
    • Instrumenta tu app para que se conecte al emulador de Data Connect
    • Llama a los 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();
            }),
      )
    ])));
  }
}

Implementa tu esquema y tu consulta en producción

Una vez que hayas configurado tu app de forma local, podrás implementar tu esquema y conector en la nube. Necesitas un proyecto con el plan Blaze para configurar una instancia de Cloud SQL.

  1. Navega a la sección Data Connect de la consola de Firebase y crea una instancia de prueba gratuita de Cloud SQL.

  2. En la terminal integrada en el IDE, ejecuta firebase init dataconnect y selecciona el ID de región o servicio que acabas de crear en la consola.

  3. Selecciona "Y" cuando se te solicite "File dataconnect/dataconnect.yaml already exists, Overwrite?".

  4. En la ventana del IDE, en la IU de la extensión de VS Code, haz clic en el botón Deploy to production.

  5. Una vez que se implemente, ve a la consola de Firebase para verificar que el esquema, las operaciones y los datos se hayan subido a la nube. También deberías poder ver el esquema y ejecutar tus operaciones en la consola. La instancia de Cloud SQL para PostgreSQL se actualizará con el esquema y los datos generados finales implementados.

Próximos pasos

Revisa tu proyecto implementado y descubre más herramientas:

  • Agrega datos a tu base de datos, inspecciona y modifica tus esquemas, y supervisa tu servicio de Data Connect en la consola de Firebase.

Accede a más información en la documentación. Por ejemplo, como completaste la guía de inicio rápido: