Memulai Firebase Data Connect

Tips: Bergabunglah dengan program Pratinjau Pribadi Firebase Data Connect untuk mempelajari solusi SQL pertama Firebase lebih lanjut. Anda akan berkesempatan menjadi pengguna awal produk ini dan mendapatkan informasi langsung tentang upaya baru Firebase untuk memodernisasi pengalaman pengembangan aplikasi Anda. Daftar di halaman produk Firebase Data Connect.

Pratinjau: Firebase Data Connect tersedia dalam Pratinjau Pribadi, yang berarti produk tersebut tidak tunduk kepada kebijakan penghentian penggunaan atau SLA dan dapat berubah dengan cara yang tidak kompatibel dengan versi sebelumnya. Melalui Pratinjau Pribadi, Data Connect dan dokumentasinya akan diperbarui dan ditingkatkan. Rilis Pratinjau Pribadi produk tidak boleh digunakan di aplikasi produksi.

Catatan: Untuk mengakses layanan Firebase Data Connect serta sebagian besar alat dan sumber yang disebutkan dalam panduan ini, Anda harus mendaftar program Pratinjau Pribadi.

Dalam panduan memulai ini, Anda akan mempelajari cara:

• Tambahkan Firebase Data Connect ke project Firebase Anda.
• Siapkan lingkungan pengembangan yang mencakup ekstensi Kode Visual Studio untuk berfungsi dengan instance produksi.
• Kemudian, kami akan menunjukkan cara:
  • Buat skema untuk aplikasi email dan deploy ke produksi.
  • Tentukan kueri dan mutasi untuk skema Anda.
  • Terapkan prototipe akhir Anda ke produksi.

Prasyarat

Untuk menggunakan panduan memulai ini, Anda akan memerlukan hal berikut.

• Linux, macOS, atau Windows
• Kode Visual Studio

Menambahkan Data Connect ke project Anda dan membuat sumber data

1. Jika Anda belum melakukannya, buat project Firebase.
   1. Di Firebase console, klik Add project, lalu ikuti petunjuk di layar.

2. Upgrade project Anda ke paket Blaze. Dengan ini, Anda dapat membuat instance Cloud SQL untuk PostgreSQL.

   Catatan: Meskipun Anda menyiapkan penagihan di upgrade Blaze, Anda tidak akan dikenai biaya atas penggunaan Data Connect atau konfigurasi Cloud SQL untuk PostgreSQL default selama pratinjau.

3. Buka bagian Data Connect di Firebase console dan ikuti alur kerja penyiapan produk.

4. Pilih lokasi untuk database CloudSQL untuk PostgreSQL Anda.

5. Catat nama dan ID project, layanan, dan database untuk konfirmasi nanti.

6. Ikuti alur penyiapan selanjutnya, lalu klik Selesai.

   Catatan: Diperlukan waktu hingga 20 menit untuk menyelesaikan penyediaan instance Cloud SQL untuk PostgreSQL.

Memilih dan menyiapkan lingkungan pengembangan

Data Connect mendukung dua pengalaman pengembangan untuk pembuatan prototipe:

• Jika Anda adalah developer Kotlin Android atau web, Anda dapat menggunakan pengembangan VS Code untuk membuat prototipe skema dan operasi secara lokal saat terhubung ke instance Cloud SQL untuk PostgreSQL.

• Jika Anda adalah developer web, Anda dapat menggunakan IDX Development untuk membuat prototipe di ruang kerja IDX menggunakan template IDX yang telah dikonfigurasi sebelumnya dengan PostgreSQL, ekstensi VS Code dengan emulator Data Connect, dan kode panduan memulai yang disiapkan untuk Anda.

Pengembangan VS Code

Jika Anda ingin mengembangkan aplikasi secara lokal dan bukan menggunakan IDX, siapkan ekstensi Firebase VS Code untuk membantu melakukan iterasi pengembangan dengan cepat.

1. Buat direktori baru untuk project lokal Anda.
2. Buka VS Code di direktori baru.
3. Download ekstensi yang dipaketkan sebagai paket VSIX, dari Firebase Storage.
4. Di VS Code, dari menu View, pilih Extensions.
5. Di kolom judul panel Ekstensi, klik ikon menu more_horiz, lalu ikuti Install from VSIX....

Catatan: Ekstensi ini mencakup ekstensi Penyorotan Sintaksis GraphQL marketplace. Ekstensi GraphQL lain yang Anda instal mungkin bertentangan dengan dukungan GraphQL yang dipaketkan dalam file VSIX.

Pengembangan IDX

IDX adalah lingkungan yang dioptimalkan untuk pengembangan aplikasi web. Jika Anda adalah developer Android Kotlin, ikuti langkah-langkah pada tab pengembangan VS Code.

Untuk menyiapkan template Data Connect IDX:

1. Akses template di situs Project IDX.
2. Ikuti alur penyiapan.

Secara opsional, Anda dapat menginstal database PostgreSQL lokal untuk pengembangan lokal dengan emulator Data Connect. Penyiapan ini dibahas di bagian akhir panduan memulai ini.

Menyiapkan project lokal Anda

Catatan: Jika Anda tidak menggunakan IDX, ikuti langkah-langkah di bagian ini.

Instal CLI, dengan mengikuti petunjuk normal.

Catatan: Jika Anda menggunakan penginstalan CLI yang sudah ada, pastikan Anda mengupdate ke versi terbaru.

Kemudian, aktifkan eksperimen Firebase Data Connect.

firebase experiments:enable dataconnect

Menyiapkan direktori project

Untuk menyiapkan project lokal, lakukan inisialisasi direktori project Anda.

Di panel sebelah kiri VS Code, klik ikon Firebase untuk membuka UI ekstensi Firebase VS Code.

Di UI ekstensi Firebase:

1. Pastikan Anda sudah login.
2. Pastikan alur penyiapan Data Connect, termasuk penyediaan database, telah selesai menggunakan Konsol Google Cloud.
3. Klik tombol Run firebase init.
4. Periksa tab Terminal di Panel bawah VS Code untuk mendapatkan perintah.
5. Pilih Data Connect sebagai fitur yang akan digunakan di direktori ini.
6. Saat diminta, berikan ID project, layanan, dan database dari project Data Connect yang Anda buat sebelumnya di konsol.

Alur ini akan membuat file firebase.json dan .firebaserc, serta subdirektori dataconnect, termasuk file dataconnect.yaml dan connector.yaml penting di direktori kerja lokal Anda.

Membuat skema dan kueri Data Connect

Mulai gunakan GraphQL untuk membuat model pengguna dan email. Anda akan memperbarui sumber di:

• /dataconnect/schema/schema.gql
• /dataconnect/default-connector/queries.gql

Mulai mengembangkan skema

Di direktori project Firebase Anda, catat folder dataconnect. Di sinilah Anda menentukan model data untuk database Cloud SQL menggunakan GraphQL.

Dalam file /dataconnect/schema/schema.gql, mulai tentukan skema yang mencakup pengguna dan email.

Pengguna

Di Data Connect, kolom GraphQL dipetakan ke kolom. Pengguna memiliki uid, name, dan email address. Data Connect mengenali beberapa jenis data primitif: String dan Date.

Salin cuplikan berikut atau hapus tanda komentar pada baris yang sesuai dalam file.

# File `/dataconnect/schema/schema.gql`

type User @table(key: "uid") {
   uid: String!
   name: String!
   address: String!
}

Secara default, Firebase Data Connect akan menambahkan kunci id UUID jika tidak ada yang diberikan. Namun, dalam hal ini, Anda ingin uid saya menjadi kunci utama, yang dapat Anda lakukan melalui perintah @table(key: "uid").

Email

Setelah memiliki pengguna, Anda dapat membuat model email. Di sini Anda dapat menambahkan {i>field<i} (atau kolom) yang biasa digunakan untuk data email. Kali ini, kita menghilangkan penambahan kunci utama karena Anda dapat mengandalkan Data Connect untuk mengelolanya.

# File `/dataconnect/schema/schema.gql`

type Email @table {
   subject: String!
   sent: Date!
   text: String!
   from: User!
}

Perhatikan bahwa kolom from dipetakan ke jenis User. Data Connect memahami bahwa ini adalah hubungan antara Email dan User, serta akan mengelola hubungan ini untuk Anda.

Men-deploy skema ke produksi

Jika menggunakan ekstensi Firebase VS Code untuk bekerja dengan database produksi, Anda perlu men-deploy skema sebelum melanjutkan. Setelah men-deploy skema ke database produksi, Anda akan dapat melihat skema tersebut di konsol.

Catatan: Penyediaan instance Cloud SQL untuk PostgreSQL dapat memerlukan waktu hingga 20 menit. Anda tidak akan dapat men-deploy hingga instance Anda siap. Sebelum men-deploy skema, pastikan alur penyiapan Data Connect, termasuk penyediaan database, telah selesai menggunakan Konsol Google Cloud.

1. Anda dapat menggunakan ekstensi Firebase VS Code untuk melakukan deployment.
   • Di UI ekstensi, pada panel Firebase Data Connect, klik Deploy.

2. Atau, Anda dapat menggunakan Firebase CLI.

   firebase deploy
   

3. Baik dalam alur ekstensi maupun CLI, Anda mungkin perlu meninjau perubahan skema dan menyetujui modifikasi yang berpotensi destruktif. Anda akan diminta untuk:

   • Tinjau perubahan skema menggunakan firebase dataconnect:sql:diff
   • Jika Anda sudah puas dengan perubahan tersebut, terapkan perubahan tersebut menggunakan alur yang dimulai oleh firebase dataconnect:sql:migrate.

Jalankan mutasi untuk menambahkan data ke tabel Anda

Di panel editor VS Code, Anda dapat melihat tombol CodeLens muncul di atas jenis GraphQL di /dataconnect/schema/schema.gql.

Kueri dan mutasi waktu pengembangan

Operasi tanpa nama yang terkait dengan tombol CodeLens ini adalah tindakan cepat dan berguna, dalam hal ini, menambahkan data ke tabel. Data Connect menggunakan mutasi GraphQL untuk menjelaskan cara dan siapa yang dapat beroperasi terhadap database. Menggunakan tombol ini akan membuat operasi waktu pengembangan untuk penyebaran data dengan cepat.

Karena Anda telah men-deploy skema ke produksi, Anda dapat menggunakan tombol Add data CodeLens di tombol schema.gql dan Run (Production) di file yang dihasilkan yang dihasilkan untuk melakukan tindakan ini di backend Anda.

Untuk menambahkan data ke tabel User dan Email:

1. Di schema.gql, klik tombol Add data di atas deklarasi jenis User.
2. Dalam file User_insert.gql yang dihasilkan, lakukan hard code data untuk tiga kolom.
3. Klik tombol Run (Production).
   
4. Ulangi langkah sebelumnya untuk menambahkan data ke tabel Email, dengan menyediakan uid pengguna di kolom fromUid, seperti yang diminta dalam mutasi Email_insert yang dihasilkan.

Tulis kueri untuk membuat daftar email

Sekarang bagian yang menyenangkan, kueri. Sebagai developer, Anda sudah terbiasa menulis kueri SQL daripada kueri GraphQL, sehingga hal ini bisa terasa sedikit berbeda pada awalnya. Namun, GraphQL jauh lebih singkat dan aman dari jenis SQL daripada SQL mentah. Ekstensi VS Code kami memudahkan pengalaman pengembangan.

Mulai mengedit file /dataconnect/default-connector/queries.gql. Jika Anda ingin mendapatkan semua email, gunakan kueri seperti ini.

# File `/dataconnect/default-connector/queries.gql`

query ListEmails @auth(level: NO_ACCESS) {
  emails {
    id, subject, text, sent
    from {
      name
    }
  }
}

Menjalankan kueri menggunakan tombol CodeLens di sekitar.

Fitur yang sangat menarik di sini adalah kemampuan untuk memperlakukan hubungan database seperti grafik. Karena Email memiliki kolom from yang merujuk ke Pengguna, Anda dapat masuk ke kolom tersebut dan mendapatkan kembali informasi tentang pengguna.

Menerapkan prototipe yang sudah selesai ke produksi

Anda telah menyelesaikan iterasi pengembangan. Sekarang Anda dapat men-deploy skema, data, dan kueri ke server dengan UI ekstensi Firebase atau Firebase CLI, seperti yang dilakukan dengan skema.

Jika Anda menggunakan ekstensi Firebase VS Code untuk men-deploy, klik tombol Deploy All.

Setelah di-deploy, Anda juga akan dapat melihat dan menjalankan operasi di konsol. Layanan Data Connect Anda akan siap untuk memproses operasi dari klien. Instance Cloud SQL untuk PostgreSQL akan diperbarui dengan skema dan data final yang dihasilkan yang telah di-deploy.

(Opsional) Instal PostgreSQL secara lokal

Dengan menginstal PostgreSQL secara lokal dan mengintegrasikannya dengan emulator, Anda dapat membuat prototipe di lingkungan pengembangan yang sepenuhnya lokal.

Anda dapat menginstal instance PostgreSQL baru atau menggunakan instance yang ada.

Menginstal PostgreSQL

Instal PostgreSQL versi 15.x dengan mengikuti petunjuk untuk platform Anda.

Catatan: Pastikan Anda mencatat nama pengguna dan sandi untuk akses pada masa mendatang.

• macOS. Download dan instal Postgres.app.
• Windows: Gunakan penginstal EDB dari halaman download PostgreSQL.
• Docker: Tarik dan jalankan image pgvector/pgvector:15, yang dilengkapi dengan dukungan PostgreSQL 15.x dan vektor.
• Linux: Sebaiknya gunakan Docker dengan image sebelumnya, tetapi Anda juga dapat mengikuti petunjuk alternatif untuk distribusi populer.

Perhatikan nama host, port, nama pengguna, dan sandi, serta output parameter terkait selama urutan penginstalan.

Agar dapat terhubung ke instance PostgreSQL, emulator membutuhkan:

• Parameter konfigurasi penyiapan ini
• Nama database dari dataconnect.yaml Anda dan database dengan nama terkait yang diinisialisasi di instance lokal.

Mengupdate .firebaserc dengan string koneksi

Gunakan detail konfigurasi PostgreSQL lokal, termasuk nama pengguna dan sandi PostgreSQL lokal, untuk string koneksi yang akan ditambahkan ke kunci berikut di file .firebaserc Anda.

{
  "projects": {},
  ...,
  ...,
  "dataconnectEmulatorConfig": {
    "postgres": {
      "localConnectionString": "postgresql://postgresusername:postgrespassword@localhost:5432?sslmode=disable"
    }}
}

Menghubungkan ke instance PostgreSQL lokal

Setelah konfigurasi ini selesai, untuk terhubung ke database lokal Anda:

1. Di VS Code, di panel sebelah kiri, klik ikon Firebase untuk membuka UI ekstensi Firebase VS Code.
2. Klik tombol Connect to Local PostgreSQL.

Langkah berikutnya

Tips: Apakah panduan ini membuat Anda tertarik untuk berpartisipasi dalam program Pratinjau Pribadi? Jika ya, daftar di halaman produk Firebase Data Connect.