本快速入门将帮助您快速开始使用 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 数据库。
查看查询和变更
在默认设置中，您可以在 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 操作。
在应用中使用生成的 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 详细了解 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。