شروع کار با Firebase SQL Connect

این آموزش سریع به شما کمک می‌کند تا با Firebase SQL Connect آشنا شوید و برنامه‌های وب و موبایل خود را به پایگاه داده PostgreSQL متصل کنید. شما:

  • دایرکتوری پروژه محلی Firebase SQL Connect خود را با VS Code و Firebase CLI تنظیم کنید.
  • طرحواره‌ها، کوئری‌ها و جهش‌های SQL Connect را بر اساس ایده‌های برنامه خود به زبان طبیعی تولید کنید.
  • از SDK های Strongly-typed در برنامه‌های خود برای اجرای کوئری‌ها و جهش‌های SQL Connect استفاده کنید.
  • یک نمونه Cloud SQL برای PostgreSQL، یک طرحواره SQL Connect ، کوئری‌ها و جهش‌ها را فراهم کنید.

Set up the local project directory

شما می‌توانید ابزارهای توسعه محلی برای SQL Connect را به دو روش نصب کنید.

  1. در دایرکتوری پروژه، دستور زیر را اجرا کنید.

    این اسکریپت رابط خط فرمان (CLI) فایربیس و افزونه SQL Connect VS Code را نصب می‌کند و شما را در راه‌اندازی پروژه‌تان با استفاده از firebase init dataconnect راهنمایی می‌کند. اگر VS Code دسکتاپ را نصب نکرده‌اید، اسکریپت آن را در مرورگر باز می‌کند.

    curl -sL https://firebase.tools/init/dataconnect | editor=true bash

  2. با کلیک روی آیکون Firebase در پنل سمت چپ Visual Studio Code، صفحه افزونه SQL Connect VS Code را باز کنید.

  3. برای اجرای شبیه‌ساز با پایگاه داده محلی PGlite، روی «شروع شبیه‌سازها» کلیک کنید.

Review schema

Firebase SQL Connect از GraphQL برای تعریف مدل داده شما استفاده می‌کند. دستورالعمل @table یک نوع GraphQL را به یک جدول PostgreSQL نگاشت می‌کند. فیلدهای موجود در این نوع، ستون‌های PostgreSQL را نگاشت می‌کنند. می‌توانید با استفاده از فیلدهایی که به انواع دیگر @table ارجاع می‌دهند، روابط بین جداول را تعریف کنید، از جمله روابط چند به چند با استفاده از جداول join با کلیدهای اصلی مرکب.

در تنظیمات پیش‌فرض، می‌توانید فایل‌های طرحواره 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")
}

Learn more about SQL Connect schemas

Develop queries and mutations

Firebase SQL Connect از GraphQL برای کوئری‌ها و جهش‌ها استفاده می‌کند. شما این موارد را در فایل‌های .gql تعریف می‌کنید و آنها را با نام از برنامه خود فراخوانی می‌کنید. سینتکس GraphQL، SDKهای نوع‌گذاری شده قوی و یک API انعطاف‌پذیر را برای دریافت داده‌های دقیق مورد نیاز برنامه شما فراهم می‌کند.

Seed data in your database

با اجرای شبیه‌ساز، می‌توانید آن را با داده‌های اولیه بارگذاری کنید. می‌توانید از فایل dataconnect/seed_data.gql ارائه شده استفاده کنید یا جهش‌های خودتان را بنویسید.

از دکمه‌ی Run (local) Code Lens در VS Code برای اجرای جهش‌ها و پر کردن پایگاه داده‌ی محلی PGlite خود استفاده کنید.

CodeLens Run button for Firebase SQL Connect

Review queries and mutations

در تنظیمات پیش‌فرض، می‌توانید کوئری‌ها و جهش‌های SQL Connect را در دایرکتوری dataconnect/example/ پیدا کنید.

شما می‌توانید داده‌های رابطه‌ای را با استفاده از کوئری‌های تو در تو (nested query) به طور دقیق جستجو کنید.

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 دسترسی داشته باشند. کوئری‌ها و جهش‌ها می‌توانند با استفاده از عبارتی مانند {field}_expr: "auth.uid" به طور ایمن به Firebase 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 بیشتر بدانید

ایجاد پرس‌وجوها و جهش‌ها

برای استفاده موثر SQL Connect نیازی نیست متخصص GraphQL باشید. می‌توانید کوئری‌ها و جهش‌های SQL Connect را از توضیحات زبان طبیعی تولید کنید.

در هر فایل .gql ، برای شروع یک کامنت و توصیف یک پرس‌وجو یا جهش # را تایپ کنید. سپس، از دکمه Generate/Refine Operation Code Lens برای تولید عملیات GraphQL استفاده کنید.

دکمه تولید CodeLens برای Firebase SQL اتصال

Use generated SDK in your app

firebase init dataconnect به طور خودکار SDK های type-safe را برای برنامه‌های پروژه شما تنظیم می‌کند. در صورت نیاز، می‌توانید SDK را به صورت دستی با دکمه Add SDK to app در افزونه SQL Connect VS Code یا با اجرای firebase init dataconnect:sdk کنید.

وب

  1. Add Firebase to your web app.

  2. In your React app's main file:

    • Import your generated 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);
    • Call SQL Connect methods. 
    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 />);

سویفت

  1. Add Firebase to your iOS app.

  2. برای استفاده از SDK تولید شده، آن را به عنوان یک وابستگی در Xcode پیکربندی کنید.

    در نوار ناوبری بالای Xcode، مسیر File > Add Package Dependencies > Add Local را انتخاب کنید و پوشه‌ای که Package.swift تولید شده در آن قرار دارد را انتخاب کنید.

  3. In your app's main delegate:

    • 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)

    • Call SQL Connect methods: 

      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. Add Firebase to your Android app.

  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. In your app's main activity:

    • یک نمونه کانکتور از 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)
  }
    • Call SQL Connect methods. 
    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
      }
    }
  }
}

فلوتر

  1. Add Firebase to your Flutter app.
  2. دستور dart pub global activate flutterfire_cli برای خط فرمان flutterfire نصب کنید.
  3. Run flutterfire configure .

  4. In your app's main function:

    • Import your generated 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());
}
    • Call SQL Connect methods. 
    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();
            }),
      )
    ])));
  }
}

Deploy to production

برای استقرار طرحواره، کوئری‌ها و جهش‌های خود در محیط عملیاتی:

  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 بیشتر بدانید

مراحل بعدی

حالا که مراحل اولیه را انجام دادید، مراحل بعدی به شرح زیر است: