Inizia a utilizzare Firebase SQL Connect

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

• Configura la directory del progetto Firebase SQL Connect locale con VS Code e l'interfaccia a riga di comando Firebase.
• Genera schemi, query e mutazioni SQL Connect in base alle tue idee per le app in linguaggio naturale.
• Utilizza gli SDK con tipizzazione forte nelle tue app per eseguire query e mutazioni SQL Connect.
• Eseguire il provisioning di un'istanza Cloud SQL per PostgreSQL, di uno schema SQL Connect, di query e di mutazioni.

Configura la directory del progetto locale

Puoi installare gli strumenti per sviluppatori locali per SQL Connect in due modi.

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

1. In una directory del progetto, esegui questo comando.

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

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

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

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

Rivedi lo schema

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

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

Sviluppa query e mutazioni

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

Inserisci dati nel tuo 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 CodeLens Esegui (locale) in VS Code per eseguire le mutazioni e compilare il database PGlite locale.

Esamina query e mutazioni

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

Puoi eseguire query sui dati relazionali con precisione utilizzando 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 }
    }
  }
}

SQL 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 alle query e alle mutazioni SQL Connect con le istruzioni @auth. Le query e le 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 SQL Connect Scopri di più sulle mutazioni SQL Connect Scopri di più sull'autenticazione SQL Connect

Genera query e mutazioni

Non è necessario essere un esperto di GraphQL per utilizzare SQL Connect in modo efficace. Puoi generare query e mutazioni SQL Connect 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 CodeLens Genera/Perfeziona operazione per generare l'operazione GraphQL.

Suggerimento: Operation Generation è disponibile anche nella console Firebase e nel server Firebase MCP.

Utilizza l'SDK generato nella tua app

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

Web

1. Aggiungi Firebase alla tua app web.

2. Nel file principale della tua 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 connetterti all'emulatore SQL Connect:

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

   • Chiama i metodi SQL 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. SQL Connect fornisce anche associazioni speciali per lavorare con SQL Connect in modo asincrono in React.

Swift

1. Aggiungi Firebase alla tua app iOS.

2. Per utilizzare l'SDK generato, configuralo 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 SQL 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 connetterti all'emulatore SQL 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 SQL 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 SQL Connect come dipendenza in Gradle.

   Aggiorna plugins e dependencies nel tuo 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 la tua app per connetterti all'emulatore SQL 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 SQL 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 connetterti all'emulatore SQL 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 SQL 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. Esamina le informazioni sui prezzi e sulla prova senza costi nella pagina Prezzi. Il tuo progetto potrebbe essere idoneo per una delle opzioni di prova di Firebase SQL Connect.

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

   firebase deploy --only dataconnect
   

   Dopo il deployment, puoi visualizzare lo schema ed eseguire query e mutazioni nella console Firebase (vai a Database e spazio di archiviazione > SQL Connect).

   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 SQL 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 SQL Connect completa seguendo il nostro codelab per il web, il codelab per iOS o il codelab per Android.
• Aggiungi dati al database, ispeziona gli schemi e monitora il servizio SQL Connect nella console Firebase.
• Configura il server MCP Firebase con strumenti per sviluppatori basati sull'AI come Antigravity, Claude Code o Cursor.
• Scopri di più sullo sviluppo di schema, query e mutation.
• Scopri di più su come SQL Connect gestisce lo schema PostgreSQL.
• Scopri di più sugli SDK client per web, Android, iOS e Flutter, nonché sugli SDK Admin per Node.js.