#Manajemen Migrasi

#Pengantar

Plugin manajemen migrasi digunakan untuk migrasi konfigurasi aplikasi dari satu environment (contohnya Staging) ke environment lain (contohnya PROD).

Perbedaan inti:

• Manajemen Migrasi: Fokus pada migrasi konfigurasi aplikasi tertentu, struktur tabel data, atau sebagian data.
• Backup Manager: Fokus pada backup dan restore data full.

#Instalasi

Bergantung pada plugin Manajemen Backup, pastikan sudah terinstal dan diaktifkan.

#Alur dan Prinsip

Memigrasi tabel data dan data dari main database, berdasarkan rule migrasi, dari satu aplikasi ke aplikasi lain. Perlu diperhatikan bahwa data dari database eksternal dan sub-app tidak dimigrasi.

#Rule Migrasi

#Rule Built-in

Mendukung lima rule migrasi berikut:

• Only structure: Hanya menyinkronkan struktur tabel data, tidak melibatkan insert atau update data.
• Overwrite (Truncate dan re-insert): Mengosongkan record tabel yang ada, kemudian insert data baru.
• Insert or update (Upsert): Berdasarkan primary key, jika record ada di-update, jika tidak ada di-insert.
• Insert ignore duplicates: Insert record baru, jika primary key konflik diabaikan (tidak update record yang ada).
• Skip: Tidak melakukan apa pun pada tabel ini.

Catatan:

• Overwrite, insert or update, insert ignore duplicates juga akan menyinkronkan perubahan struktur tabel.
• Tabel dengan auto-increment ID sebagai primary key atau tanpa primary key tidak mendukung "Insert or update" dan "Insert ignore duplicates".

#Desain Detail

#Interface Konfigurasi

Konfigurasi rule migrasi

Aktifkan rule independen

Pilih rule independen dan tabel data yang diproses dengan rule independen saat ini

#File Migrasi

#Buat Migrasi Baru

#Eksekusi Migrasi

#Pemeriksaan Environment Variable

Pemeriksaan environment variable aplikasi (pelajari apa itu environment variable)

Jika DB_UNDERSCORED, USE_DB_SCHEMA_IN_SUBAPP, DB_TABLE_PREFIX, DB_SCHEMA, COLLECTION_MANAGER_SCHEMA di .env tidak konsisten, akan muncul popup yang memberitahu bahwa migrasi tidak dapat dilanjutkan

Jika environment variable atau secret yang dikonfigurasi dinamis hilang, akan muncul popup yang memberitahu user. Anda perlu mengisi environment variable atau secret yang perlu ditambahkan di sini, lalu lanjutkan

#Pemeriksaan Plugin

Pemeriksaan plugin aplikasi, jika environment saat ini kekurangan plugin akan muncul popup peringatan, pada saat ini Anda juga dapat memilih untuk melanjutkan migrasi

#Log dan Penyimpanan Migrasi

Setelah eksekusi migrasi selesai, file log eksekusi akan disimpan di server, dapat dilihat secara online atau di-download.

Saat melihat file log eksekusi secara online, Anda juga dapat men-download SQL yang dieksekusi saat migrasi struktur data.

Klik tombol Process untuk melihat proses eksekusi migrasi yang telah selesai

#Tentang Direktori storage

Manajemen migrasi terutama menangani record database. Sebagian data di direktori storage (seperti log, riwayat backup, request log, dll) tidak akan otomatis dimigrasi.

• Jika perlu mempertahankan file ini di environment baru, Anda perlu menyalin folder terkait di direktori storage secara manual.

#Rollback

Sebelum eksekusi migrasi, sistem akan otomatis membuat backup.

#Prinsip Rollback

1. Stop service: Hentikan aplikasi sebelum memulai rollback, untuk mencegah penulisan data baru.
2. Pencocokan versi: Versi core NocoBase (Docker image) harus konsisten dengan versi saat file backup dihasilkan.
3. Restore di environment baru: Jika database atau storage saat ini sudah rusak, restore versi image saja mungkin tidak cukup. Cara paling aman adalah di instance aplikasi yang baru (database dan storage baru) menggunakan core image yang benar untuk restore backup.

#Alur Rollback

#Skenario A: Eksekusi Task Migrasi Gagal

Jika hanya eksekusi task migrasi yang error, tetapi versi core tidak berubah, langsung gunakan Backup Manager untuk restore backup yang otomatis dibuat sebelum migrasi.

#Skenario B: Sistem Rusak atau Upgrade Core Gagal

Jika upgrade atau migrasi menyebabkan sistem tidak dapat berjalan, perlu rollback ke kondisi stabil:

1. Stop aplikasi: Hentikan service container saat ini.
2. Siapkan environment baru: Siapkan database kosong baru dan environment storage kosong.
3. Deploy versi target: Ubah Docker image tag kembali ke versi saat backup dihasilkan.
4. Restore backup: Eksekusi restore di environment bersih ini melalui Backup Manager.
5. Switch traffic: Update gateway/load balancer, arahkan traffic ke instance baru yang sudah pulih ini.

#Command Line

#yarn nocobase migration generate

Usage: nocobase migration generate [options]

Options:
  --title [title]    migration title
  --ruleId <ruleId>  migration rule id

Contoh

yarn nocobase migration generate --ruleId=1

#yarn nocobase migration run

Usage: nocobase migration run [options] <filePath>

Arguments:
  filePath           migration file path

Options:
  --skip-backup      skip backup
  --var [var]        variable (default: [])
  --secret [secret]  secret (default: [])

Contoh

yarn nocobase migration run /your/path/migration_1775658568158.nbdata \
  && --var A=a --var B=b \
  && --secret C=c --secret D=d

#Best Practice

#Alur Deployment Rekomendasi (Blue-Green Switching)

Untuk memastikan zero-downtime atau downtime minimal, dan keamanan tertinggi, disarankan menggunakan solusi switching dual-environment:

1. Tahap persiapan (Staging): Buat file migrasi di environment Staging.
2. Backup aman (PROD-A): Buat full backup untuk production environment saat ini (PROD-A).
3. Deploy paralel (PROD-B): Deploy instance production baru, dengan database kosong (PROD-B), gunakan versi core target.
4. Restore dan migrasi:
   • Restore backup PROD-A ke PROD-B.
   • Eksekusi file migrasi dari Staging di PROD-B.
5. Verifikasi: Sementara PROD-A masih melayani, lakukan testing menyeluruh terhadap PROD-B.
6. Switch traffic: Update Nginx/gateway, arahkan traffic dari PROD-A ke PROD-B.
   • Jika ada masalah, dapat langsung kembali ke PROD-A.

#Konsistensi Data dan Maintenance Downtime

Saat ini NocoBase tidak mendukung migrasi zero-downtime. Untuk menghindari inkonsistensi data selama proses backup atau migrasi:

• Tutup gateway/entrance: Sangat disarankan untuk menghentikan akses user sebelum memulai backup atau migrasi. Anda dapat mengkonfigurasi halaman maintenance 503 melalui Nginx atau gateway, untuk memberi tahu user bahwa sistem sedang dalam maintenance, dan mencegah penulisan data baru.
• Sinkronisasi data manual: Jika user terus menghasilkan data di versi lama selama migrasi, data tersebut perlu disinkronkan secara manual setelahnya.