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 locale Firebase SQL Connect con VS Code e l'interfaccia a riga di comando di Firebase.
Genera schemi, query e mutazioni SQL Connect in base alle tue idee per app in linguaggio naturale.
Utilizza gli SDK fortemente tipizzati nelle tue app per eseguire SQL Connect query e mutazioni.
Esegui il provisioning di un'istanza Cloud SQL per PostgreSQL, uno schema SQL Connect, query e mutazioni.

Configurare la directory del progetto locale

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

In una directory di progetto, esegui questo comando.

Lo script installa l'interfaccia a riga di comando di Firebase e l'estensione VS Code SQL Connect 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
```
Apri la schermata dell'estensione VS Code di SQL Connect facendo clic sull'icona di Firebase nel riquadro a sinistra di Visual Studio Code.
Fai clic su Avvia emulatori per eseguire l'emulatore con un database PGlite locale.

Rivedi schema

Firebase SQL 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 SQL 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 SQL Connect

Sviluppare query e mutazioni

Firebase SQL 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 di CodeLens per Firebase SQL
Connect

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

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 a query e mutazioni SQL 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 SQL Connect Scopri di più sulle mutazioni SQL Connect Scopri di più sull'autenticazione SQL Connect

Generare query e mutazioni

Non è necessario essere esperti di GraphQL per utilizzare SQL Connect in modo efficace. Puoi generare query e mutazioni SQL Connect dalle 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 di CodeLens per Firebase SQL
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 SQL Connect VS Code o eseguendo firebase init dataconnect:sdk.

Web

Aggiungi Firebase alla tua app web.

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

Swift

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

Nel delegato principale della tua 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 connetterla 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

Aggiungi Firebase alla tua app Android.

Per utilizzare l'SDK generato, configura SQL 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")
}

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

Aggiungi Firebase alla tua app Flutter.
Installa la CLI flutterfire dart pub global activate flutterfire_cli.
Esegui flutterfire configure.

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

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.
Fai clic sul pulsante Esegui il deployment in produzione nell'estensione SQL Connect VS Code 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.

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 tuo database, esamina gli schemi e monitora il servizio SQL Connect nella console Firebase.
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 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.