Men-deploy dan mengelola skema dan konektor SQL Connect

Layanan Firebase SQL Connect memiliki tiga komponen utama:

  • Database PostgreSQL yang mendasarinya dengan skema SQL sendiri
  • sebuah SQL Connect skema aplikasi (dideklarasikan dalam file .gql Anda)
  • sejumlah konektor (dideklarasikan dalam file .gql Anda, dikonfigurasi dalam file connector.yaml).

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

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

Konsep deployment penting

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

Deployment skema

Deployment skema SQL Connect memengaruhi skema SQL untuk database Cloud SQL Anda. SQL Connect membantu Anda memigrasikan skema selama deployment, baik saat Anda menggunakan database baru atau perlu mengadaptasi database yang ada secara non-destruktif.

Migrasi skema SQL 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 apa pun yang tidak digunakan dalam skema SQL Connect Anda akan dihapus dari database.

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

    Kompatibel berarti migrasi skema hanya memengaruhi tabel dan kolom yang direferensikan dalam skema aplikasi Anda. Elemen dalam database Anda 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 SQL Connect tidak dikirimkan oleh kode klien dan dieksekusi di server. Sebagai gantinya, saat di-deploy, operasi SQL Connect ini disimpan di server, seperti Cloud Functions. Artinya, deployment dapat merusak pengguna yang ada.

SQL Connect mengintegrasikan analisis perubahan yang dapat menyebabkan gangguan dalam update konektor Anda ke CLI Firebase.

CLI menganalisis perubahan pada setiap konektor terkait skema Anda, dan mengeluarkan serangkaian pesan penilaian terkait konektor perubahan yang mungkin mengubah perilaku klien (pesan berada di tingkat peringatan) atau mungkin atau akan merusak (pesan berada di tingkat gangguan) kode klien versi sebelumnya.

Contoh:

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

Daftar skenario tingkat peringatan dan tingkat gangguan yang lebih lengkap diberikan dalam panduan referensi CLI.

Mengikuti alur kerja deployment

Anda dapat mengerjakan project SQL Connect di direktori project lokal dan di Firebase console.

Alur deployment yang direkomendasikan mencakup:

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

Men-deploy dan mengelola resource SQL Connect

Sebaiknya verifikasi resource produksi sebelum melakukan deployment.

firebase dataconnect:services:list

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

Dengan menggunakan perintah deploy apa pun, flag --only dataconnect memungkinkan Anda memisahkan SQL Connect deployment 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.

Fitur ini memvalidasi bahwa skema baru tidak merusak konektor yang ada. Ikuti praktik terbaik saat melakukan perubahan yang dapat menyebabkan gangguan.

Fitur ini juga memverifikasi bahwa skema SQL telah dimigrasikan sebelum memperbarui the SQL Connect skema. Jika tidak, fitur ini akan otomatis meminta Anda untuk melakukan langkah-langkah yang diperlukan untuk memigrasikan skema.

Deployment flag --force

firebase deploy --only dataconnect --force

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

Deployment --force tetap memeriksa apakah skema SQL cocok dengan skema SQL Connect, memperingatkan tentang ketidakcocokan, dan meminta.

Men-deploy resource yang dipilih

Untuk men-deploy dengan kontrol yang lebih mendetail, 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. Jika deployment asli menyertakan perubahan yang dapat menyebabkan gangguan dan merusak, 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 SQL Connect untuk memverifikasi perubahan dan mengawasi cara update dilakukan.

Membandingkan 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 yang sesuai Cloud SQL saat ini. Jika ada perbedaan, perintah ini akan mencetak perintah SQL yang akan dijalankan untuk memperbaiki perbedaan tersebut

Menerapkan perubahan

Jika Anda puas dan siap men-deploy perubahan ke instance skema Cloud SQL, 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 akan 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 untuk menyetujui operasi opsional yang menghapus skema, tabel, atau kolom untuk memaksa skema database Anda agar persis cocok dengan skema aplikasi Anda.

Anda dapat menyesuaikan perilaku ini dengan mengubah file dataconnect.yaml. Hapus 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 untuk cocok dengan skema aplikasi Anda.

schemaValidation: "STRICT"

Lihat referensi CLI SQL 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 (mungkin memengaruhi perilaku klien) dan tingkat gangguan (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 harapkan, dalam mode interaktif, CLI akan meminta Anda untuk menerima 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 gangguan. Jika tidak, skrip Anda akan keluar dengan log perubahan yang dapat menyebabkan gangguan. Anda dapat mengganti dan men-deploy dengan menetapkan 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 SQL Connect project Anda.

Meminimalkan perubahan yang dapat menyebabkan gangguan

  • Firebase merekomendasikan untuk menyimpan file skema SQL Connect dan konektor Anda dalam kontrol sumber.
  • Hindari perubahan yang dapat menyebabkan gangguan jika memungkinkan. Beberapa contoh umum perubahan yang dapat menyebabkan gangguan mencakup:
    • Menghapus kolom dari skema Anda
    • Membuat kolom yang dapat diisi null dalam skema Anda menjadi tidak dapat diisi null (yaitu Int -> Int!)
    • Mengganti nama kolom dalam skema Anda.
  • Jika Anda perlu menghapus kolom dari skema, pertimbangkan untuk membaginya menjadi beberapa deployment guna meminimalkan dampak:
    • Pertama, hapus referensi ke kolom di konektor Anda, dan deploy perubahan.
    • Selanjutnya, update aplikasi Anda untuk menggunakan SDK yang baru dibuat.
    • Terakhir, hapus kolom di file .gql skema Anda, migrasikan skema SQL Anda, dan deploy sekali lagi.

Menggunakan mode ketat saat menggunakan database baru

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

Tindakan ini akan memastikan perubahan opsional juga diterapkan.

Menggunakan mode kompatibel saat Anda memiliki data produksi di database

Jika Anda melakukan perubahan pada database yang berisi data produksi, sebaiknya jalankan migrasi skema dalam mode 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 yang tidak dapat diisi null yang tidak disertakan dalam skema aplikasi Anda, batasan NOT NULL akan dihapus, sehingga data masih dapat ditambahkan ke tabel dengan konektor yang Anda tentukan.

Apa langkah selanjutnya?

  • Deployment dan pengelolaan kode klien yang Anda kembangkan dengan SDK yang dihasilkan dibahas dalam panduan untuk Android, iOS, web, dan Flutter.
  • Untuk mengetahui informasi selengkapnya tentang alat deployment, tinjau referensi CLI SQL Connect dan referensi file konfigurasi SQL Connect.