Men-deploy dan mengelola skema dan konektor Data Connect

Layanan Firebase Data Connect memiliki tiga komponen utama:

  • Database PostgreSQL pokok dengan skema SQL-nya sendiri
  • skema aplikasi Data Connect (dideklarasikan dalam file .gql Anda)
  • sejumlah konektor (dideklarasikan dalam file .gql, dikonfigurasi dalam file connector.yaml).

Skema SQL adalah sumber tepercaya untuk data Anda, Data Connect skema adalah cara konektor Anda dapat melihat data tersebut, dan konektor mendeklarasikan API yang dapat digunakan klien Anda untuk mengakses data tersebut.

Saat men-deploy layanan Data Connect dengan CLI, Anda akan memigrasikan skema SQL, lalu memperbarui skema Data Connect, lalu memperbarui setiap konektor.

Konsep penerapan penting

Untuk memahami sepenuhnya deployment, penting untuk mencatat konsep utama tentang skema dan konektor.

Deployment skema

Penerapan skema Data Connect memengaruhi skema SQL untuk database Cloud SQL Anda. Data Connect membantu Anda memigrasikan skema selama deployment, baik saat Anda bekerja dengan database baru atau perlu menyesuaikan database yang ada secara non-destruktif.

Migrasi skema Data Connect memiliki dua mode validasi skema yang berbeda: ketat dan kompatibel.

  • Validasi mode ketat mengharuskan skema database persis cocok dengan skema aplikasi sebelum skema aplikasi dapat diperbarui. Tabel atau kolom yang tidak digunakan dalam skema Data Connect Anda akan dihapus dari database.

  • Validasi mode yang kompatibel mengharuskan skema database kompatibel dengan skema aplikasi sebelum skema aplikasi dapat diupdate; perubahan tambahan yang menghapus skema, tabel, atau kolom bersifat opsional.

    Kompatibel berarti migrasi skema hanya memengaruhi tabel dan kolom yang dirujuk dalam skema aplikasi Anda. Elemen dalam database yang tidak digunakan oleh skema aplikasi Anda tidak akan diubah. Oleh karena itu, setelah deployment, database Anda mungkin berisi:

    • Skema
    • Tabel
    • Kolom

Deployment konektor

Kueri dan mutasi Data Connect tidak dikirimkan oleh kode klien dan dieksekusi di server. Sebagai gantinya, saat di-deploy, operasi Data Connect ini disimpan di server, seperti Cloud Functions. Artinya, deployment dapat merusak pengguna yang ada.

Data Connect mengintegrasikan analisis perubahan yang menyebabkan gangguan pada update konektor ke dalam Firebase CLI.

CLI menganalisis perubahan pada setiap konektor sehubungan dengan skema Anda, dan mengeluarkan serangkaian pesan penilaian sehubungan dengan perubahan konektor yang mungkin mengubah perilaku klien (pesan tingkat peringatan) atau mungkin atau akan merusak (pesan tingkat kerusakan) versi sebelumnya dari kode klien.

Contoh:

  • Perubahan konektor yang dapat mengubah perilaku klien mencakup penghapusan kolom yang dapat bernilai null dari kueri tanpa anotasi skema @retired.
  • Perubahan konektor yang dapat atau akan merusak klien mencakup perubahan variabel operasi yang dapat bernilai null menjadi tidak dapat bernilai null tanpa nilai default, atau mengubah jenis data kolom menjadi sesuatu yang tidak kompatibel (mis. String menjadi Int).

Daftar skenario tingkat peringatan dan tingkat perubahan yang lebih ekstensif diberikan dalam panduan referensi CLI.

Ikuti alur kerja deployment

Anda dapat mengerjakan project Data Connect di direktori project lokal dan di konsol Firebase.

Alur deployment yang direkomendasikan meliputi:

  1. Mencantumkan skema dan konektor yang saat ini di-deploy dengan firebase dataconnect:services:list.
  2. Mengelola pembaruan skema.
    1. Periksa perbedaan skema SQL antara database Cloud SQL dan skema Data Connect lokal dengan firebase dataconnect:sql:diff.
    2. Jika perlu, lakukan migrasi skema SQL dengan dataconnect:sql:migrate.
  3. Melakukan deployment skema dan koneksi dengan menjalankan firebase deploy, baik hanya untuk skema, hanya untuk konektor, atau kombinasi resource.

Men-deploy dan mengelola resource Data Connect

Sebaiknya verifikasi resource produksi sebelum melakukan deployment.

firebase dataconnect:services:list

Saat bekerja di direktori project lokal, Anda biasanya akan menggunakan perintah firebase deploy untuk men-deploy skema dan konektor ke produksi, dengan masukan interaktif.

Dengan menggunakan perintah deploy apa pun, flag --only dataconnect memungkinkan Anda memisahkan deployment Data Connect dari produk lain di project Anda.

Deployment normal

firebase deploy --only dataconnect

Dalam deployment normal ini, Firebase CLI mencoba men-deploy skema dan konektor Anda.

Layanan ini memvalidasi bahwa skema baru tidak merusak konektor yang ada. Ikuti praktik terbaik saat melakukan perubahan yang mengganggu.

Tindakan ini juga memverifikasi bahwa skema SQL telah dimigrasikan sebelum mengupdate skema Data Connect. Jika tidak, alat ini akan otomatis memandu Anda melalui langkah-langkah yang diperlukan untuk memigrasikan skema.

Deployment tanda --force

firebase deploy --only dataconnect --force

Jika validasi skema SQL atau konektor tidak menjadi masalah, Anda dapat menjalankan kembali perintah dengan --force untuk mengabaikannya.

Penerapan --force masih memeriksa apakah skema SQL cocok dengan skema Data Connect, memperingatkan ketidakcocokan, dan memberikan perintah.

Men-deploy resource yang dipilih

Untuk men-deploy dengan kontrol yang lebih terperinci, gunakan flag --only dengan argumen serviceId. Untuk men-deploy hanya perubahan skema untuk layanan tertentu:

firebase deploy --only dataconnect:serviceId:schema

Anda juga dapat men-deploy semua resource untuk konektor dan layanan tertentu.

firebase deploy --only dataconnect:serviceId:connectorId

Terakhir, Anda dapat men-deploy skema dan semua konektor untuk satu layanan.

firebase deploy --only dataconnect:serviceId

Me-roll back deployment

Untuk melakukan rollback manual, periksa versi kode Anda sebelumnya dan deploy-kan. Jika deployment asli menyertakan perubahan merusak yang destruktif, Anda mungkin tidak dapat memulihkan sepenuhnya data yang dihapus.

Memigrasikan skema database

Jika Anda membuat prototipe dengan cepat, bereksperimen dengan skema, dan mengetahui bahwa perubahan skema Anda bersifat merusak, Anda dapat berencana menggunakan alat Data Connect untuk memverifikasi perubahan dan mengawasi cara pembaruan dilakukan.

Perbedaan perubahan skema SQL

Anda dapat memverifikasi perubahan:

firebase dataconnect:sql:diff

Anda dapat meneruskan daftar layanan yang dipisahkan koma.

Perintah ini membandingkan skema lokal untuk layanan dengan skema database Cloud SQL yang sesuai saat ini. Jika ada perbedaan, perintah SQL yang akan dijalankan untuk memperbaiki perbedaan tersebut akan dicetak

Menerapkan perubahan

Jika Anda sudah puas dan siap men-deploy perubahan pada instance Cloud SQL skema, jalankan perintah firebase dataconnect:sql:migrate. Anda akan diminta untuk menyetujui perubahan.

firebase dataconnect:sql:migrate [serviceId]

Di lingkungan interaktif, pernyataan migrasi SQL dan perintah tindakan ditampilkan.

Memigrasikan dalam mode ketat atau kompatibel

Dalam project baru, mode validasi skema default akan diterapkan. Perilaku perintah migrate adalah menerapkan semua perubahan skema database yang diperlukan oleh skema aplikasi Anda, lalu meminta Anda menyetujui operasi opsional yang menghapus skema, tabel, atau kolom untuk memaksa skema database Anda agar sama persis dengan skema aplikasi Anda.

Anda dapat menyesuaikan perilaku ini dengan mengubah file dataconnect.yaml. Batalkan komentar pada kunci schemaValidation, dan deklarasikan COMPATIBLE sehingga hanya perubahan yang diperlukan yang diterapkan dalam migrasi.

schemaValidation: "COMPATIBLE"

Atau, tetapkan perilaku ke STRICT sehingga semua perubahan skema diterapkan dan skema database Anda dipaksa agar cocok dengan skema aplikasi Anda.

schemaValidation: "STRICT"

Lihat referensi CLI Data Connect untuk mengetahui informasi selengkapnya.

Mengupdate konektor

Saat Anda menjalankan firebase deploy, CLI akan memulai update konektor yang berlaku dan mengeluarkan pesan penilaian tingkat peringatan (dapat memengaruhi perilaku klien) dan tingkat kerusakan (mungkin atau pasti merusak) yang berlaku.

Mengelola update konektor dengan CLI

CLI memiliki perilaku yang sedikit berbeda dalam mode interaktif dan mode non-interaktif.

Seperti yang mungkin Anda duga, dalam mode interaktif, CLI akan meminta Anda menyetujui semua pesan. Anda dapat mengganti dan memaksa deployment konektor dengan flag --force.

# Prompts for acceptance for any warning-level or breaking-level changes prior
# to deploying connectors.
firebase deploy --only dataconnect
# Will deploy connectors without prompting.
firebase deploy --only dataconnect --force

Dalam mode non-interaktif, CLI akan men-deploy konektor Anda selama tidak ada penilaian tingkat kerusakan. Jika tidak, skrip Anda akan keluar dengan log perubahan yang menyebabkan error. Anda dapat mengganti dan men-deploy dengan menyetel flag --force.

# Will deploy connectors with warning-level changes. If any breaking changes
# are present, the deploy will fail and output any breaking changes
firebase deploy --only dataconnect --non-interactive
# Will deploy the connectors from the previous step, if the same issues are present.
firebase deploy --only dataconnect --non-interactive --force

Untuk mengetahui informasi selengkapnya, lihat panduan referensi CLI.

Praktik terbaik untuk mengelola skema dan konektor

Firebase merekomendasikan beberapa praktik yang harus diikuti dalam project Data Connect Anda.

Meminimalkan perubahan yang dapat menyebabkan gangguan

  • Firebase merekomendasikan agar file skema dan konektor Data Connect Anda tetap berada di kontrol sumber.
  • Hindari perubahan yang merusak jika memungkinkan. Beberapa contoh perubahan yang merusak kompatibilitas meliputi:
    • Menghapus kolom dari skema
    • Membuat kolom nullable di skema Anda menjadi non-nullable (yaitu Int -> Int!)
    • Mengganti nama kolom dalam skema Anda.
  • Jika Anda perlu menghapus kolom dari skema, pertimbangkan untuk membaginya ke dalam beberapa deployment untuk meminimalkan dampak:
    • Pertama, hapus semua referensi ke kolom di konektor Anda, lalu deploy perubahan.
    • Selanjutnya, update aplikasi Anda untuk menggunakan SDK yang baru dibuat.
    • Terakhir, hapus kolom dalam file skema .gql, migrasikan skema SQL, dan deploy sekali lagi.

Menggunakan mode ketat saat bekerja dengan database baru

Jika Anda menggunakan Data Connect dengan database baru dan secara aktif mengembangkan skema aplikasi, dan Anda ingin memastikan skema database tetap sesuai dengan skema aplikasi, Anda dapat menentukan schemaValidation: "STRICT" di dataconnect.yaml.

Tindakan ini akan memastikan perubahan opsional juga diterapkan.

Gunakan mode kompatibel saat Anda memiliki data produksi di database

Jika Anda membuat perubahan pada database yang berisi data produksi, sebaiknya jalankan migrasi skema dalam mode yang kompatibel untuk memastikan data yang ada tidak dihapus. Anda dapat menentukan schemaValidation: "COMPATIBLE" di dataconnect.yaml.

Dalam mode kompatibel, hanya perubahan migrasi skema yang diperlukan yang diterapkan ke database Anda.

  • DROP SCHEMA, DROP TABLE, dan DROP COLUMN dianggap sebagai pernyataan opsional dan tidak akan dibuat untuk rencana Anda, meskipun skema database Anda berisi skema, tabel, atau kolom yang tidak ditentukan dalam skema aplikasi Anda.
  • Jika tabel database Anda berisi kolom non-null yang tidak disertakan dalam skema aplikasi, batasan NOT NULL akan dihapus, sehingga data tetap dapat ditambahkan ke tabel dengan konektor yang Anda tentukan.

Apa langkah selanjutnya?