เริ่มต้นใช้งาน Firebase SQL Connect

คู่มือเริ่มต้นฉบับย่อนี้จะช่วยให้คุณเริ่มต้นใช้งาน Firebase SQL Connect เพื่อ เชื่อมต่อเว็บและแอปบนอุปกรณ์เคลื่อนที่กับฐานข้อมูล PostgreSQL ได้ โดยคุณจะได้ทำสิ่งต่อไปนี้

  • ตั้งค่าไดเรกทอรีโปรเจ็กต์ Firebase SQL Connect ในเครื่องด้วย VS Code และ Firebase CLI
  • สร้างสคีมา การค้นหา และการเปลี่ยนแปลง SQL Connect โดยอิงตามไอเดียแอป ของคุณในภาษาธรรมชาติ
  • ใช้ SDK ที่มีการพิมพ์อย่างเข้มงวดในแอปเพื่อเรียกใช้ SQL Connect การค้นหาและการเปลี่ยนแปลง
  • จัดเตรียมอินสแตนซ์ Cloud SQL สำหรับ PostgreSQL, สคีมา SQL Connect, การค้นหา และการเปลี่ยนแปลง

ตั้งค่าไดเรกทอรีโปรเจ็กต์ที่อยู่ในเครื่อง

คุณสามารถติดตั้งเครื่องมือพัฒนาในเครื่องสำหรับ SQL Connect ได้ 2 วิธี

  1. เรียกใช้คำสั่งต่อไปนี้ในไดเรกทอรีโปรเจ็กต์

    สคริปต์จะติดตั้ง Firebase CLI และส่วนขยาย SQL Connect VS Code รวมถึงแนะนำขั้นตอน firebase init dataconnect เพื่อตั้งค่าโปรเจ็กต์ หากคุณไม่ได้ติดตั้ง VS Code Desktop ไว้ สคริปต์จะเปิด VS Code ในเบราว์เซอร์

    curl -sL https://firebase.tools/init/dataconnect | editor=true bash

  2. เปิดหน้าจอส่วนขยาย SQL Connect VS Code โดยคลิกไอคอน Firebase ในแผงด้านซ้ายของ Visual Studio Code

  3. คลิกเริ่มโปรแกรมจำลอง เพื่อเรียกใช้โปรแกรมจำลองกับฐานข้อมูล PGlite ในเครื่อง

ตรวจสอบสคีมา

Firebase SQL Connect ใช้ GraphQL เพื่อกำหนดโมเดลข้อมูล Directive @table จะแมปประเภท GraphQL กับตาราง PostgreSQL ช่องในประเภทจะแมปกับคอลัมน์ PostgreSQL คุณสามารถกำหนดความสัมพันธ์ระหว่างตารางได้โดยใช้ช่องที่อ้างอิงประเภท @table อื่นๆ รวมถึงความสัมพันธ์แบบหลายต่อหลายโดยใช้ตารางรวมที่มีคีย์หลักแบบผสม

ในการตั้งค่าเริ่มต้น คุณจะพบไฟล์สคีมา SQL Connect ใน ไดเรกทอรี dataconnect/schema/ ต่อไปนี้เป็นตารางตัวอย่าง 2 ตารางจากสคีมาเทมเพลตภาพยนตร์ สคีมาของคุณอาจแตกต่างออกไปหากคุณใช้ 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 ที่ให้ไว้หรือเขียนการเปลี่ยนแปลงของคุณเอง

ใช้ปุ่ม Run (local) Code Lens ใน VS Code เพื่อดำเนินการเปลี่ยนแปลงและป้อนข้อมูลลงในฐานข้อมูล PGlite ในเครื่อง

ปุ่มเรียกใช้ CodeLens สำหรับ Firebase SQL Connect

ตรวจสอบการค้นหาและการเปลี่ยนแปลง

ในการตั้งค่าเริ่มต้น คุณจะพบการค้นหาและการเปลี่ยนแปลง 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

เว็บและแอปบนอุปกรณ์เคลื่อนที่จะเข้าถึงได้เฉพาะ SQL Connectการค้นหาและการเปลี่ยนแปลงที่มี @auth Directive เท่านั้น เพื่อรักษาความปลอดภัยของแอป การค้นหาและการเปลี่ยนแปลงสามารถเข้าถึง UID ของ Firebase Auth ได้อย่างปลอดภัย โดยใช้นิพจน์ เช่น {field}_expr: "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 ให้พิมพ์ # เพื่อเริ่มความคิดเห็นและอธิบายการค้นหาหรือการเปลี่ยนแปลง จากนั้นใช้ปุ่ม Generate/Refine Operation Code Lens เพื่อสร้างการดำเนินการ GraphQL

ปุ่มสร้าง CodeLens สำหรับ Firebase SQL Connect

ใช้ SDK ที่สร้างขึ้นในแอป

firebase init dataconnect จะตั้งค่า SDK ที่ปลอดภัยต่อประเภทสำหรับแอปในโปรเจ็กต์โดยอัตโนมัติ หากจำเป็น คุณสามารถเพิ่ม SDK ด้วยตนเองได้โดยใช้ปุ่ม Add SDK to app ในส่วนขยาย SQL Connect VS Code หรือโดยการเรียกใช้ firebase init dataconnect:sdk

เว็บ

  1. เพิ่ม Firebase ไปยังเว็บแอป

  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 ที่สร้างขึ้น ให้กำหนดค่า SDK เป็นทรัพยากร Dependency ใน Xcode

    ในแถบการนำทางด้านบนของ Xcode ให้เลือกไฟล์ > เพิ่มการขึ้นต่อกันของแพ็กเกจ > เพิ่มในเครื่อง แล้วเลือกโฟลเดอร์ที่มี 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 ที่สร้างขึ้น ให้กำหนดค่า SQL Connect เป็นทรัพยากร Dependency ใน Gradle

    อัปเดต plugins และ dependencies ใน app/build.gradle.kts

    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. ในกิจกรรมหลักของแอป ให้ทำดังนี้

    • รับอินสแตนซ์เครื่องมือเชื่อมต่อจาก 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

ขั้นตอนถัดไป

เมื่อทำตามคู่มือเริ่มต้นฉบับย่อนี้เสร็จแล้ว ขั้นตอนถัดไปที่คุณควรทำมีดังนี้