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. 点击运行 firebase init 按钮。

  7. 点击 启动模拟器 按钮，以使用本地 PGlite 数据库运行 SQL Connect 模拟器。

查看架构

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

在默认设置中，您可以在 SQL Connect 架构文件在 dataconnect/schema/ 目录中找到。以下是电影模板架构中的两个示例表。如果您使用 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 中的运行（本地） 代码镜头按钮执行变更并填充本地 PGlite 数据库。

Firebase SQL Connect 的 CodeLens“运行”按钮

查看查询和变更

在默认设置中，您可以在 SQL Connect 查询和变更中 dataconnect/example/ 目录。

您可以使用嵌套查询精确查询关系型数据。

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 应用和移动应用只能使用带有 SQL Connect指令的 @auth 查询和变更。查询和变更可以使用类似 {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 Auth

生成查询和变更

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

在任何 .gql 文件中，输入 # 以开始注释并描述查询或变更。然后，使用生成/优化操作 代码镜头按钮生成 GraphQL 操作。

Firebase SQL Connect 的 CodeLens“生成”按钮

在应用中使用生成的 SDK

firebase init dataconnect 会自动为项目中的应用设置类型安全的 SDK。如果需要，您可以使用 SQL Connect VS Code 扩展程序中的将 SDK 添加到 应用 按钮手动添加 SDK，也可以运行 firebase init dataconnect: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. 在应用的 main 函数中：

    • 导入生成的 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 协同工作

后续步骤

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