开始使用（续）

开始使用（续）

开始使用（续）

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

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

设置本地项目目录

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

该脚本会安装 Firebase CLI 和 SQL Connect VS Code 扩展程序，并引导您完成 firebase init dataconnect 以设置项目。如果您未安装 VS Code 桌面版，脚本会在浏览器中打开它。

curl -sL https://firebase.tools/init/dataconnect | editor=true bash 2. 点击 Visual Studio Code 左侧面板中的 Firebase 图标，打开 SQL Connect VS Code 扩展程序界面。 3. 点击 Start emulators 以运行使用本地 PGlite 数据库的模拟器。

查看架构

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) Code Lens 按钮执行突变并填充本地 PGlite 数据库。

查看查询和变更

在默认设置中，您可以在 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 构建安全的查询和变更。

为确保应用安全，Web 应用和移动应用只能通过 @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 操作。

在应用中使用生成的 SDK

firebase init dataconnect 会自动为项目中的应用设置类型安全的 SDK。如果需要，您可以使用 SQL Connect 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';

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

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

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

调用 SQL Connect 方法。

``` function App() { const [movies, setMovies] = useState([]); useEffect(() => { listMovies.then(res => setMovies(res.data)); }, []); return ( movies.map(movie =>

{movie.title}

); ); }

const root = ReactDOM.createRoot(document.getElementById('root')); root.render(); ```

Swift

将 Firebase 添加到您的 iOS 应用。
如需使用生成的 SDK，请在 Xcode 中将其配置为依赖项。

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

导入 SQL Connect SDK 和您生成的 SDK：

``` import FirebaseDataConnect // Generated queries. // Update as needed with the package name of your generated SDK. import

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

} ``` 3. 在应用的主 activity 中：

从生成的 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 扩展程序中的部署到生产环境按钮，或在终端中运行以下命令：

firebase deploy --only dataconnect

部署后，您可以在 Firebase 控制台中查看架构并运行查询和突变（依次前往数据库和存储 > SQL Connect）。

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

后续步骤

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

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