Bắt đầu sử dụng Firebase SQL Connect

Hướng dẫn nhanh này giúp bạn thiết lập và sử dụng Firebase SQL Connect để kết nối ứng dụng web và ứng dụng di động với cơ sở dữ liệu PostgreSQL. Bạn sẽ:

  • Thiết lập thư mục dự án Firebase SQL Connect cục bộ bằng VS Code và Firebase CLI.
  • Tạo giản đồ, truy vấn và đột biến SQL Connect dựa trên ý tưởng ứng dụng của bạn bằng ngôn ngữ tự nhiên.
  • Sử dụng SDK được gõ mạnh trong ứng dụng để chạy SQL Connect truy vấn và đột biến.
  • Cung cấp một Cloud SQL cho thực thể PostgreSQL, một SQL Connect giản đồ, các truy vấn và đột biến.

Thiết lập thư mục dự án cục bộ

Bạn có thể cài đặt các công cụ phát triển cục bộ cho SQL Connect theo 2 cách.

  1. Trong thư mục dự án, hãy chạy lệnh sau.

    Tập lệnh này sẽ cài đặt CLI Firebase và tiện ích SQL Connect VS Code, đồng thời hướng dẫn bạn thực hiện firebase init dataconnect để thiết lập dự án. Nếu bạn chưa cài đặt ứng dụng VS Code dành cho máy tính, tập lệnh này sẽ mở ứng dụng đó trong trình duyệt.

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

  2. Mở màn hình tiện ích SQL Connect VS Code bằng cách nhấp vào biểu tượng Firebase trong bảng điều khiển bên trái của Visual Studio Code.

  3. Nhấp vào Start emulators (Bắt đầu trình mô phỏng) để chạy trình mô phỏng bằng cơ sở dữ liệu PGlite cục bộ.

Xem lại giản đồ

Firebase SQL Connect sử dụng GraphQL để xác định mô hình dữ liệu của bạn. Chỉ thị @table liên kết một loại GraphQL với bảng PostgreSQL. Các trường trong loại liên kết với các cột PostgreSQL. Bạn có thể xác định mối quan hệ giữa các bảng bằng các trường tham chiếu đến các loại @table khác, bao gồm cả mối quan hệ nhiều-nhiều bằng cách sử dụng các bảng kết hợp có khoá chính tổng hợp.

Trong quá trình thiết lập mặc định, bạn có thể tìm thấy các tệp giản đồ SQL Connect trong thư mục dataconnect/schema/. Sau đây là 2 bảng ví dụ trong giản đồ mẫu phim. Giản đồ của bạn có thể khác nếu bạn sử dụng Gemini để tạo giản đồ đó.

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")
}

Tìm hiểu thêm về giản đồSQL Connect

Phát triển các truy vấn và đột biến

Firebase SQL Connect sử dụng GraphQL cho các truy vấn và đột biến. Bạn xác định các truy vấn và đột biến này trong các tệp .gql và gọi chúng theo tên từ ứng dụng của mình. Cú pháp GraphQL cung cấp SDK được gõ mạnh và API linh hoạt để tìm nạp chính xác dữ liệu mà ứng dụng của bạn cần.

Gieo dữ liệu trong cơ sở dữ liệu

Khi trình mô phỏng đang chạy, bạn có thể gieo dữ liệu ban đầu cho trình mô phỏng đó. Bạn có thể sử dụng tệp dataconnect/seed_data.gql được cung cấp hoặc tự viết các đột biến.

Sử dụng nút Run (local) (Chạy (cục bộ)) Code Lens trong VS Code để thực thi các đột biến và điền dữ liệu vào cơ sở dữ liệu PGlite cục bộ.

Nút Chạy CodeLens cho Firebase SQL Connect

Xem lại các truy vấn và đột biến

Trong quá trình thiết lập mặc định, bạn có thể tìm thấy các truy vấn và đột biến SQL Connect trong dataconnect/example/ thư mục.

Bạn có thể truy vấn dữ liệu quan hệ một cách chính xác bằng các truy vấn lồng nhau.

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 giúp bạn xây dựng các truy vấn và đột biến an toàn bằng Firebase Auth.

Để đảm bảo an toàn cho ứng dụng, ứng dụng web và ứng dụng di động chỉ có thể truy cập vào các SQL Connect truy vấn và đột biến bằng @auth chỉ thị. Các truy vấn và đột biến có thể truy cập an toàn vào UID của Firebase Auth bằng một biểu thức như {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
    }
  )
}

Tìm hiểu thêm về các truy vấn SQL Connect Tìm hiểu thêm về các đột biến SQL Connect Tìm hiểu thêm về SQL Connect Auth

Tạo các truy vấn và đột biến

Bạn không cần phải là chuyên gia về GraphQL để sử dụng SQL Connect một cách hiệu quả. Bạn có thể tạo các truy vấn và đột biến SQL Connect từ nội dung mô tả bằng ngôn ngữ tự nhiên.

Trong bất kỳ tệp .gql nào, hãy nhập # để bắt đầu nhận xét và mô tả truy vấn hoặc đột biến. Sau đó, hãy sử dụng nút Generate/Refine Operation (Tạo/Tinh chỉnh thao tác) Code Lens để tạo thao tác GraphQL.

Nút Tạo CodeLens cho Firebase SQL Connect

Sử dụng SDK đã tạo trong ứng dụng

firebase init dataconnect tự động thiết lập SDK an toàn theo loại cho các ứng dụng trong dự án của bạn. Nếu cần, bạn có thể thêm SDK theo cách thủ công bằng nút Add SDK to app trong tiện ích SQL Connect VS Code hoặc bằng cách chạy firebase init dataconnect:sdk.

Web

  1. Thêm Firebase vào ứng dụng web.

  2. Trong tệp chính của ứng dụng React:

    • Nhập SDK đã tạo:
    // Update as needed with the path to your generated SDK.
import { listMovies, ListMoviesData } from '@dataconnect/generated';
    • Thiết lập ứng dụng để kết nối với trình mô phỏng SQL Connect:
    import { connectDataConnectEmulator } from 'firebase/data-connect';

const dataConnect = getDataConnect(connectorConfig);
connectDataConnectEmulator(dataConnect, 'localhost', 9399);
    • Gọi các phương thức 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. Thêm Firebase vào ứng dụng iOS.

  2. Để sử dụng SDK đã tạo, hãy định cấu hình SDK đó làm phần phụ thuộc trong Xcode.

    Trong thanh điều hướng trên cùng của Xcode, hãy chọn File > Add Package Dependencies > Add Local (Tệp > Thêm phần phụ thuộc gói > Thêm cục bộ) rồi chọn thư mục chứa Package.swift đã tạo.

  3. Trong uỷ quyền chính của ứng dụng:

    • Nhập SDK SQL Connect và SDK đã tạo:

      import FirebaseDataConnect
// Generated queries.
// Update as needed with the package name of your generated SDK.
import <CONNECTOR-PACKAGE-NAME>

let connector = DataConnect.moviesConnector

    • Thiết lập ứng dụng để kết nối với trình mô phỏng 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)

    • Gọi các phương thức 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. Thêm Firebase vào ứng dụng Android.

  2. Để sử dụng SDK đã tạo, hãy định cấu hình SQL Connect làm phần phụ thuộc trong Gradle.

    Cập nhật plugins và dependencies trong 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. Trong hoạt động chính của ứng dụng:

    • Nhận thực thể trình kết nối từ SDK đã tạo:
    private val connector = com.myapplication.MoviesConnector.instance
    • Thiết lập ứng dụng để kết nối với trình mô phỏng 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)
  }
    • Gọi các phương thức 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. Thêm Firebase vào ứng dụng Flutter.
  2. Cài đặt CLI flutterfire dart pub global activate flutterfire_cli.
  3. Chạy flutterfire configure.

  4. Trong hàm chính của ứng dụng:

    • Nhập SDK đã tạo:
    // Generated queries.
// Update as needed with the path to your generated SDK

import 'movies_connector/movies.dart';
    • Thiết lập ứng dụng để kết nối với trình mô phỏng 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());
}
    • Gọi các phương thức 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();
            }),
      )
    ])));
  }
}

Triển khai lên kênh phát hành công khai

Cách triển khai giản đồ, truy vấn và đột biến lên kênh phát hành công khai:

  1. Xem thông tin về mức giá và gói dùng thử miễn phí trên trang Mức giá. Dự án của bạn có thể đủ điều kiện sử dụng một trong các gói dùng thử Firebase SQL Connect

  2. Nhấp vào nút Deploy to production (Triển khai lên kênh phát hành công khai) trong tiện ích SQL Connect VS Code hoặc chạy trong một thiết bị đầu cuối:

    firebase deploy --only dataconnect

    Sau khi triển khai, bạn có thể xem giản đồ và chạy các truy vấn và đột biến trong bảng điều khiển Firebase (chuyển đến Databases & Storage > SQL Connect).

Tìm hiểu thêm về dataconnect.yaml Tìm hiểu thêm về cách SQL Connect hoạt động với Cloud SQL

Các bước tiếp theo

Bây giờ bạn đã hoàn tất hướng dẫn nhanh này, sau đây là một số bước tiếp theo: