開始在 Android 上使用 Firebase SQL Connect

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

事前準備

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

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

教學課程

教學課程

1. 建立新的 Android Studio 專案

在 Android Studio 中，使用「Empty Activity」範本建立新專案。

將專案命名為「Quickstart App」，套件名稱為「com.example.quickstartapp」。

 Android Studio 新專案對話方塊

2. 將 Firebase 新增至 Android Studio 專案

在 build.gradle.kts 檔案中新增 Firebase 依附元件和 Kotlin 序列化外掛程式。

 QuickstartApp/build.gradle.kts 
plugins {
  alias(libs.plugins.android.application) apply false
  alias(libs.plugins.kotlin.compose) apply false

  // Add this line.
  id("com.google.gms.google-services") version "4.4.4" apply false
}
 QuickstartApp/app/build.gradle.kts 
plugins {
  alias(libs.plugins.android.application)
  alias(libs.plugins.kotlin.compose)

  // Add these lines.
  kotlin("plugin.serialization") version libs.versions.kotlin
  id("com.google.gms.google-services")
}

// ...

dependencies {
  // ...

  // Add these lines.
  implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.11.0")
  implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.11.0")

  implementation(platform("com.google.firebase:firebase-bom:34.14.0"))
  implementation("com.google.firebase:firebase-dataconnect")
}

3. 初始化 Firebase 專案

切換至 Android Studio 專案目錄，並在其中初始化 Firebase 專案。

 
cd ~/QuickstartApp
 
firebase login --reauth
 
firebase init dataconnect

系統提示時，請選擇下列選項：

  • 建立新的 Firebase 專案。
  • 請勿使用 Gemini 建立結構定義 (在本教學課程中，您將使用預先建構的範例結構定義)。
  • 佈建免費試用Cloud SQL執行個體和資料庫。

並保留所有其他提示的預設值。

接著，在 Firebase 專案中註冊 Android 應用程式。

firebase apps:create -a com.example.quickstartapp android android-quickstart
 
firebase apps:sdkconfig android -o app/google-services.json

4. 查看 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
  }
}

5. 部署結構定義和作業

每當您變更資料庫結構定義、查詢或突變時，都必須部署這些項目，變更才會在資料庫中生效。

 
firebase deploy --only dataconnect

6. 將範例資料填入資料庫

測試範例應用程式時，您會看到這些種子資料。請注意，您在這個步驟中執行的任意 GraphQL，可用於管理工作。

 
firebase dataconnect:execute dataconnect/seed_data.gql

7. 產生 Android 用戶端 SDK

這項指令會使用 GraphQL 定義，專為您的資料庫產生 Android 用戶端 SDK。您可以在用戶端應用程式中使用這個程式庫，執行所有資料庫作業。

您可以在 connector.yaml 中加入定義，為多個平台產生程式庫，包括適用於 iOS 的 Swift、適用於網頁的 JavaScript，以及 Flutter。

 
firebase dataconnect:sdk:generate
 自動產生的 Android SDK (節錄) 
public interface ExampleConnector : GeneratedConnector<ExampleConnector> {
  override val dataConnect: com.google.firebase.dataconnect.FirebaseDataConnect

  public val listMovies: ListMoviesQuery

  // ...
}

8. 編寫 Android 用戶端範例

將 app/src/main/java/com/example/sequel/MainActivity.kt 的內容替換成這個簡單的 Android 應用程式。

請注意，應用程式會使用產生的 SDK 中的函式，完成必要的資料庫存取作業。

 
package com.example.quickstartapp

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.foundation.lazy.items
import androidx.compose.material3.Scaffold
import androidx.compose.material3.Text
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import com.example.quickstartapp.ui.theme.QuickstartAppTheme
import com.google.firebase.dataconnect.generated.ExampleConnector
import com.google.firebase.dataconnect.generated.ListMoviesQuery
import com.google.firebase.dataconnect.generated.execute
import com.google.firebase.dataconnect.generated.instance

class MainActivity : ComponentActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    enableEdgeToEdge()
    setContent {
      QuickstartAppTheme() {
        Scaffold(modifier = Modifier.fillMaxSize()) { innerPadding ->
          var movies by remember {
            mutableStateOf(emptyList<ListMoviesQuery.Data.MoviesItem>())
          }
          LaunchedEffect(Unit) {
            // Queries need to be executed in a coroutine context
            try {
              movies = ExampleConnector.instance.listMovies.execute().data.movies
            } catch (e: Exception) {
              // TODO: Handle error, e.g., show a Toast or update a state variable to
              //   display an error message.
            }
          }
          LazyColumn(modifier = Modifier.padding(innerPadding)) {
            items(movies) { movie ->
              Text(text = movie.title)
            }
          }
        }
      }
    }
  }
}

9. 試用應用程式

在 Android Studio 中執行範例應用程式，即可查看實際運作情形。

後續步驟

試用 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 架構」一文中的指引，然後繼續閱讀後續頁面，瞭解如何編寫作業。