เริ่มต้นใช้งาน 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. ติดตั้งข้อกำหนดเบื้องต้นต่อไปนี้

  2. สร้างไดเรกทอรีโปรเจ็กต์และเปิดใน Visual Studio Code

  3. ติดตั้งส่วนขยาย SQL Connect VS Code จาก VS Code Marketplace

  4. คลิกปุ่มลงชื่อเข้าใช้ด้วย Google

  5. คลิกปุ่มเชื่อมต่อโปรเจ็กต์ Firebase

  6. คลิกปุ่มเรียกใช้ firebase init

  7. คลิกปุ่มเริ่มโปรแกรมจำลอง เพื่อเรียกใช้SQL Connect โปรแกรมจำลองกับฐานข้อมูล 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

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

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