Inizia a utilizzare Firebase Data Connect

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

  • Configura la directory del progetto Firebase Data Connect locale con VS Code e l'interfaccia a riga di comando di Firebase.
  • Genera schemi, query e mutazioni Data Connect in base alle tue idee per app in linguaggio naturale.
  • Utilizza gli SDK fortemente tipizzati nelle tue app per eseguire Data Connect query e mutazioni.
  • Esegui il provisioning di un'istanza Cloud SQL per PostgreSQL, uno schema Data Connect, query e mutazioni (richiede un piano Blaze).

Configurare la directory del progetto locale

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

  1. Installa i seguenti prerequisiti:

  2. Crea una directory di progetto e aprila in Visual Studio Code.

  3. Installa l'estensione Firebase Data Connect da VS Code Marketplace.

  4. Fai clic sul pulsante Accedi con Google.

  5. Fai clic sul pulsante Collega un progetto Firebase.

  6. Fai clic sul pulsante Esegui firebase init.

  7. Fai clic sul pulsante Avvia emulatori per eseguire l'emulatore Data Connect con un database PGlite locale.

Schema di revisione

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

Nella configurazione predefinita, puoi trovare i file di schema Data Connect nella directory dataconnect/schema/. Ecco due tabelle di esempio dello schema del modello di film. Il tuo 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 di Data Connect

Sviluppare query e mutazioni

Firebase Data Connect utilizza GraphQL per query e mutazioni. Definisci questi elementi nei file .gql e li richiami per nome dalla tua app. La sintassi GraphQL fornisce SDK fortemente tipizzati e un'API flessibile per recuperare i dati esatti di cui la tua app ha bisogno.

Dati iniziali nel database

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

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

Pulsante Esegui CodeLens per Firebase Data Connect

Esamina query e mutazioni

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

Puoi eseguire query sui dati relazionali in modo preciso con 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 Auth.

Per proteggere la tua app, le app web e mobile possono accedere solo a query e mutazioni Data Connect con direttive @auth. Query e mutazioni possono accedere in modo sicuro all'UID di Firebase Auth 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 Auth

Generare query e mutazioni

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

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

Pulsante Genera CodeLens per Firebase Data Connect

Utilizzare l'SDK generato nella tua app

firebase init dataconnect configura automaticamente gli SDK sicuri per il tipo per le app nel tuo progetto. Se necessario, puoi aggiungere l'SDK manualmente con il pulsante Aggiungi SDK all'app nell'estensione 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 la tua app per connetterla all'emulatore Data Connect:
    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 />);

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 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 la tua app per connetterla all'emulatore 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)

    • 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 della tua app:

    • Recupera un'istanza del connettore dall'SDK generato:
    private val connector = com.myapplication.MoviesConnector.instance
    • Strumenta la tua app per connetterla all'emulatore 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)
  }
    • 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 la tua app per connetterla all'emulatore 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());
}
    • 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();
            }),
      )
    ])));
  }
}

Distribuzione in produzione

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

  1. Esegui l'upgrade del progetto Firebase per utilizzare il piano Blaze.

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

    firebase deploy --only dataconnect

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

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: