Inizia a utilizzare Firebase Data Connect

Questa guida rapida ti consente di iniziare a utilizzare Firebase Data Connect per connettere le tue app web e mobile a un database PostgreSQL. Imparerai a:

• Configurare la directory del progetto Firebase Data Connect locale con VS Code e l'interfaccia a riga di comando di Firebase.
• Generare schemi, query e mutazioni Data Connect in base alle idee delle tue app in linguaggio naturale.
• Utilizzare gli SDK con tipi sicuri nelle tue app per eseguire Data Connect query e mutazioni.
• Eseguire il provisioning di un'istanza Cloud SQL per PostgreSQL, uno schema Data Connect, query e mutazioni.

Configurare la directory del progetto locale

Puoi installare gli strumenti di sviluppo locali per Data Connect in due modi.

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

1. In una directory del progetto, esegui il seguente comando.

   Lo script installa l'interfaccia a riga di comando di Firebase e l' estensione Data Connect VS Code e ti guida attraverso firebase init dataconnect per configurare il progetto. Se non hai installato VS Code desktop, lo script lo apre in un browser.

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

2. Apri la schermata dell'estensione Data Connect VS Code facendo clic sull'icona di Firebase nel riquadro a sinistra di Visual Studio Code.

3. Fai clic su Avvia emulatori per eseguire l'emulatore con un database PGlite locale.

Esaminare lo schema

Firebase Data Connect utilizza GraphQL per definire il modello di dati. La @table direttiva mappa un tipo GraphQL a una tabella PostgreSQL. I campi nel tipo di mappa alle colonne PostgreSQL. Puoi definire le relazioni tra le tabelle utilizzando i campi che fanno riferimento ad altri tipi @table, incluse le relazioni many-to-many utilizzando le tabelle di join con chiavi primarie composite.

Nella configurazione predefinita, puoi trovare i file di schema Data Connect in la directory dataconnect/schema/. Ecco due tabelle di esempio dallo schema del modello di film. Lo schema potrebbe essere diverso se hai utilizzato Gemini per generarlo.

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

Scopri di più sugli schemi Data Connect

Sviluppare query e mutazioni

Firebase Data Connect utilizza GraphQL per query e mutazioni. Questi vengono definiti nei file .gql e chiamati per nome dall'app. La sintassi GraphQL fornisce SDK con tipi sicuri e un'API flessibile per recuperare i dati esatti di cui la tua app ha bisogno.

Inserire dati nel database

Con l'emulatore in esecuzione, puoi inserire i dati iniziali. Puoi utilizzare il file dataconnect/seed_data.gql fornito o scrivere le tue mutazioni.

Utilizza il pulsante Esegui (locale) Code Lens in VS Code per eseguire le mutazioni e popolare il database PGlite locale.

Esaminare query e mutazioni

Nella configurazione predefinita, puoi trovare le Data Connect query e le mutazioni nella dataconnect/example/ directory.

Puoi eseguire query sui dati relazionali con precisione utilizzando le query nidificate.

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

Data Connect ti aiuta a creare query e mutazioni sicure con Firebase Authentication.

Per proteggere la tua app, le app web e mobile possono accedere alle Data Connect query e mutazioni solo con le @auth direttive. Le query e le mutazioni possono accedere in modo sicuro all'UID di Firebase Authentication utilizzando un'espressione come {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
    }
  )
}

Scopri di più sulle query Data Connect Scopri di più sulle mutazioni Data Connect Scopri di più su Data Connect Authentication

Generare query e mutazioni

Non è necessario essere esperti di GraphQL per utilizzare Data Connect in modo efficace. Puoi generare Data Connect query e mutazioni da descrizioni in linguaggio naturale.

In qualsiasi file .gql, digita # per iniziare un commento e descrivere una query o una mutazione. Poi, utilizza il pulsante Genera/Perfeziona operazione Code Lens per generare l'operazione GraphQL.

**Suggerimento:** la generazione di operazioni è disponibile anche in Firebase Console e nel server Firebase MCP.

Utilizzare l'SDK generato nell'app

firebase init dataconnect configura automaticamente gli SDK con tipi sicuri per le app nel tuo progetto. Se necessario, puoi aggiungere l'SDK manualmente con il pulsante Aggiungi SDK all' app nell'estensione Data Connect VS Code o eseguendo firebase init dataconnect:sdk.

Web

1. Aggiungi Firebase alla tua app web.

2. Nel file principale dell'app React:

   • Importa l'SDK generato:

   // Update as needed with the path to your generated SDK.
   import { listMovies, ListMoviesData } from '@dataconnect/generated';
   

   • Strumenta l'app per connetterti all'Data Connect emulatore:

   import { connectDataConnectEmulator } from 'firebase/data-connect';
   
   const dataConnect = getDataConnect(connectorConfig);
   connectDataConnectEmulator(dataConnect, 'localhost', 9399);
   

   • Chiama i metodi 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 />);
   

   Nota: in questo esempio, l'app React chiama la query utilizzando l'SDK Firebase JavaScript. Data Connect fornisce anche binding speciali per lavorare con Data Connect in modo asincrono in React.

Swift

1. Aggiungi Firebase alla tua app iOS.

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

   Nella barra di navigazione in alto 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 dell'app:

   • Importa l'SDK Data Connect e l'SDK generato:

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

   • Strumenta l'app per connetterti all'Data Connect emulatore:

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

   • Chiama i metodi: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. 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 dell'app:

   • Recupera un'istanza del connettore dall'SDK generato:

   private val connector = com.myapplication.MoviesConnector.instance
   

   • Strumenta l'app per connetterti all'Data Connect emulatore:

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

   • Chiama i metodi 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. 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:

   // Generated queries.
   // Update as needed with the path to your generated SDK
   
   import 'movies_connector/movies.dart';
   

   • Strumenta l'app per connetterti all'Data Connect emulatore:

   void main() async {
     WidgetsFlutterBinding.ensureInitialized();
     await Firebase.initializeApp(
       options: DefaultFirebaseOptions.currentPlatform,
     );
     
     MoviesConnector.instance.dataConnect
         .useDataConnectEmulator(Uri.base.host, 443, isSecure: true);
     
     runApp(const MyApp());
   }
   

   • Chiama i metodi 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();
               }),
         )
       ])));
     }
   }
   

Eseguire il deployment in produzione

Per eseguire il deployment di schema, query e mutazioni in produzione:

1. Esamina le informazioni sui prezzi e sulla prova senza costi nella pagina Prezzi. Il tuo progetto potrebbe avere diritto a una delle Firebase Data Connect opzioni di prova.

2. Fai clic sul pulsante Esegui il deployment in produzione nell'estensione Data Connect VS Code o esegui in un terminale:

   firebase deploy --only dataconnect
   

   Dopo il deployment, visita la Firebase console per visualizzare lo schema ed eseguire query e mutazioni.

   Suggerimento: puoi configurare la regione Cloud SQL, il nome dell'istanza e il nome del database PostgreSQL in dataconnect.yaml prima del deployment.

Scopri di più su dataconnect.yaml Scopri di più su come Data Connect funziona con Cloud SQL

Passaggi successivi

Ora che hai completato la guida rapida, ecco alcuni passaggi successivi:

• Esplora un repository di app di avvio rapido e crea un'app completa Data Connect seguendo il nostro codelab per il web, codelab per iOS, o codelab per Android.
• Aggiungi dati al database, esamina gli schemi e monitora il servizio Data Connect nella Firebase console.
• Configura il server Firebase MCP con strumenti di sviluppo basati sull'AI come Gemini Code Assist.
• Scopri di più sullo sviluppo di schemi, query e mutazioni.
• Scopri di più su come Data Connect gestisce lo schema PostgreSQL.
• Scopri di più sugli SDK client per web, Android, iOS e Flutter, nonché sugli SDK Admin per Node.js.