開始使用 Firebase SQL Connect

這份快速入門指南可協助您開始使用 Firebase SQL Connect，將網頁和行動應用程式連線至 PostgreSQL 資料庫。您將學會以下內容：

使用 VS Code 和 Firebase CLI 設定本機 Firebase SQL Connect 專案目錄。
根據您以自然語言提出的應用程式構想，生成 SQL Connect 結構定義、查詢和突變。
在應用程式中使用強型別 SDK，執行SQL Connect查詢和異動。
佈建 PostgreSQL 適用的 Cloud SQL 執行個體、SQL Connect 結構定義、查詢和突變。

設定本機專案目錄

您可以透過兩種方式安裝 SQL Connect 的本機開發工具。

安裝下列必要項目：
- Visual Studio Code
- Node.js，使用 nvm-windows (適用於 Windows) 或 nvm (適用於 macOS 或 Linux)。
- Firebase CLI
建立專案目錄，並在 Visual Studio Code 中開啟。
從 VS Code Marketplace 安裝 SQL Connect VS Code 擴充功能。
按一下「使用 Google 帳戶登入」按鈕。
按一下「連結 Firebase 專案」按鈕。
按一下「Run firebase init」按鈕。
按一下「Start emulators」按鈕，即可使用本機 PGlite 資料庫執行模擬器 SQL Connect。

查看結構定義

Firebase SQL Connect 會使用 GraphQL 定義資料模型。@table 指令會將 GraphQL 型別對應至 PostgreSQL 資料表。類型中的欄位會對應至 PostgreSQL 資料欄。您可以使用參照其他 @table 類型的欄位定義資料表之間的關係，包括使用具有複合主鍵的聯結資料表，定義多對多關係。

在預設設定中，您可以在 dataconnect/schema/ 目錄中找到 SQL Connect 架構檔案。以下是電影範本結構定義中的兩個範例表格。如果您使用 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 和彈性 API，可擷取應用程式所需的確切資料。

在資料庫中填充資料

模擬器執行時，您可以為其提供初始資料。您可以使用提供的 dataconnect/seed_data.gql 檔案，也可以自行編寫突變。

在 VS Code 中使用「Run (local)」程式碼鏡頭按鈕執行突變，並填入本機 PGlite 資料庫。

Firebase SQL Connect 的 CodeLens 執行按鈕

查看查詢和突變

在預設設定中，您可以在 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 查詢和變動。查詢和變動可使用 {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驗證

生成查詢和異動

您不必是 GraphQL 專家，也能有效使用 SQL Connect。您可以根據自然語言說明生成 SQL Connect 查詢和突變。

在任何 .gql 檔案中輸入 # 即可開始註解，並說明查詢或變動。接著，使用「Generate/Refine Operation」(產生/修正作業) Code Lens 按鈕，產生 GraphQL 作業。

Firebase SQL Connect 的 CodeLens 生成按鈕

在應用程式中使用產生的 SDK

firebase init dataconnect 會自動為專案中的應用程式設定類型安全 SDK。如有需要，您可以使用 SQL Connect VS Code 擴充功能中的「Add SDK to app」(將 SDK 新增至應用程式) 按鈕，或執行 firebase init dataconnect:sdk，手動新增 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 的資料夾。

在應用程式的主要委派中：

匯入 SQL Connect SDK 和您產生的 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，請在 Gradle 中將 SQL Connect 設定為依附元件。

更新 app/build.gradle.kts 中的 plugins 和 dependencies。

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 擴充功能中的「Deploy to production」(部署至正式環境) 按鈕，或在終端機中執行下列指令：
```
firebase deploy --only dataconnect
```
部署完成後，請前往 Firebase 控制台查看結構定義，並執行查詢和突變。

提示： 您可以在部署前，於 dataconnect.yaml 中設定 Cloud SQL 區域、執行個體名稱和 PostgreSQL 資料庫名稱。

進一步瞭解 dataconnect.yaml 進一步瞭解 SQL Connect 如何與 Cloud SQL 搭配運作

後續步驟

您已完成快速入門導覽課程，接下來可以採取下列行動：

探索快速入門應用程式存放區，並按照網頁程式碼研究室、iOS 程式碼研究室或 Android 程式碼研究室的指示，建構功能齊全的 SQL Connect 應用程式。
在 Firebase 控制台中連線服務，即可將資料新增至資料庫、檢查結構定義，以及監控 SQL。
使用 Gemini Code Assist 等 AI 輔助開發工具，設定 Firebase MCP 伺服器。
進一步瞭解結構定義、查詢和突變開發作業。
進一步瞭解 SQL Connect 如何管理 PostgreSQL 結構定義。
進一步瞭解網頁、Android、iOS 和 Flutter 的用戶端 SDK，以及 Node.js 的 Admin SDK。