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:

Configurare la directory del progetto Firebase SQL Connect locale con VS Code e l'interfaccia a riga di comando di Firebase.
Generare schemi, query e mutazioni SQL Connect in base alle idee delle tue app in linguaggio naturale.
Utilizzare gli SDK con tipi sicuri nelle tue app per eseguire SQL Connect query e mutazioni.
Eseguire 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 locali per SQL Connect in due modi.

In una directory del progetto, esegui il seguente comando.

Lo script installa l'interfaccia a riga di comando di Firebase e l' estensione SQL 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
```
Apri la schermata dell'estensione SQL Connect VS Code 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.

Esaminare lo schema

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

Sviluppare query e mutazioni

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

Esaminare query e mutazioni

Nella configurazione predefinita, puoi trovare le SQL Connect query e le mutazioni in 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 }
    }
  }
}

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

Per proteggere la tua app, le app web e mobile possono accedere a SQL Connect query e mutazioni con @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 SQL Connect Scopri di più sulle mutazioni SQL Connect Scopri di più su SQL Connect Authentication

Generare query e mutazioni

Non devi essere un esperto di GraphQL per utilizzare SQL Connect in modo efficace. Puoi generare SQL 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 Code Lens Genera/Perfeziona operazione per generare l'operazione GraphQL.

Pulsante Genera di CodeLens per Firebase SQL
Connect

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 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 l'app per connetterti all'SQL Connect emulatore:

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

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 l'app per connetterti all'SQL 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: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 dell'app:

Recupera un'istanza del connettore dall'SDK generato:

private val connector = com.myapplication.MoviesConnector.instance

Strumenta l'app per connetterti all'SQL 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 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 l'interfaccia a riga di comando 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 l'app per connetterti all'SQL 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 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();
            }),
      )
    ])));
  }
}

Eseguire il deployment 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 Firebase SQL Connect opzioni di prova.
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 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 funziona SQL Connect 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 Connectcompleta 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 SQL 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 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.