Firebase SQL Connect 使用入门 (iOS)

在本快速入门中，您将创建并部署一个小型的示例数据库，然后从 iOS 应用访问该数据库。

前提条件

如需完成本快速入门，您需要具备以下条件：

  • 安装了以下工具的环境：
    • 最新版本的 Xcode。
    • Firebase CLI。如果您已安装 NPM，请运行以下命令： 
      npm install -g firebase-tools@latest
       否则，请参阅相关文档，了解安装说明。
  • Google 账号。

教程

教程

1. 创建新的 Xcode 项目

在 Xcode 中，使用 App 模板创建新项目。

将项目命名为 Quickstart，并将软件包标识符设为 com.example.Quickstart。

Xcode“新建项目”对话框

在空文件夹（例如 ~/qs-ios）中创建项目。Xcode 将创建一个文件夹 ~/qs-ios/Quickstart，其中包含您的项目文件。

2. 初始化 Firebase 项目

切换到 Xcode 项目的项目目录，并在其中初始化 Firebase 项目。

 
cd ~/qs-ios
 
firebase login --reauth
 
firebase init dataconnect

出现提示时，请选择以下选项：

  • 创建新的 Firebase 项目。
  • 不使用 Gemini 创建架构（在本教程中，您将使用预构建的示例架构）。
  • 预配免费试用 Cloud SQL 实例和数据库。

接受所有其他提示的默认值。

接下来，在 Firebase 项目中注册 iOS 应用。

firebase apps:create --bundle-id com.example.Quickstart ios ios-quickstart

当系统提示您指定 App Store ID 时，请按 Enter 键跳过此步骤。

firebase apps:sdkconfig ios -o Quickstart/GoogleService-Info.plist

在 Xcode 中，依次选择 File > Add Files to "Quickstart"，然后选择 GoogleService-Info.plist 文件。

3. 查看示例 GraphQL 定义

在 SQL Connect 中，您可以使用 GraphQL 定义所有数据库架构和操作。初始化项目时，Firebase CLI 会创建一些示例定义，帮助您入门。

 dataconnect/schema/schema.gql（摘录） 
type Movie @table {
  title: String!
  imageUrl: String!
  genre: String
}

type MovieMetadata @table {
  movie: Movie! @unique
  rating: Float
  releaseYear: Int
  description: String
}
 dataconnect/example/queries.gql（摘录） 
query ListMovies @auth(level: PUBLIC) {
  movies {
    id
    title
    imageUrl
    genre
  }
}

4. 部署架构和操作

无论何时对数据库架构、查询或突变进行更改，您都必须部署这些更改，才能使它们在数据库中生效。

 
firebase deploy --only dataconnect

5. 使用示例数据为数据库播种

此初始数据将为您提供在测试示例应用时可供查看的内容。请注意，在此步骤中，您正在执行任意 GraphQL，这对于管理任务是允许的。

 
firebase dataconnect:execute dataconnect/seed_data.gql

6. 生成 iOS 客户端 SDK

此命令使用您的 GraphQL 定义生成专门针对您的数据库的 iOS 客户端 SDK。您可以在客户端应用中使用此库来执行所有数据库操作。

您可以通过向 connector.yaml 添加定义，为多个平台生成库，包括适用于 Android 的 Kotlin、适用于 Web 的 JavaScript 和 Flutter。

 
firebase dataconnect:sdk:generate
 自动生成的 iOS SDK（摘录） 
public class ListMoviesQuery {

  // ...

  @MainActor
  public func execute(
    fetchPolicy: QueryFetchPolicy = .preferCache,
  ) async throws -> OperationResult<ListMoviesQuery.Data> {
    var variables = ListMoviesQuery.Variables()

    let ref = dataConnect.query(
      name: "ListMovies", variables: variables, resultsDataType: ListMoviesQuery.Data.self,
      publisher: .observableMacro)

    let refCast = ref as! QueryRefObservation<ListMoviesQuery.Data, ListMoviesQuery.Variables>
    return try await refCast.execute(fetchPolicy: fetchPolicy)
  }
}

7. 将 Firebase 依赖项添加到您的 Xcode 项目中

使用 Swift Package Manager 将生成的库添加到您的项目中。添加生成的库时，它会以传递方式包含 Firebase 核心库和 Firebase SQL Connect 库。

在 Xcode 导航栏中，依次选择 File > Add Package Dependencies > Add Local，然后选择包含生成的库 FirebaseDataConnectGenerated/DataConnectGenerated/ 的文件夹。正确的文件夹将包含一个名为 Package.swift 的文件。

8. 编写示例 iOS 客户端

将 Quickstart/QuickstartApp.swift 的内容替换为这个简单的 iOS 应用。

请注意，应用使用生成的 SDK 中的函数完成必要的数据库访问。

 
import SwiftUI
import FirebaseCore
import FirebaseDataConnect
import DataConnectGenerated

@main
struct QuickstartApp: App {
  init() {
    FirebaseApp.configure()
  }
  var body: some Scene {
    WindowGroup {
      ListMovieView()
    }
  }
}

struct ListMovieView: View {
  @State private var moviesData: ListMoviesQuery.Data?

  var body: some View {
    VStack {
      ForEach(moviesData?.movies ?? []) { movie in
        Text(movie.title)
      }
    }
    .task {
      let result = try? await DataConnect.exampleConnector
          .listMoviesQuery.execute()
      self.moviesData = result?.data
    }
  }
}

9. 试用此应用

在 Xcode 中运行示例应用，查看其运行效果。

后续步骤

试用 SQL Connect VS Code 扩展程序

使用 SQL Connect 进行开发时，我们强烈建议使用 SQL Connect VS Code 扩展程序。 即使您不使用 Visual Studio Code 作为主要开发环境，该扩展程序也提供了多项功能，可让架构和操作开发更加便捷：

  • 一个 GraphQL 语言服务器，提供特定于 SQL Connect 的语法检查和自动补全建议
  • 与代码位于同一行的 CodeLens 按钮，可让您从架构定义文件中读取和写入数据，并从操作定义中执行查询和突变。
  • 自动使生成的 SDK 与 GraphQL 定义保持同步。
  • 简化了本地模拟器设置。
  • 简化了向生产环境的部署。

使用 SQL Connect 模拟器进行本地开发

虽然本教程介绍了如何将 SQL Connect 架构和操作直接部署到生产环境，但您可能不希望在积极开发应用时更改生产数据库。建议您设置 SQL Connect 模拟器，并针对该模拟器（而非生产环境）开展开发工作。模拟器会设置一个本地 PGlite 实例，该实例的行为与 Cloud SQL 上的实时 PostgreSQL 实例类似。

了解如何为应用编写架构和操作

使用 SQL Connect 开发应用时，设计架构和操作是您要完成的首要任务之一，也是最重要的开发任务之一。

  • Firebase 控制台中的 Gemini 是一款 AI 工具，可根据应用的自然语言描述生成 SQL Connect 架构。借助此工具，您可以非常快速地开始使用，尤其是在您之前从未处理过关系型数据库的情况下。
  • 或者，您也可以直接使用 GraphQL 编写数据库架构、查询和变更。首先，请参阅设计 SQL Connect 架构中的指南，然后继续浏览后续页面，了解如何编写操作。

了解如何从 SQL Connect 获取实时更新

您可以使用 SQL Connect 编写可实时响应数据变化的客户端应用。 请参阅获取来自 SQL Connect 的实时更新。