Firebase SQL Connect 使用入门

本快速入门将帮助您快速开始使用 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 安装本地开发工具。

  1. 安装以下必备组件：

  2. 创建项目目录并在 Visual Studio Code 中打开该目录。

  3. 从 VS Code Marketplace 安装 SQL Connect VS Code 扩展程序。

  4. 点击使用 Google 账号登录按钮。

  5. 点击关联 Firebase 项目 按钮。

  6. 点击 Run firebase init 按钮。

  7. 点击启动模拟器按钮，以运行包含本地 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) Code Lens 按钮执行突变并填充本地 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 构建安全的查询和变更。

为确保应用安全，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 操作。

Firebase SQL Connect 的 CodeLens“生成”按钮

在应用中使用生成的 SDK

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

Web

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

  2. 在 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

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

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

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

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

  1. 将 Firebase 添加到您的 Flutter 应用。
  2. 安装 flutterfire CLI dart pub global activate flutterfire_cli。
  3. 运行 flutterfire configure。

  4. 在应用的主函数中：

    • 导入生成的 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();
            }),
      )
    ])));
  }
}

部署到生产环境

如需将架构、查询和变更部署到生产环境，请执行以下操作：

  1. 请查看价格页面上的价格和免费试用信息。您的项目或许符合Firebase SQL Connect试用选项之一的条件。

  2. 点击 SQL Connect VS Code 扩展程序中的部署到生产环境按钮，或在终端中运行以下命令：

    firebase deploy --only dataconnect

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

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

后续步骤

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