بدء استخدام 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 في Visual Studio Code من خلال النقر على رمز Firebase في اللوحة اليمنى من Visual Studio Code.

  3. انقر على بدء المحاكيات لتشغيل المحاكي باستخدام قاعدة بيانات 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 ذات الأنواع المحدّدة بدقة وواجهة برمجة تطبيقات مرنة لاسترداد البيانات الدقيقة التي يحتاجها تطبيقك.

بيانات أولية في قاعدة البيانات

بعد تشغيل المحاكي، يمكنك إضافة بيانات أولية إليه. يمكنك استخدام ملف dataconnect/seed_data.gql المقدَّم أو كتابة عمليات التحويل الخاصة بك.

استخدِم زر تشغيل (محلي) في 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 Auth

إنشاء طلبات وعمليات تغيير

لست بحاجة إلى أن تكون خبيرًا في GraphQL لاستخدام SQL Connect بفعالية. يمكنك إنشاء طلبات بحث وعمليات تغيير من أوصاف باللغة الطبيعية.SQL Connect

في أي ملف .gql، اكتب # لبدء تعليق ووصف طلب بحث أو عملية تغيير. بعد ذلك، استخدِم زر إنشاء/تحسين العملية في Code Lens لإنشاء عملية GraphQL.

زر "إنشاء" في CodeLens لربط Firebase SQL

استخدام حزمة SDK التي تم إنشاؤها في تطبيقك

تُعدّ firebase init dataconnect تلقائيًا حِزم SDK آمنة الأنواع للتطبيقات في مشروعك. إذا لزم الأمر، يمكنك إضافة حزمة تطوير البرامج (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. في المفوَّض الرئيسي لتطبيقك:

    • استورِد حزمة تطوير البرامج (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)
      }
    
    • استدعاء طرق 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());
    }
    
    • استدعاء طرق 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

الخطوات التالية

بعد إكمال دليل التشغيل السريع، إليك بعض الخطوات التالية: