在本地开始使用 Firebase Data Connect

在本快速入门中，您将学习如何在本地构建应用中的 Firebase Data Connect，而无需设置生产 SQL 实例。您将学习以下内容：

  • 将 Firebase Data Connect 添加到您的 Firebase 项目。
  • 设置开发环境，包括用于处理本地实例的 Visual Studio Code 扩展程序。
  • 接下来，我们将向您展示如何执行以下操作：
    • 使用 VS Code 扩展程序工具（搭配 Gemini Code Assist）执行以下操作：
      • 为应用创建架构
      • 创建管理 query 和 mutation 以填充本地数据库
      • 帮助您在可部署的连接器中为应用实现查询和变更
    • 使用针对本地模拟器的示例数据测试查询和突变
    • 生成强类型 SDK 并在应用中使用
    • 将最终架构和连接器部署到云端（可选，需要升级到 Blaze 方案）。

选择本地开发流程

Data Connect 为您提供了两种安装开发工具并在本地工作的方式。

前提条件

如需使用本快速入门，您需要满足以下条件。

设置开发环境

  1. 为本地项目创建新目录。
  2. 在新目录中打开 VS Code。
  3. 从 Visual Studio Code Marketplace 安装 Firebase Data Connect 扩展程序。

设置项目目录

如需设置本地项目，请初始化项目目录。在 IDE 窗口的左侧面板中，点击 Firebase 图标以打开 Data Connect VS Code 扩展程序界面：

  1. 点击使用 Google 账号登录按钮。
  2. 点击关联 Firebase 项目按钮，然后在控制台中选择您之前创建的项目。
  3. 点击 Run firebase init 按钮。

  4. 点击启动模拟器按钮。

创建架构

在 Firebase 项目目录的 /dataconnect/schema/schema.gql 文件中，开始定义有关电影评论的 GraphQL 架构。

使用 Gemini Code Assist 构建架构

使用 Gemini Code Assist 创建电影评价应用架构：

  1. 点击 Data Connect VS Code 扩展程序图标以打开其边栏。
  2. 点击试用 Gemini 和 @FirebaseDataConnect。系统会打开 Gemini Code Assist 聊天窗口。
  3. 点击聊天界面，然后开始输入 @FirebaseDataConnect 以过滤相关命令。

  4. 选择 /generate_schema 命令，然后在提示中完成该命令，要求 Gemini 为您正在开发的应用构建架构。

    例如：

    @FirebaseDataConnect /generate_schema I want to build an app to track movie reviews from multiple users

  5. 片刻之后，系统会显示推荐的架构。查看架构。

  6. 如需将代码添加到 schema.gql，请执行以下操作：

    1. 点击插入到文件底部按钮
    2. 或者，如需在光标位置插入代码，请点击聊天回答顶部的 + 按钮。

电影

在 Data Connect 中，GraphQL 字段会映射到列。电影具有 id、title、imageUrl 和 genre。Data Connect 可识别以下原初数据类型：String 和 UUID。

复制以下代码段，或取消文件中的相应行的注释。

# By default, a UUID id key will be created by default as primary key.
# If you want to specify a primary key, say title, which you can do through
# the @table(key: "title") directive
type Movie @table {
  id: UUID! @default(expr: "uuidV4()")
  title: String!
  imageUrl: String!
  genre: String
}

MovieMetadata

复制以下代码段，或取消文件中的相应行的注释。

# Movie - MovieMetadata is a one-to-one relationship
type MovieMetadata @table {
  # This time, we omit adding a primary key because
  # you can rely on Data Connect to manage it.

  # @unique indicates a 1-1 relationship
  movie: Movie! @unique
  # movieId: UUID <- this is created by the above reference
  rating: Float
  releaseYear: Int
  description: String
}

请注意，movie 字段映射到 Movie 类型。 Data Connect 了解这是 Movie 和 MovieMetadata 之间的关系，并将为您管理这种关系。

如需详细了解 Data Connect 架构，请参阅相关文档

向表格添加数据

在 IDE 编辑器面板中，您会看到 CodeLens 按钮显示在 /dataconnect/schema/schema.gql 中的 GraphQL 类型上方。您可以使用 Add data 和 Run (Local) 按钮将数据添加到本地数据库。

如需向 Movie 和 MovieMetadata 表格添加记录，请执行以下操作：

  1. 在 schema.gql 中，点击 Movie 类型声明上方的添加数据按钮。
    Firebase Data Connect 的 CodeLens“添加数据”按钮
  2. 在生成的 Movie_insert.gql 文件中，对这三个字段的数据进行硬编码。
  3. 点击运行（本地）按钮。
    Firebase Data Connect 的 CodeLens“运行”按钮
  4. 重复上述步骤，向 MovieMetadata 表格添加一条记录，并在 movieId 字段中提供电影的 id，如生成的 MovieMetadata_insert 突变中所提示的那样。

如需快速验证数据是否已添加，请执行以下操作：

  1. 返回到 schema.gql，点击 Movie 类型声明上方的读取数据按钮。
  2. 在生成的 Movie_read.gql 文件中，点击运行（本地）按钮以执行查询。

在文档中详细了解 Data Connect 突变

定义查询

现在，让我们来做更有趣的事情：定义应用中所需的查询。 作为开发者，您习惯于编写 SQL 查询，而不是 GraphQL 查询，因此一开始可能会觉得有点不同。

不过，与原始 SQL 相比，GraphQL 更加简洁且类型安全。此外，我们的 VS Code 扩展程序可简化查询和突变的开发体验。

如需使用 Gemini Code Assist 创建查询，请执行以下操作：

  1. 点击 Data Connect VS Code 扩展程序图标以打开其边栏。
  2. 点击试用 Gemini 和 @FirebaseDataConnect。系统会打开 Gemini Code Assist 聊天窗口。
  3. 点击聊天界面，然后开始输入 @FirebaseDataConnect 以过滤相关命令。

  4. 选择 /generate_operation 命令，然后在提示中完成该命令，让 Gemini 构建查询。

    例如：

    @FirebaseDataConnect /generate_operation List all movies with titles start with "A".

  5. 片刻之后，系统会显示推荐的查询。查看查询。

  6. 如需将代码添加到 queries.gql，请执行以下操作：

    1. 点击插入到文件底部按钮
    2. 或者，如需在光标位置插入代码，请点击聊天回答顶部的 + 按钮。

使用附近的 CodeLens 按钮执行查询。

在文档中详细了解 Data Connect 查询

生成 SDK 并在应用中使用

在 IDE 左侧面板中，点击 Firebase 图标以打开 Data Connect VS Code 扩展程序界面：

  1. 点击向应用添加 SDK 按钮。

  2. 在随即显示的对话框中，选择包含应用代码的目录。Data Connect系统会生成 SDK 代码并将其保存到该目录中。

  3. 选择应用平台，然后注意，系统会立即在所选目录中生成 SDK 代码。

使用 SDK 从应用中调用查询

您可以使用 Data Connect 生成的 SDK 来实现对 ListMovies 查询的调用。然后，您可以使用 Data Connect 模拟器在本地执行此查询。

Web

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

  2. 在 React 应用的主文件中：

    • 导入生成的 SDK
    • 对应用进行插桩处理，以连接到 Data Connect 模拟器
    • 调用 Data Connect 方法。
    import React from 'react';
import ReactDOM from 'react-dom/client';

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

// Generated queries.
// Update as needed with the path to your generated SDK.
import { listMovies, ListMoviesData } from '@movie-app/movies';

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

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. 将 Firebase 添加到您的 iOS 应用。

  2. 如需使用生成的 SDK，请在 Xcode 中将其配置为依赖项。

    在 Xcode 顶部导航栏中，依次选择 File > Add Package Dependencies > Add Local，然后选择包含生成的 Package.swift 的文件夹。

  3. 在应用的主委托中：

    • 导入生成的 SDK
    • 对应用进行插桩处理，以连接到 Data Connect 模拟器
    • 调用 Data Connect 方法。
    import SwiftUI

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

let connector = DataConnect.moviesConnector

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

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. 将 Firebase 添加到您的 Android 应用。

  2. 如需使用生成的 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")
}

  3. 在应用的主 activity 中：

    • 导入生成的 SDK
    • 对应用进行插桩处理，以连接到 Data Connect 模拟器
    • 调用 Data Connect 方法。
    import android.os.Bundle
import android.widget.TextView
import androidx.appcompat.app.AppCompatActivity
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.lifecycleScope
import androidx.lifecycle.repeatOnLifecycle
import kotlinx.coroutines.launch


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


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. 将 Firebase 添加到您的 Flutter 应用。
  2. 安装 flutterfire CLI dart pub global activate flutterfire_cli。
  3. 运行 flutterfire configure。
  4. 在应用的主函数中：
    • 导入生成的 SDK
    • 对应用进行插桩处理，以连接到 Data Connect 模拟器
    • 调用 Data Connect 方法。
import 'package:firebase_core/firebase_core.dart';
import 'package:flutter/material.dart';
import 'firebase_options.dart';

// Generated queries.
// Update as needed with the path to your generated SDK

import 'movies_connector/movies.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  await Firebase.initializeApp(
    options: DefaultFirebaseOptions.currentPlatform,
  );
  
  MoviesConnector.instance.dataConnect
      .useDataConnectEmulator(Uri.base.host, 443, isSecure: true);
  
  runApp(const MyApp());
}

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();
            }),
      )
    ])));
  }
}

将架构和查询部署到生产环境

在应用上完成本地设置后，您现在可以将架构和连接器部署到云端。您需要有 Blaze 方案项目才能设置 Cloud SQL 实例。

  1. 前往 Firebase 控制台的“Data Connect”部分，然后创建一个免费试用 Cloud SQL 实例。

  2. 在 IDE 集成的终端中，运行 firebase init dataconnect 并选择您刚刚在控制台上创建的区域/服务 ID。

  3. 当系统提示“File dataconnect/dataconnect.yaml already exists, Overwrite?”（文件 dataconnect/dataconnect.yaml 已存在，是否覆盖？）时，选择 "Y"。

  4. 在 IDE 窗口的 VS Code 扩展程序界面中，点击部署到生产环境按钮。

  5. 部署完成后，前往 Firebase 控制台，验证架构、操作和数据是否已上传到云端。您应该能够查看架构，并且还可以在控制台中运行操作。Cloud SQL for PostgreSQL 实例将使用最终部署的生成架构和数据进行更新。

后续步骤

查看已部署的项目并探索更多工具：

  • 在 Firebase 控制台中，您可以向数据库添加数据、检查和修改架构，以及监控 Data Connect 服务。

如需了解详情，请参阅相关文档。例如，由于您已完成快速入门：