تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

بدء استخدام 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 بطريقتَين.

في دليل المشروع، نفِّذ الأمر التالي.

يثبّت النص البرمجي واجهة Firebase CLI وإضافة SQL Connect VS Code، ويرشدك خلال firebase init dataconnect لإعداد مشروعك. إذا لم يكن لديك VS Code desktop مثبّتًا، سيفتحه النص البرمجي في متصفّح.
```
curl -sL https://firebase.tools/init/dataconnect | editor=true bash
```
افتح شاشة إضافة SQL Connect VS Code بالنقر على رمز Firebase في اللوحة اليمنى من Visual Studio Code.
انقر على بدء المحاكيات لتشغيل المحاكي باستخدام قاعدة بيانات 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

مراجعة طلبات البحث والتعديلات

في الإعداد التلقائي، يمكنك العثور على طلبات البحث والتعديلات في 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 إنشاء/تحسين العملية لإنشاء عملية GraphQL.

زر "إنشاء" في CodeLens لـ Firebase SQL
Connect

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

firebase init dataconnect تلقائيًا بإعداد حزم تطوير البرامج (SDK) التي تمنع أخطاء الكتابة للتطبيقات في مشروعك. إذا لزم الأمر، يمكنك إضافة حزمة تطوير البرامج يدويًا باستخدام الزر إضافة حزمة تطوير البرامج إلى التطبيق في إضافة SQL Connect VS Code أو من خلال تشغيل firebase init dataconnect:sdk.

الويب

أضِف Firebase إلى تطبيق الويب.

في الملف الرئيسي لتطبيق 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

أضِف Firebase إلى تطبيقك على أجهزة iOS.
لاستخدام حزمة تطوير البرامج (SDK) التي تم إنشاؤها، عليك ضبطها كاعتمادية في Xcode.

في شريط التنقّل العلوي في Xcode، انقر على ملف > إضافة موارد الاعتمادية للحزمة > إضافة حزمة محلية (File > Add Package Dependencies > Add Local)، ثم اختَر المجلد الذي يحتوي على حزمة Package.swift التي تم إنشاؤها.

في المفوَّض الرئيسي لتطبيقك:

استورِد حزمة تطوير البرامج (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

أضِف Firebase إلى تطبيق Android.

لاستخدام حزمة تطوير البرامج (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")
}

في النشاط الرئيسي لتطبيقك:

احصل على مثيل موصّل من حزمة تطوير البرامج (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

أضِف Firebase إلى تطبيق Flutter.
ثبِّت flutterfire CLI dart pub global activate flutterfire_cli.
شغِّل flutterfire configure.

في الدالة الرئيسية لتطبيقك:

استورِد حزمة 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();
            }),
      )
    ])));
  }
}

النشر في قناة الإصدار العلني

لنشر المخطط والطلبات والتعديلات في بيئة الإنتاج:

راجِع معلومات الأسعار والفترة التجريبية بدون تكلفة في صفحة الأسعار. قد يكون مشروعك مؤهلاً لأحد خيارات الفترة التجريبية في Firebase SQL Connect.
انقر على الزر النشر في قناة الإصدار العلني في إضافة SQL Connect VS Code أو شغِّل الأمر في وحدة طرفية:
```
firebase deploy --only dataconnect
```
بعد النشر، يمكنك الاطّلاع على المخطط وتشغيل طلبات البحث والتعديلات في وحدة تحكّم Firebase (انتقِل إلى قواعد البيانات ومساحة التخزين > SQL Connect).

ملاحظة: يمكنك ضبط منطقة Cloud SQL واسم المثيل واسم قاعدة بيانات PostgreSQL في dataconnect.yaml قبل النشر.

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

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

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

استكشِف مستودع تطبيقات البدء السريع وأنشئ تطبيق SQL Connect يتضمّن ميزات كاملة من خلال اتّباع الدرس التطبيقي حول الترميز للويب أو الدرس التطبيقي حول الترميز لنظام التشغيل iOS أو الدرس التطبيقي حول الترميز لنظام التشغيل Android.
يمكنك إضافة البيانات إلى قاعدة بياناتك وفحص المخططات ومراقبة خدمة SQL Connect في وحدة تحكّم Firebase.
إعداد خادم Firebase MCP باستخدام أدوات للمطوّرين مستنِدة إلى الذكاء الاصطناعي، مثل Antigravity أو Claude Code أو Cursor
يمكنك الاطّلاع على مزيد من المعلومات حول تطوير المخطط وطلب البحث والتغيير.
مزيد من المعلومات حول كيفية إدارة SQL Connect لمخطّط PostgreSQL
يمكنك الاطّلاع على مزيد من المعلومات حول حِزم SDK للعملاء على الويب وAndroid وiOS وFlutter، بالإضافة إلى حِزم SDK للمشرفين على Node.js.