بدء استخدام Firebase SQL Connect

يساعدك هذا الدليل السريع في بدء استخدام Firebase SQL Connect لربط تطبيقات الويب والأجهزة الجوّالة بقاعدة بيانات PostgreSQL. سيكون عليك إجراء ما يلي:

  • إعداد دليل مشروع Firebase SQL Connect محلي باستخدام VS Code وواجهة سطر الأوامر 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. انقر على بدء المحاكيات لتشغيل المحاكي باستخدام قاعدة بيانات 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. ويمكن لطلبات البحث وعمليات التغيير الوصول بشكل آمن إلى معرّف 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 Auth

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

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

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

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

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

firebase init dataconnect تضبط تلقائيًا حِزم SDK آمنة الأنواع للتطبيقات في مشروعك. ويمكنك إضافة حزمة 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 (انتقِل إلى قواعد البيانات ومساحة التخزين > SQL Connect).

مزيد من المعلومات حول dataconnect.yaml مزيد من المعلومات حول طريقة عمل SQL Connect مع Cloud SQL

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

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