此页面由 Cloud Translation API 翻译。

Firebase Data Connect 使用入门

本快速入门将帮助您快速开始使用 Firebase Data Connect 将 Web 应用和移动应用连接到 PostgreSQL 数据库。您将学习以下内容：

使用 VS Code 和 Firebase CLI 设置本地 Firebase Data Connect 项目目录。
根据您以自然语言表达的应用创意，生成 Data Connect 架构、查询和变更。
在应用中使用强类型 SDK 来运行 Data Connect 查询和变更。
预配 Cloud SQL for PostgreSQL 实例、Data Connect 架构、查询和变更（需要 Blaze 方案）。

设置本地项目目录

您可以通过两种方式为 Data Connect 安装本地开发工具。

在项目目录中，运行以下命令。

该脚本会安装 Firebase CLI 和 Data Connect VS Code 扩展程序，并引导您完成 firebase init dataconnect 以设置项目。如果您未安装 VS Code 桌面版，该脚本会在浏览器中打开它。
```
curl -sL https://firebase.tools/init/dataconnect | editor=true bash
```
点击 Visual Studio Code 左侧面板中的 Firebase 图标，打开 Data Connect VS Code 扩展程序界面。
点击 Start emulators 以运行具有本地 PGlite 数据库的模拟器。

查看架构

Firebase Data Connect 使用 GraphQL 定义数据模型。@table 指令用于将 GraphQL 类型映射到 PostgreSQL 表。类型映射中的字段对应于 PostgreSQL 列。您可以使用引用其他 @table 类型的字段来定义表之间的关系，包括使用具有复合主键的联接表来定义多对多关系。

在默认设置中，您可以在 dataconnect/schema/ 目录中找到 Data 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")
}

详细了解数据连接架构

开发查询和变更

Firebase Data Connect 使用 GraphQL 进行查询和变更。您可以在 .gql 文件中定义这些内容，并从应用中按名称调用它们。GraphQL 语法提供强类型 SDK 和灵活的 API，可用于提取应用所需的精确数据。

数据库中的种子数据

在模拟器运行的情况下，您可以为其植入初始数据。您可以使用提供的 dataconnect/seed_data.gql 文件，也可以自行编写突变。

使用 VS Code 中的 Run (local) Code Lens 按钮执行突变并填充本地 PGlite 数据库。

适用于 Firebase Data Connect 的 CodeLens“运行”按钮

查看查询和变更

在默认设置中，您可以在 dataconnect/example/ 目录中找到 Data 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 }
    }
  }
}

Data Connect 可帮助您使用 Firebase Auth 构建安全的查询和变更。

为确保应用安全，Web 应用和移动应用只能通过 @auth 指令访问 Data 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
    }
  )
}

详细了解 Data Connect 查询详细了解 Data Connect 变更详细了解 Data Connect 身份验证

生成查询和变更

您无需成为 GraphQL 专家，也能有效使用 Data Connect。您可以根据自然语言说明生成 Data Connect 查询和变更。

在任何 .gql 文件中，输入 # 以开始注释，并描述查询或突变。然后，使用 Generate/Refine Operation Code Lens 按钮生成 GraphQL 操作。

Firebase Data Connect 的 CodeLens 生成按钮

在应用中使用生成的 SDK

firebase init dataconnect 会自动为项目中的应用设置类型安全的 SDK。如果需要，您可以使用 VS Code 扩展程序中的向应用添加 SDK 按钮或运行 firebase init dataconnect:sdk 手动添加 SDK。

Web

将 Firebase 添加到您的网页应用。

在 React 应用的主文件中：

导入生成的 SDK：

// Update as needed with the path to your generated SDK.
import { listMovies, ListMoviesData } from '@dataconnect/generated';

对应用进行插桩处理以连接到 Data Connect 模拟器：

import { connectDataConnectEmulator } from 'firebase/data-connect';

const dataConnect = getDataConnect(connectorConfig);
connectDataConnectEmulator(dataConnect, 'localhost', 9399);

调用 Data 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 的文件夹。

在应用的主委托中：

导入 Data 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

对应用进行插桩处理以连接到 Data 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)

调用 Data 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 中将 Data 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")
}

在应用的主 activity 中：

从生成的 SDK 获取连接器实例：

private val connector = com.myapplication.MoviesConnector.instance

对应用进行插桩处理以连接到 Data 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)
  }

调用 Data 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';

对应用进行插桩处理以连接到 Data 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());
}

调用 Data 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 项目以使用 Blaze 方案。
点击 Data Connect VS Code 扩展程序中的部署到生产环境按钮，或在终端中运行以下命令：
```
firebase deploy --only dataconnect
```
部署完成后，请访问 Firebase 控制台，查看架构并运行查询和突变。

提示：您可以在部署之前在 dataconnect.yaml 中配置 Cloud SQL 区域、实例名称和 PostgreSQL 数据库名称。
提示：每个项目均可获享一个 Cloud SQL 3 个月免费试用实例。请参阅其限制。

详细了解 dataconnect.yaml 详细了解 Data Connect 如何与 Cloud SQL 搭配使用

后续步骤

现在，您已完成快速入门，接下来可以执行以下操作：

探索快速入门应用代码库，并按照我们的 Web 版 Codelab、iOS 版 Codelab 或 Android 版 Codelab 构建功能齐全的 Data Connect 应用。
在 Firebase 控制台中，向数据库添加数据、检查架构并监控 Data Connect 服务。
将 Firebase MCP 服务器与 Gemini Code Assist 等 AI 赋能的开发工具搭配使用。
详细了解架构、查询和变更开发。
详细了解 Data Connect 如何管理 PostgreSQL 架构。
详细了解适用于 Web、Android、iOS 和 Flutter 的客户端 SDK 以及适用于 Node.js 的 Admin SDK。