Inizia a utilizzare Firebase Data Connect localmente

Nota: segui questa guida rapida locale se vuoi provare Data Connect con un progetto con piano Spark. In questa guida, creerai un prototipo localmente con un emulatore e un database locale. Se invece vuoi aggiungere Data Connect a un progetto con piano Blaze e configurare un servizio e un database Cloud SQL, prova la guida introduttiva alla produzione.

In questa guida rapida imparerai a creare Firebase Data Connect nella tua applicazione localmente senza configurare un'istanza SQL di produzione. Imparerai a:

• Aggiungi Firebase Data Connect al tuo progetto Firebase.
• Configura un ambiente di sviluppo che includa le estensioni di Visual Studio Code per utilizzare un'istanza locale.
• Poi ti mostreremo come:
  • Utilizza gli strumenti di estensione VS Code, con Gemini Code Assist, per:
    • Crea uno schema per un'app
    • Crea query e mutazioni amministrative per popolare il database locale
    • Aiutarti a implementare query e mutazioni per la tua app in un connettore distribuibile
  • Testa le query e le mutazioni con dati di esempio rispetto a un emulatore locale
  • Genera SDK fortemente tipizzati e utilizzali nella tua app
  • Esegui il deployment dello schema e del connettore finali sul cloud (facoltativo, con un upgrade del piano Blaze).

Esplora un repository di app di avvio rapido e crea un'app Data Connect completa seguendo il nostro codelab per il web, il codelab per iOS o il codelab per Android.

Scegli un flusso di sviluppo locale

Data Connect ti offre due modi per installare gli strumenti di sviluppo e lavorare in locale.

Installazione automatica (macOS o Linux) Installazione manuale (Windows)

Prerequisiti

Per utilizzare questa guida rapida, devi disporre di quanto segue.

• Un progetto Firebase. Se non ne hai ancora creato uno, fallo nella console Firebase.

Configura l'ambiente di sviluppo

1. Crea una nuova directory per il progetto locale.

2. Per configurare un ambiente di sviluppo Data Connect e un IDE basato su browser, esegui questo comando nella nuova directory che hai creato.

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

   Questo script tenta l'installazione. L'IDE installato fornisce strumenti, tra cui estensioni VS Code pre-incluse, per aiutarti a gestire lo schema e definire query e mutazioni da utilizzare nella tua applicazione.

Nota: se hai già installato la versione desktop di VS Code, lo script la aprirà automaticamente.

Nota: se lo script non funziona, utilizza i passaggi per l'installazione manuale.

Configurare la directory del progetto

Per configurare il progetto locale, inizializza la directory del progetto. Nella finestra IDE, nel riquadro a sinistra, fai clic sull'icona di Firebase per aprire l'interfaccia utente dell'estensione Data Connect VS Code:

1. Fai clic sul pulsante Accedi con Google.
2. Fai clic sul pulsante Collega un progetto Firebase e seleziona il progetto che hai creato in precedenza nella console.
3. Fai clic sul pulsante Esegui firebase init.

4. Fai clic sul pulsante Avvia emulatori.

   Nota :nel terminale integrato, verifica che gli emulatori configurati vengano avviati. Una volta in esecuzione, dovresti visualizzare l'aggiornamento dell'interfaccia utente dell'estensione con i dettagli dell'emulatore.

Crea uno schema

Nella directory del progetto Firebase, nel file /dataconnect/schema/schema.gql, inizia a definire uno schema GraphQL, ad esempio, sulle recensioni di film.

Utilizzare Gemini Code Assist per creare uno schema

Per creare uno schema di app per recensioni di film utilizzando Gemini Code Assist:

1. Fai clic sull'icona dell'estensione Data Connect VS Code per aprire la relativa barra laterale.
2. Fai clic su Prova Gemini con @FirebaseDataConnect. Si apre la finestra della chat Gemini Code Assist.
3. Fai clic sull'interfaccia di chat e inizia a digitare @FirebaseDataConnect per filtrare i comandi pertinenti.

4. Seleziona il comando /generate_schema e, al prompt, completa il comando chiedendo a Gemini di creare uno schema per l'app che stai sviluppando.

   Ad esempio:

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

5. Dopo qualche istante, viene visualizzato uno schema consigliato. Rivedi lo schema.

   Nota: se vuoi modificare lo schema iniziale, puoi eseguire un nuovo comando @FirebaseDataConnect /generate_schema e chiedere a Gemini, ad esempio, di rimuovere un tipo dallo schema o di aggiungere campi specifici a un tipo.

6. Per aggiungere il codice a schema.gql:

   1. Fai clic sul pulsante Inserisci in fondo al file.
   2. In alternativa, per inserire il codice nella posizione del cursore, fai clic sul pulsante + nella parte superiore della risposta della chat.

Film

Nota :lo schema è univoco per l'app che hai descritto a Gemini Code Assist. Negli esempi seguenti, i nomi delle tabelle e i campi possono variare in base al modo in cui hai formulato il prompt.

In Data Connect, i campi GraphQL vengono mappati alle colonne. Il film ha id, title, imageUrl e genre. Data Connect riconosce i tipi di dati primitivi: String e UUID.

Copia il seguente snippet o rimuovi il commento dalle righe corrispondenti nel file.

# 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

Copia il seguente snippet o rimuovi il commento dalle righe corrispondenti nel file.

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

Tieni presente che il campo movie è mappato a un tipo di Movie. Data Connect comprende che si tratta di un rapporto tra Movie e MovieMetadata e lo gestirà per tuo conto.

Scopri di più sugli schemi di Data Connect nella documentazione

Aggiungere dati alle tabelle

Nel riquadro dell'editor IDE, sopra i tipi GraphQL in /dataconnect/schema/schema.gql verranno visualizzati i pulsanti CodeLens. Puoi utilizzare i pulsanti Aggiungi dati e Esegui (locale) per aggiungere dati al database locale.

Per aggiungere record alle tabelle Movie e MovieMetadata:

1. In schema.gql, fai clic sul pulsante Aggiungi dati sopra la dichiarazione del tipo Movie.
   
2. Nel file Movie_insert.gql generato, codifica in modo permanente i dati per i tre campi.
3. Fai clic sul pulsante Esegui (locale).
   
4. Ripeti i passaggi precedenti per aggiungere un record alla tabella MovieMetadata, fornendo il id del tuo film nel campo movieId, come richiesto nella mutazione MovieMetadata_insert generata.

Per verificare rapidamente che i dati siano stati aggiunti:

1. In schema.gql, fai clic sul pulsante Leggi dati sopra la dichiarazione del tipo Movie.
2. Nel file Movie_read.gql risultante, fai clic sul pulsante Esegui (locale) per eseguire la query.

Scopri di più sulle mutazioni di Data Connect nella documentazione

Definire una query

Ora passiamo alla parte più divertente: definisci le query di cui avrai bisogno nella tua applicazione. In qualità di sviluppatore, sei abituato a scrivere query SQL anziché query GraphQL, quindi all'inizio potrebbe sembrarti un po' diverso.

Nota: questa sezione descrive la creazione di una query, ma il flusso si applica anche alle mutazioni.

Tuttavia, GraphQL è molto più conciso e sicuro dal punto di vista dei tipi rispetto a SQL non elaborato. Inoltre, la nostra estensione VS Code semplifica l'esperienza di sviluppo, sia per le query che per le mutazioni.

Per creare una query utilizzando Gemini Code Assist:

1. Fai clic sull'icona dell'estensione Data Connect VS Code per aprire la relativa barra laterale.
2. Fai clic su Prova Gemini con @FirebaseDataConnect. Si apre la finestra della chat Gemini Code Assist.
3. Fai clic sull'interfaccia di chat e inizia a digitare @FirebaseDataConnect per filtrare i comandi pertinenti.

4. Seleziona il comando /generate_operation e, al prompt, completa il comando chiedendo a Gemini di creare una query.

   Ad esempio:

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

5. Dopo qualche istante, viene visualizzata una query consigliata. Esamina la query.

   Nota: se vuoi modificare la query iniziale, puoi eseguire un nuovo comando @FirebaseDataConnect /generate_operation e chiedere a Gemini, ad esempio, di filtrare i titoli che iniziano con cifre numeriche. In alternativa, chiedi di creare più mutazioni con un'istruzione come "Genera una mutazione per tutti i miei tipi di schema".

6. Per aggiungere il codice a queries.gql:

   1. Fai clic sul pulsante Inserisci in fondo al file.
   2. In alternativa, per inserire il codice nella posizione del cursore, fai clic sul pulsante + nella parte superiore della risposta della chat.

Esegui la query utilizzando il pulsante CodeLens nelle vicinanze.

Scopri di più sulle query Data Connect nella documentazione

Generare SDK e utilizzarli nella tua app

Nel riquadro a sinistra dell'IDE, fai clic sull'icona di Firebase per aprire l'interfaccia utente dell'estensione Data Connect VS Code:

1. Fai clic sul pulsante Aggiungi SDK all'app.

2. Nella finestra di dialogo visualizzata, seleziona una directory contenente il codice per la tua app. Data Connect Il codice SDK verrà generato e salvato qui.

   Nota: se non hai ancora una directory di app, puoi creare e selezionare una nuova directory per il codice SDK per ora e collegarla alla tua app in un secondo momento.

3. Seleziona la piattaforma dell'app, quindi tieni presente che il codice SDK viene generato immediatamente nella directory selezionata.

Utilizzare gli SDK per chiamare la query da un'app

Puoi utilizzare l'SDK generato da Data Connect per implementare una chiamata alla query ListMovies. Puoi quindi eseguire questa query localmente utilizzando l'emulatore Data Connect.

Web

1. Aggiungi Firebase alla tua app web.

2. Nel file principale dell'app React:

   • importa l'SDK generato
   • strumentare l'app per connettersi all'emulatore Data Connect
   • chiama i metodi Data Connect.
   Nota: in questo esempio, l'app React chiama la query utilizzando l'SDK Firebase JavaScript. Data Connect fornisce anche binding speciali per utilizzare Data Connect in modo asincrono in React.

   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. Aggiungi Firebase alla tua app iOS.

2. Per utilizzare l'SDK generato, configuralo come dipendenza in Xcode.

   Nella barra di navigazione superiore di Xcode, seleziona File > Add Package Dependencies > Add Local (File > Aggiungi dipendenze pacchetto > Aggiungi locale) e scegli la cartella contenente il file Package.swift generato.

3. Nel delegato principale della tua app:

   • importa l'SDK generato
   • strumentare l'app per connettersi all'emulatore Data Connect
   • chiama i metodi 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. Aggiungi Firebase alla tua app Android.

2. Per utilizzare l'SDK generato, configura Data Connect come dipendenza in Gradle.

   Aggiorna plugins e dependencies in 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. Nell'attività principale della tua app:

   • importa l'SDK generato
   • strumentare l'app per connettersi all'emulatore Data Connect
   • chiama i metodi 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. Aggiungi Firebase alla tua app Flutter.
2. Installa l'interfaccia a riga di comando FlutterFire dart pub global activate flutterfire_cli.
3. Esegui flutterfire configure.
4. Nella funzione principale dell'app:
   • importa l'SDK generato
   • strumentare l'app per connettersi all'emulatore Data Connect
   • chiama i metodi 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();
            }),
      )
    ])));
  }
}

Esegui il deployment dello schema e della query in produzione

Una volta configurata l'app in locale, puoi eseguire il deployment dello schema e del connettore nel cloud. Per configurare un'istanza Cloud SQL, devi avere un progetto con piano Blaze.

1. Vai alla sezione Data Connect della console Firebase e crea un'istanza Cloud SQL di prova senza costi.

   Nota: il provisioning dell'istanza Cloud SQL per PostgreSQL può richiedere fino a 15 minuti. Non potrai eseguire il deployment finché l'istanza non sarà pronta.
   Nota: se vuoi utilizzare chiavi di crittografia gestite dal cliente (CMEK), assicurati di scegliere Utilizza l'istanza Cloud SQL esistente e seleziona un database Cloud SQL esistente con CMEK.

2. Nel terminale integrato nell'IDE, esegui firebase init dataconnect e seleziona l'ID regione/servizio che hai appena creato nella console.

3. Seleziona "Y" quando ti viene chiesto "File dataconnect/dataconnect.yaml already exists, Overwrite?".

4. Nella finestra dell'IDE, nell'interfaccia utente dell'estensione VS Code, fai clic sul pulsante Esegui il deployment in produzione.

5. Una volta eseguito il deployment, vai alla console Firebase per verificare che lo schema, le operazioni e i dati siano stati caricati nel cloud. Dovresti essere in grado di visualizzare lo schema ed eseguire le operazioni anche nella console. L'istanza Cloud SQL per PostgreSQL verrà aggiornata con lo schema e i dati generati e implementati finali.

Passaggi successivi

Esamina il progetto di cui è stato eseguito il deployment e scopri altri strumenti:

• Aggiungi dati al tuo database, esamina e modifica gli schemi e monitora il tuo servizio Data Connect nella console Firebase.

Accedi a ulteriori informazioni nella documentazione. Ad esempio, dato che hai completato la guida rapida:

• Scopri altri strumenti e indicazioni di assistenza AI per aiutarti a generare schemi, query e mutazioni. La guida all'assistenza AI spiega come configurare e utilizzare il nostro server MCP con i tuoi IDE e le best practice per scrivere prompt.
• Scopri di più sullo sviluppo di schema, query e mutazione
• Scopri di più sulla generazione di SDK client e sulle chiamate di query e mutazioni dal codice client per web, Android, iOS e Flutter.