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

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

  • מגדירים את ספריית הפרויקט המקומי Firebase SQL Connect באמצעות VS Code ו-Firebase CLI.
  • יצירת סכימות, שאילתות ומוטציות על סמך רעיונות לאפליקציות בשפה טבעית.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

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

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

אפשר לשאול שאילתות מדויקות על נתונים יחסיים באמצעות שאילתות מקוננות.

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.

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

לחצן ליצירת CodeLens לחיבור Firebase SQL

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

firebase init dataconnect באופן אוטומטי מגדיר ערכות SDK בטוחות לטיפוסים עבור אפליקציות בפרויקט. אם צריך, אפשר להוסיף את ה-SDK באופן ידני באמצעות הלחצן Add SDK to app (הוספת SDK לאפליקציה) בתוסף 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. בנציג הראשי של האפליקציה:

    • מייבאים את SQL Connect SDK ואת ה-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)
      
    • הפעלת methods של 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. מתקינים את flutterfire CLI 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. מעיינים במידע על התמחור ועל תקופת הניסיון ללא עלות בדף תמחור. יכול להיות שהפרויקט שלכם עומד בדרישות לאחת מאפשרויות הניסיון של Firebase SQL Connect.

  2. לוחצים על הלחצן Deploy to production (פריסה בסביבת הייצור) בתוסף SQL Connect VS Code או מריצים את הפקודה במסוף:

    firebase deploy --only dataconnect
    

    אחרי הפריסה, נכנסים אל מסוף Firebase כדי לראות את הסכימה ולהריץ שאילתות ושינויים.

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

השלבים הבאים

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