איך מתחילים להשתמש ב-Firebase SQL Connect

במדריך למתחילים הזה נסביר איך להתחיל להשתמש ב-Firebase SQL Connect כדי לחבר את האפליקציות שלכם לאינטרנט ולנייד למסד נתונים של PostgreSQL. אתם:

  • מגדירים את ספריית הפרויקט המקומית של Firebase SQL Connect באמצעות VS Code ו-CLI של Firebase.
  • ליצור סכימות, שאילתות ומוטציות של SQL Connect על סמך רעיונות לאפליקציות בשפה טבעית.
  • משתמשים בערכות ה-SDK עם טיפוסים מוגדרים באפליקציות כדי להריץ שאילתות ומוטציות של SQL Connect.
  • מקצים מכונה של Cloud SQL ל-PostgreSQL, סכימה של SQL Connect, שאילתות ומוטציות.

הגדרת ספריית הפרויקט המקומית

יש שתי דרכים להתקין כלי למפתחים מקומיים ל-SQL Connect.

  1. מריצים את הפקודה הבאה בספריית הפרויקט.

    הסקריפט מתקין את Firebase CLI ואת התוסף SQL Connect ל-VS Code, ומדריך אתכם בתהליך ההגדרה של הפרויקט ב-firebase init dataconnect. אם לא התקנתם את VS Code למחשב, הסקריפט יפתח אותו בדפדפן.

    curl -sL https://firebase.tools/init/dataconnect | editor=true bash
  2. פותחים את מסך התוסף SQL Connect VS Code בלחיצה על סמל Firebase בחלונית הימנית של Visual Studio Code.

  3. לוחצים על Start emulators כדי להפעיל את הסימולטור עם מסד נתונים מקומי של PGlite.

סכימת ביקורת

‫Firebase SQL Connect משתמש ב-GraphQL כדי להגדיר את מודל הנתונים. ההוראה @table ממפה סוג GraphQL לטבלת PostgreSQL. השדות בסוג ממופים לעמודות ב-PostgreSQL. אתם יכולים להגדיר קשרים בין טבלאות באמצעות שדות שמפנים לסוגים אחרים של @table, כולל קשרי רבים לרבים באמצעות טבלאות צירוף עם מפתחות ראשיים מורכבים.

בהגדרה שמוגדרת כברירת מחדל, קובצי הסכימה של SQL Connect נמצאים בספרייה dataconnect/schema/. הנה שתי טבלאות לדוגמה מהסכימה של תבנית הסרט. אם השתמשתם ב-Gemini כדי ליצור את הסכימה, יכול להיות שהיא תהיה שונה.

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

מידע נוסף על סכימות של SQL Connect

פיתוח שאילתות ומוטציות

‫Firebase SQL Connect משתמש ב-GraphQL לשאילתות ולמוטציות. אתם מגדירים אותן בקובצי .gql וקוראים להן לפי השם מהאפליקציה. התחביר של GraphQL מספק ערכות SDK עם סוגים מוגדרים היטב ו-API גמיש לאחזור הנתונים המדויקים שהאפליקציה צריכה.

נתוני Seed במסד הנתונים

כשהאמולטור פועל, אפשר להזין בו נתונים ראשוניים. אתם יכולים להשתמש בקובץ dataconnect/seed_data.gql שסופק או לכתוב מוטציות משלכם.

משתמשים בלחצן Run (local)‎ של Code Lens ב-VS Code כדי להריץ את המוטציות ולאכלס את מסד הנתונים המקומי של PGlite.

כפתור ההפעלה של CodeLens ל-Firebase SQL Connect

בדיקת שאילתות ומוטציות

בהגדרה שמוגדרת כברירת מחדל, אפשר למצוא את השאילתות והמוטציות של SQL Connect בספרייה dataconnect/example/.

אתם יכולים להריץ שאילתות על נתונים יחסיים בצורה מדויקת באמצעות שאילתות בתצוגת עץ.

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 עוזר לכם ליצור שאילתות ומוטציות מאובטחות באמצעות Firebase Auth.

כדי לשמור על אבטחת האפליקציה, אפליקציות לאינטרנט ולנייד יכולות לגשת רק לשאילתות ולמוטציות של SQL Connect עם ההנחיות @auth. שאילתות ומוטציות יכולות לגשת באופן מאובטח למזהה המשתמש ב-Firebase Auth באמצעות ביטוי כמו {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
    }
  )
}

מידע נוסף על שאילתות SQL Connect מידע נוסף על מוטציות SQL Connect מידע נוסף על אימות SQL Connect

יצירת שאילתות ומוטציות

אתם לא צריכים להיות מומחים ב-GraphQL כדי להשתמש ב-SQL Connect ביעילות. אתם יכולים ליצור שאילתות ומוטציות של SQL Connect מתיאורים בשפה טבעית.

בכל קובץ .gql, מקלידים # כדי להתחיל תגובה ומתארים שאילתה או מוטציה. אחר כך משתמשים בכפתור Code Lens Generate/Refine Operation כדי ליצור את פעולת GraphQL.

הכפתור Generate ב-CodeLens ל-Firebase SQL Connect

שימוש ב-SDK שנוצר באפליקציה

‫firebase init dataconnect מגדיר באופן אוטומטי ערכות SDK למניעת שגיאות הקלדה באפליקציות בפרויקט. אם צריך, אפשר להוסיף את ה-SDK באופן ידני באמצעות הכפתור Add SDK to app בתוסף SQL Connect VS Code או על ידי הפעלת firebase init dataconnect:sdk.

אינטרנט

  1. מוסיפים את Firebase לאפליקציה לאינטרנט.
  2. בקובץ הראשי של אפליקציית React:

    • מייבאים את ה-SDK שנוצר:
    // Update as needed with the path to your generated SDK.
    import { listMovies, ListMoviesData } from '@dataconnect/generated';
    
    • מגדירים את האפליקציה כך שתתחבר לאמולטור של SQL Connect:
    import { connectDataConnectEmulator } from 'firebase/data-connect';
    
    const dataConnect = getDataConnect(connectorConfig);
    connectDataConnectEmulator(dataConnect, 'localhost', 9399);
    
    • מפעילים את ה-methods של 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

  1. מוסיפים את Firebase לאפליקציה ל-iOS.
  2. כדי להשתמש ב-SDK שנוצר, צריך להגדיר אותו כתלות ב-Xcode.

    בסרגל הניווט העליון של Xcode, בוחרים באפשרות File > Add Package Dependencies > Add Local (קובץ > הוספת יחסי תלות בין חבילות > הוספת חבילה מקומית) ובוחרים את התיקייה שמכילה את קובץ ה-Package.swift שנוצר.

  3. ב-delegate הראשי של האפליקציה:

    • מייבאים את ה-SDK של SQL Connect ואת ה-SDK שנוצר:

      import FirebaseDataConnect
      // Generated queries.
      // Update as needed with the package name of your generated SDK.
      import <CONNECTOR-PACKAGE-NAME>
      
      let connector = DataConnect.moviesConnector
      
    • מגדירים את האפליקציה כך שתתחבר לאמולטור של 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)
      
    • מפעילים את השיטות של 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. מוסיפים את Firebase לאפליקציה ל-Android.
  2. כדי להשתמש ב-SDK שנוצר, צריך להגדיר את SQL Connect כתלות ב-Gradle.

    מעדכנים את plugins ו-dependencies ב-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. בפעילות העיקרית של האפליקציה:

    • מקבלים מופע של מחבר מה-SDK שנוצר:
    private val connector = com.myapplication.MoviesConnector.instance
    
    • מגדירים את האפליקציה כך שתתחבר לאמולטור של 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)
      }
    
    • מפעילים את ה-methods של 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. מוסיפים את Firebase לאפליקציית Flutter.
  2. מתקינים את ה-CLI של flutterfire dart pub global activate flutterfire_cli.
  3. מריצים את flutterfire configure.
  4. בפונקציה העיקרית של האפליקציה:

    • מייבאים את ה-SDK שנוצר:
    // Generated queries.
    // Update as needed with the path to your generated SDK
    
    import 'movies_connector/movies.dart';
    
    • מגדירים את האפליקציה כך שתתחבר לאמולטור של 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());
    }
    
    • מפעילים את ה-methods של 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();
                }),
          )
        ])));
      }
    }
    

פריסה בסביבת הייצור

כדי לפרוס את הסכימה, השאילתות והמוטציות בסביבת הייצור:

  1. בדף Pricing תוכלו לקרוא מידע על התמחור ועל תקופת הניסיון בחינם. יכול להיות שהפרויקט שלכם עומד בדרישות לאחת מאפשרויות הניסיון של Firebase SQL Connect.

  2. לוחצים על הכפתור Deploy to production בתוסף SQL Connect ל-VS Code, או מריצים בטרמינל:

    firebase deploy --only dataconnect
    

    אחרי הפריסה, אפשר לראות את הסכימה ולהריץ שאילתות ומוטציות במסוף Firebase (עוברים אל Databases & Storage > SQL Connect).

מידע נוסף על dataconnect.yaml מידע נוסף על אופן הפעולה של SQL Connect עם Cloud SQL

השלבים הבאים

עכשיו, אחרי שסיימתם את המדריך למתחילים, הנה כמה פעולות נוספות שאפשר לבצע: