開始在 iOS 上使用 Firebase SQL Connect

在本快速入門導覽課程中,您將建立及部署小型範例資料庫,並從 iOS 應用程式存取該資料庫。

事前準備

如要完成本快速入門導覽課程,請務必符合以下條件:

  • 安裝下列工具的環境:
    • 最新版本的 Xcode
    • Firebase CLI。如果已安裝 NPM,請執行:
      npm install -g firebase-tools@latest
      否則,請參閱說明文件中的安裝說明。
  • Google 帳戶。

教學課程

教學課程

1. 建立新的 Xcode 專案

在 Xcode 中,使用「App」範本建立新專案。

將專案命名為「Quickstart」,並使用軟體包 ID「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 (excerpt)
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、網頁適用的 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 的即時更新」。