ApsaraDB for ClickHouse:Upgrade via data migration

Prasyarat

Sebelum memulai, pastikan Anda telah memiliki:

• Dua kluster Edisi Kompatibel Komunitas (Community-compatible Edition), keduanya dalam status Running

  Untuk migrasi antara Edisi Kompatibel Komunitas dan Edisi Perusahaan (Enterprise Edition), lihat Migrasi kluster ClickHouse Community-compatible Edition ke kluster Enterprise Edition.

• Akun database dan kata sandi yang dikonfigurasi pada kedua kluster

• Konfigurasi penyimpanan berjenjang (tiered storage) yang sama untuk data panas dan dingin pada kedua kluster

• Kedua kluster berada di wilayah (region) dan Virtual Private Cloud (VPC) yang sama, dengan alamat IP masing-masing kluster ditambahkan ke daftar putih (whitelist) kluster lainnya

  Jalankan SELECT * FROM system.clusters; untuk menemukan alamat IP kluster. Untuk konfigurasi daftar putih, lihat Set a whitelist.

• Kluster tujuan yang versi mesin utamanya lebih baru daripada kluster sumber

• Ruang penyimpanan disk yang tersedia pada kluster tujuan (tidak termasuk cold storage) minimal 1,2x dari ruang disk yang digunakan pada kluster sumber (tidak termasuk cold storage)

• Setiap tabel lokal di kluster sumber dipasangkan tepat dengan satu tabel terdistribusi

Untuk versi yang didukung, lihat Catatan rilis untuk ApsaraDB for ClickHouse Community-compatible Edition.

Apa yang dapat dan tidak dapat dimigrasikan

Konten migrasi yang didukung:

• Database, tabel (mesin MergeTree), tampilan yang di-materialisasi (materialized views), kamus data (hanya yang dibuat dengan SQL), izin pengguna, dan konfigurasi kluster

• Skema tabel non-MergeTree (tabel eksternal dan tabel Log) — hanya skema, tanpa data bisnis

  Jika kluster sumber berisi tabel non-MergeTree, kluster tujuan hanya akan memiliki skemanya setelah migrasi, tanpa data bisnis apa pun. Untuk memigrasikan data bisnis tersebut, Anda dapat menggunakan fungsi remote. Untuk informasi selengkapnya, lihat Use the remote function to migrate data.

Tidak didukung:

• Kamus data yang dibuat menggunakan XML

• Tabel mesin Kafka dan RabbitMQ (data bisnis)

Daftar periksa persiapan

Sebelum memulai migrasi:

• Pastikan tidak ada operasi manajemen (scale-out, upgrade, atau downgrade) yang sedang berjalan di kedua kluster.

• Periksa keberadaan kamus data yang dibuat dengan XML dengan menjalankan: SELECT * FROM system.dictionaries WHERE (database = '') OR isNull(database); — jika kueri ini mengembalikan hasil, hapus kamus tersebut sebelum melanjutkan.

• Jika kamus data mengakses layanan eksternal, pastikan layanan tersebut dapat dijangkau dan daftar putihnya mengizinkan akses dari kluster tujuan.

• Jika kamus data menggunakan tabel internal ClickHouse sebagai sumbernya dengan parameter HOST yang diatur ke alamat IP, alamat IP tersebut akan berubah setelah migrasi — buat ulang kamus data tersebut secara manual dengan IP baru setelah migrasi.

• Untuk tabel Kafka dan RabbitMQ: kosongkan dari kluster sumber dan buat ulang di kluster tujuan, atau gunakan kelompok konsumen (consumer group) yang berbeda untuk menghindari pemisahan data.

• Pastikan total data dingin (cold data) di kluster sumber kurang dari 1 TB. Volume data dingin yang lebih besar akan memperpanjang waktu migrasi secara signifikan dan dapat menyebabkan kegagalan tugas.

• Setelah upgrade, perbarui titik akhir (endpoint) di pengaturan klien Anda agar mengarah ke kluster tujuan.

Dampak potensial

Kluster sumber selama migrasi:

• Operasi baca dan tulis tetap berjalan normal.

• Operasi Data Definition Language (DDL) (menambah, menghapus, atau memodifikasi database dan tabel) diblokir.

• Saat perkiraan waktu migrasi tersisa turun menjadi 10 menit atau kurang, kluster sumber secara otomatis menghentikan penulisan (write) untuk menjaga konsistensi data:

  • Jika hal ini terjadi dalam jendela waktu penghentian penulisan (write-stop time window) yang telah ditetapkan, penulisan akan langsung dihentikan.

  • Jika hal ini terjadi di luar jendela waktu penghentian penulisan dan dalam waktu 5 hari sejak pembuatan tugas, ubah jendela waktu penghentian penulisan untuk melanjutkan.

  • Jika hal ini terjadi di luar jendela waktu penghentian penulisan dan melebihi 5 hari sejak pembuatan tugas, migrasi gagal. Batalkan tugas tersebut, hapus data yang telah dimigrasikan dari kluster tujuan, lalu mulai kembali dari awal.

• Penulisan dilanjutkan secara otomatis ketika semua data telah dimigrasikan, atau ketika jendela waktu penghentian penulisan berakhir sebelum migrasi selesai.

Kluster tujuan setelah migrasi:

Kluster tujuan menjalankan operasi merge secara intensif untuk periode tertentu setelah migrasi, sehingga meningkatkan penggunaan I/O dan latensi kueri. Rencanakan peningkatan latensi ini sebelum mengalihkan traffic. Untuk memperkirakan durasi operasi merge, lihat Calculate the merge duration after migration.

Ikhtisar migrasi

Semua langkah dilakukan pada kluster tujuan, bukan kluster sumber.

1. Catat dan bersihkan tabel mesin Kafka/RabbitMQ (lewati jika tidak berlaku).

2. Buat tugas migrasi pada kluster tujuan.

3. Nilai apakah migrasi dapat diselesaikan (hanya diperlukan jika kecepatan penulisan sumber melebihi 20 MB/detik).

4. Monitor tugas migrasi.

5. Buat ulang tabel mesin Kafka/RabbitMQ di kluster sumber (lewati jika tidak berlaku).

6. Hapus tabel mesin Kafka/RabbitMQ di kluster sumber (lewati jika tidak berlaku).

7. Buat ulang tabel mesin Kafka/RabbitMQ di kluster tujuan (lewati jika tidak berlaku).

8. (Opsional) Batalkan tugas migrasi jika diperlukan.

9. (Opsional) Ubah jendela waktu penghentian penulisan.

Langkah 1: catat dan bersihkan tabel mesin Kafka/RabbitMQ

Sebelum memulai migrasi, catat definisi semua tabel mesin Kafka/RabbitMQ dan tampilan materialisasi turunannya di kluster sumber, tangani tabel implisit, lalu hapus tabel-tabel tersebut untuk menghindari error migrasi.

1. Login ke kluster sumber dan kueri semua tabel mesin Kafka dan RabbitMQ beserta dependensi turunannya.

   /*
   create_table_query: definisi tabel
   dependencies_database: database dari tabel yang bergantung pada tabel ini
   dependencies_table: tabel yang bergantung pada tabel ini
   Dari dependencies_database dan dependencies_table, Anda dapat mengidentifikasi tampilan materialisasi yang bergantung pada tabel Kafka/RabbitMQ
   */
   SELECT * FROM system.tables WHERE engine IN ('RabbitMQ', 'Kafka');

2. Lihat definisi tampilan materialisasi untuk memeriksa apakah tabel targetnya merupakan tabel implisit.

   /*
   Lihat definisi tampilan materialisasi.
   Jika tabel target tampilan materialisasi adalah tabel implisit, beri perhatian khusus:
   Menghapus tampilan materialisasi juga akan menghapus tabel implisit, menyebabkan kehilangan data.
   Contoh: Jika CREATE MATERIALIZED VIEW [db.]table_name [TO[db.]name] tidak menentukan TO,
   sistem secara otomatis membuat tabel implisit, kemungkinan dalam format '.inner_id.<TABLE_UUID>' atau '.inner.<TABLE>'
   */
   SELECT * FROM system.tables WHERE database='<DATABASE>' AND name = '<MATERIALIZED_VIEW_NAME>';

3. Jika tabel target tampilan materialisasi adalah tabel implisit, RENAME tabel target tersebut ke nama baru untuk mencegah kehilangan data saat tampilan materialisasi di-drop nanti.

   -- Rename tabel target implisit ke nama baru untuk melindungi data
   RENAME TABLE <DATABASE>.`.inner_id.<TABLE_UUID>` TO <DATABASE>.<new_target_table_name>;

4. Hapus tabel mesin Kafka/RabbitMQ dan tampilan materialisasi turunannya.

   -- Drop tampilan materialisasi terlebih dahulu
   DROP TABLE <DATABASE>.<MATERIALIZED_VIEW_NAME>;
   -- Lalu drop tabel mesin Kafka/RabbitMQ
   DROP TABLE <DATABASE>.<KAFKA_OR_RABBITMQ_TABLE_NAME>;

Langkah 2: buat tugas migrasi

1. Login ke Konsol ApsaraDB for ClickHouse.

2. Di halaman Clusters, pilih tab Clusters of Community-compatible Edition, lalu klik ID kluster tujuan.

3. Di panel navigasi kiri, klik Data Migration and Synchronization > Migration from ClickHouse.

4. Klik Create Migration Task.

5. Konfigurasikan instans sumber dan tujuan, lalu klik Test Connectivity and Proceed.

   Jika pengujian koneksi gagal, konfigurasi ulang instans sesuai petunjuk pesan error.

   

6. Tinjau detail konten migrasi, lalu klik Next: Pre-detect and Start Synchronization.

7. Sistem menjalankan pemeriksaan awal (precheck) dengan pemeriksaan berikut:

   Periksa	Persyaratan
   Status instans	Tidak ada tugas manajemen (scale-out, perubahan konfigurasi) yang sedang berjalan di kedua kluster
   Ruang penyimpanan	Penyimpanan disk tujuan >= 1,2x penyimpanan disk sumber (tidak termasuk cold storage)
   Tabel lokal dan tabel terdistribusi	Setiap tabel lokal di kluster sumber memiliki tepat satu tabel terdistribusi

   • Jika pemeriksaan awal berhasil:

     1. Tinjau detail dampak di halaman tersebut.

     2. Tetapkan Time of Stopping Data Writing.

        Tetapkan jendela penghentian penulisan minimal 30 menit untuk meningkatkan tingkat keberhasilan migrasi. Tanggal akhir tidak boleh lebih dari 5 hari sejak hari ini. Jadwalkan jendela tersebut pada jam sepi untuk meminimalkan dampak terhadap bisnis.

     3. Klik Completed untuk membuat dan memulai tugas.

   • Jika pemeriksaan awal gagal: Atasi masalah yang ditunjukkan, lalu coba lagi migrasi tersebut.

Langkah 3: nilai apakah migrasi dapat diselesaikan

Lewati langkah ini jika kecepatan penulisan kluster sumber kurang dari 20 MB/detik.

Jika kecepatan penulisan kluster sumber melebihi 20 MB/detik, periksa apakah kluster tujuan dapat mengimbangi:

1. Buka View cluster monitoring information dan periksa metrik Disk throughput untuk kluster tujuan.

2. Bandingkan kedua kecepatan penulisan tersebut:

   • Kecepatan penulisan tujuan >= kecepatan penulisan sumber: Migrasi memiliki tingkat keberhasilan tinggi. Lanjutkan ke Langkah 4.

   • Kecepatan penulisan tujuan < kecepatan penulisan sumber: Migrasi mungkin gagal. Batalkan tugas migrasi dan lakukan migrasi manual sebagai gantinya.

Langkah 4: monitor tugas migrasi

1. Di halaman Clusters, pilih tab Clusters of Community-compatible Edition, lalu klik ID kluster tujuan.

2. Di panel navigasi kiri, klik Migration from ClickHouse. Daftar migrasi menampilkan Migration Status, Running Information, dan Data Write-Stop Window untuk setiap tugas.

   Saat perkiraan waktu tersisa di kolom Running Information turun menjadi 10 menit atau kurang dan statusnya Migrating, logika penghentian penulisan (write-stop) akan dipicu. Lihat Potential impacts untuk mengetahui apa yang terjadi dalam setiap skenario.

   Penting

   • Jika kluster sumber berisi tabel mesin Kafka/RabbitMQ: saat tugas migrasi memasuki fase data migration (yaitu, migrasi skema tabel telah selesai), lakukan Langkah 5 untuk membuat ulang tabel mesin Kafka/RabbitMQ di kluster sumber agar data inkremental kembali mengalir dan disinkronkan ke kluster tujuan.

   • Sesaat sebelum jendela penghentian penulisan yang dikonfigurasi, lakukan Langkah 6 untuk menghapus tabel mesin Kafka/RabbitMQ dan tampilan materialisasi turunannya di kluster sumber guna mencegah penumpukan pesan selama periode penghentian penulisan yang dapat menyebabkan inkonsistensi data.

Langkah 5: buat ulang tabel mesin Kafka/RabbitMQ di kluster sumber

Setelah tugas migrasi memasuki fase data migration (yaitu, migrasi skema tabel telah selesai), gunakan pernyataan DDL yang telah disimpan sebelumnya untuk membuat ulang tabel mesin Kafka/RabbitMQ dan tampilan materialisasi turunannya di kluster sumber. Setelah dibuat ulang, data inkremental akan kembali mengalir dan secara otomatis disinkronkan ke kluster tujuan.

-- Buat ulang tabel mesin Kafka/RabbitMQ di kluster sumber
CREATE TABLE <database>.<kafka_or_rabbitmq_table_name> (...)
ENGINE = Kafka/RabbitMQ
SETTINGS ...;

-- Buat ulang tampilan materialisasi (mengarah ke tabel target yang telah diganti namanya)
CREATE MATERIALIZED VIEW <database>.<materialized_view_name> TO <database>.<new_target_table_name>
AS SELECT ... FROM <database>.<kafka_or_rabbitmq_table_name>;

Langkah 6: hapus tabel mesin Kafka/RabbitMQ di kluster sumber

Sesaat sebelum jendela penghentian penulisan yang dikonfigurasi, hapus tabel mesin Kafka/RabbitMQ dan tampilan materialisasi turunannya di kluster sumber untuk menghentikan penulisan data inkremental dan memastikan konsistensi sinkronisasi data akhir.

-- Drop tampilan materialisasi terlebih dahulu
DROP TABLE <DATABASE>.<MATERIALIZED_VIEW_NAME>;
-- Lalu drop tabel mesin Kafka/RabbitMQ
DROP TABLE <DATABASE>.<KAFKA_OR_RABBITMQ_TABLE_NAME>;

Langkah 7: buat ulang tabel mesin Kafka/RabbitMQ di kluster tujuan

Setelah tugas migrasi selesai, gunakan pernyataan DDL yang telah disimpan sebelumnya untuk membuat ulang tabel mesin Kafka/RabbitMQ dan tampilan materialisasi turunannya di kluster tujuan guna memulihkan pipeline konsumsi data inkremental.

-- Buat ulang tabel mesin Kafka/RabbitMQ di kluster tujuan
CREATE TABLE <database>.<kafka_or_rabbitmq_table_name> (...)
ENGINE = Kafka/RabbitMQ
SETTINGS ...;

-- Buat ulang tampilan materialisasi
CREATE MATERIALIZED VIEW <database>.<materialized_view_name> TO <database>.<target_table_name>
AS SELECT ... FROM <database>.<kafka_or_rabbitmq_table_name>;

Langkah 8: (Opsional) batalkan tugas migrasi

1. Di halaman Clusters, pilih tab Clusters of Community-compatible Edition, lalu klik ID kluster tujuan.

2. Di panel navigasi kiri, klik Migration from ClickHouse.

3. Di kolom Actions untuk tugas yang dituju, klik Stop Migration.

4. Di kotak dialog Stop Migration, klik OK.

Daftar tugas mungkin tidak langsung diperbarui setelah pembatalan. Segarkan halaman untuk memeriksa status terbaru. Setelah pembatalan, Migration Status berubah menjadi Completed. Sebelum memulai migrasi baru, hapus data yang telah dimigrasikan dari kluster tujuan untuk menghindari duplikasi data.

Langkah 9: (Opsional) ubah jendela waktu penghentian penulisan

1. Di halaman Clusters, pilih tab Clusters of Community-compatible Edition, lalu klik ID kluster tujuan.

2. Di panel navigasi kiri, klik Migration from ClickHouse.

3. Di kolom Actions untuk tugas yang dituju, klik Modify Data Write-Stop Time Window.

4. Di kotak dialog Modify Data Write-Stop Time Window, pilih Write-stop Time yang baru. Aturan yang sama saat membuat tugas juga berlaku di sini.

5. Klik OK.

Langkah selanjutnya

Setelah memastikan bahwa semua data bisnis telah berhasil dimigrasikan ke kluster tujuan, hapus kluster sumber.

Untuk instruksi penghapusan, lihat Delete a cluster.