איך מתחילים להשתמש ב-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 desktop, הסקריפט ייפתח בדפדפן.

    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 חיבור

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

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

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, מקלידים # כדי להתחיל תגובה ולתאר שאילתה או מוטציה. לאחר מכן, משתמשים בלחצן Generate/Refine Operation Code Lens כדי ליצור את פעולת ה-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);
    • מבצעים קריאה ל-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)

    • הפעלת method של 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 (עוברים אל Databases & Storage > SQL Connect).

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

השלבים הבאים

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