PolarDB:Migrasi data

Langkah 1: Konfigurasikan dan mulai sinkronisasi data

1. Ekstrak NimoShake.zip, masuk ke direktori NimoShake, dan edit file konfigurasi bersama conf/nimo.conf. Alat nimo-shake, nimo-full-check, dan nimo-repair berbagi file ini, dan masing-masing alat hanya membaca parameter yang diperlukannya. Berikut adalah parameter konfigurasi inti yang diperlukan untuk memulai sinkronisasi:

   Parameter	Deskripsi	Contoh nilai
   sync_mode	Mode sinkronisasi: all menunjukkan sinkronisasi penuh dan inkremental, sedangkan full hanya sinkronisasi penuh.	all
   source.access_key_id	ID AccessKey AWS DynamoDB sumber.	AKIAIOSFODNN7...
   source.secret_access_key	Secret access key AWS DynamoDB sumber.	wJalrXUtnFEMI...
   source.region	Wilayah tempat AWS DynamoDB sumber berada.	cn-north-1
   target.endpoint_url	Titik akhir akses DynamoDB kluster PolarDB target (termasuk nomor port).	http://pe-xxx.rwlb.rds...
   target.access_key_id	ID AccessKey akun DynamoDB untuk kluster PolarDB target.	your-polardb-access-key
   target.secret_access_key	Secret access key akun DynamoDB untuk kluster PolarDB target.	your-polardb-secret-key
   filter.collection.white	Daftar putih untuk penyaringan tabel. Pisahkan beberapa nama tabel dengan titik koma (;). Parameter ini tidak dapat digunakan bersama parameter daftar hitam.	c1;c2
   filter.collection.black	Daftar hitam untuk penyaringan tabel. Pisahkan beberapa nama tabel dengan titik koma (;). Parameter ini tidak dapat digunakan bersama parameter daftar putih.	c1;c2

   Untuk menggunakan mode pemeriksaan berbasis snapshot S3 yang direkomendasikan (lihat Langkah 2), Anda juga harus mengonfigurasi parameter koneksi PostgreSQL native berikut:

   Parameter	Deskripsi	Contoh nilai
   s3.export_state_file	Jalur ke file status ekspor. File ini ditulis oleh nimo-shake dan dibaca oleh nimo-full-check.	../nimo-shake-s3-exports.json
   s3.export_bucket	Nama bucket S3 target untuk ekspor data DynamoDB.	my-export-bucket
   s3.export_prefix	Awalan jalur S3 yang digunakan untuk mengatur file yang diekspor.	exports/my-project/
   target.pg.endpoint_url	Alamat port native PolarDB for PostgreSQL (format host:port).	pc-xxx.pg.polardb.rds...:5432
   target.pg.user	Username untuk PolarDB for PostgreSQL (juga digunakan sebagai nama skema). Catatan Akun DynamoDB pada dasarnya adalah akun database standar. Secret access key-nya (SK) dihasilkan dengan mengenkripsi password yang Anda tetapkan menggunakan algoritma yang kompatibel. Oleh karena itu, target.pg.user dan target.access_key_id merujuk pada akun yang sama. target.pg.password adalah password kustom Anda, dan SK adalah kunci yang diturunkan dari password tersebut.	your-username
   target.pg.password	Password untuk PolarDB for PostgreSQL.	your-password
   target.pg.check_database	Nama database khusus yang menyimpan tabel pemeriksaan inkremental. Selama fase sinkronisasi inkremental, nimo-shake menulis primary key dari catatan yang berubah ke tabel pemeriksaan inkremental di database ini agar dapat dibaca oleh mode pemeriksaan s3 atau incr. Anda harus membuat database ini secara manual sebelum startup, dan nimo-shake serta nimo-full-check harus dikonfigurasi dengan nilai yang sama. Catatan target.pg.check_database mengarah ke database khusus yang menyimpan tabel pemeriksaan inkremental. Sebelum memulai sinkronisasi, gunakan Privileged Account untuk membuat database secara manual dan atur pemiliknya menjadi **target.pg.user** (akun DynamoDB yang dijelaskan di atas). Dengan demikian, akun tersebut memiliki izin untuk membuat skema dan tabel pemeriksaan inkremental di database tersebut.	nimoshake_check

   (Opsional) Sinkronisasi penuh dalam mode tulis langsung PostgreSQL

   Secara default, sinkronisasi penuh menggunakan mode tulis langsung PostgreSQL native untuk menulis data langsung ke PolarDB menggunakan protokol PostgreSQL standar, melewati lapisan API kompatibilitas DynamoDB untuk performa yang lebih tinggi. Untuk kembali ke lapisan API DynamoDB (BatchWriteItem, yang menulis maksimal 25 item sekaligus), Anda dapat mengubah parameter ini secara manual menjadi dynamodb. Anda dapat mengonfigurasi parameter berikut di bagian [SHAKE] file conf/nimo.conf:

   Parameter	Deskripsi	Default
   full.write_protocol	Protokol yang digunakan untuk penulisan data penuh. postgresql (default): mode tulis langsung PostgreSQL berkinerja tinggi. dynamodb: lapisan API DynamoDB (BatchWriteItem, maksimal 25 item per batch).	postgresql
   full.document.write.batch	Jumlah dokumen yang ditulis dalam setiap batch. Saat menggunakan mode tulis langsung PostgreSQL, ukuran batch tidak dibatasi hingga 25 dokumen. Anda dapat meningkatkan nilai ini untuk lebih meningkatkan throughput tulis. Jika Anda kembali ke protokol dynamodb, ubah nilai ini kembali menjadi 25.	1000
   full.document.concurrency	Jumlah thread tulis konkuren per tabel. Dalam mode tulis langsung PostgreSQL, alat secara otomatis mengatur ukuran kolam koneksi berdasarkan nilai ini untuk memastikan korespondensi satu-ke-satu antara thread dan koneksi.	4

   Catatan

   • Mode tulis langsung PostgreSQL juga mengharuskan Anda mengonfigurasi empat parameter target.pg.*. Kumpulan konfigurasi ini dibagi dengan mode pemeriksaan s3 / incr, sehingga Anda tidak perlu memasukkannya lagi.

   • Mode ini hanya memengaruhi jalur tulis selama fase sinkronisasi penuh. Sinkronisasi inkremental selalu menulis data melalui lapisan API yang kompatibel dengan DynamoDB.

2. (Opsional) Perlindungan Stream Buffer untuk sinkronisasi penuh berdurasi panjang

   AWS DynamoDB Streams hanya menyimpan catatan perubahan selama 24 jam. Ketika tabel sumber berukuran besar dan sinkronisasi penuh diperkirakan memakan waktu lebih dari 24 jam, perubahan inkremental yang dihasilkan selama fase penuh mungkin secara otomatis dibuang oleh AWS jika tetap berada di Streams lebih dari 24 jam, menyebabkan kehilangan data dalam sinkronisasi inkremental. Untuk mengatasi hal ini, Anda dapat mengaktifkan Stream Buffer: pendengar inkremental menulis catatan perubahan Streams ke buffer lokal secara real-time sejak awal sinkronisasi penuh, melewati batas retensi 24 jam. Setelah sinkronisasi penuh selesai, perubahan yang dibuffer dikonsumsi dan diputar ulang dari buffer lokal untuk memastikan tidak ada perubahan yang hilang. Fitur ini dinonaktifkan secara default dan hanya boleh diaktifkan ketika durasi perkiraan sinkronisasi penuh mendekati atau melebihi 24 jam. Konfigurasikan parameter berikut di conf/nimo.conf:

   Parameter	Deskripsi	Default
   incr.stream_buffer.enable	Sakelar utama untuk Stream Buffer.	false
   incr.stream_buffer.dir	Direktori file buffer. Jika dibiarkan kosong, default ke direktori saudara dari checkpoint (<workdir>/<id>-buffer).	Kosong
   incr.stream_buffer.max_seg_size_mb	Ukuran maksimum (MB) file segmen buffer tunggal. Melebihi nilai ini memicu rotasi.	64
   incr.stream_buffer.max_seg_count	Jumlah maksimum catatan per segmen buffer. Melebihi nilai ini memicu rotasi.	10000
   incr.stream_buffer.max_seg_duration_sec	Interval waktu (detik) untuk rotasi segmen paksa.	300
   incr.stream_buffer.max_size_mb	Kuota disk global (MB), dibagi oleh semua shard dan tabel (bukan per-shard). Rencanakan berdasarkan ruang disk yang tersedia di mesin.	51200 (50 GB)
   incr.stream_buffer.quota_backoff_sec	Ketika buffer melebihi kuota global, penulis mencatat ERROR setiap 30 detik untuk meminta operasi memperluas ruang disk atau mempercepat sinkronisasi penuh. Setelah durasi yang ditentukan oleh quota_backoff_sec berlalu, program sinkronisasi secara otomatis dihentikan.	1800

   • Kapasitas disk dapat diperkirakan secara kasar dengan rumus: Disk yang diperlukan (MB) ≈ Durasi sinkronisasi penuh (detik) × Tulisan puncak (catatan/detik) × (Rata-rata byte per catatan / 3) / 1 MB × 1.5. Selalu sediakan ruang disk lebih daripada kurang.

   • Selama sinkronisasi penuh, pembaca tidak mengonsumsi buffer. Oleh karena itu, begitu buffer melebihi max_size_mb, buffer tidak dapat dikosongkan sendiri. Dalam kasus ini, proses crash setelah backoff. Anda harus menambah ruang disk atau meningkatkan kecepatan sinkronisasi penuh sebelum memulai ulang.

3. Jalankan file biner untuk sistem operasi Anda untuk memulai sinkronisasi.

   Catatan

   Kami merekomendasikan menjalankan tugas dengan nohup di latar belakang untuk mencegah tugas sinkronisasi terganggu jika sesi terminal terputus.

   # Jalankan di direktori NimoShake
   nohup ./bin/nimo-shake.linux.amd64 -conf=./conf/nimo.conf > /dev/null 2>&1 &

   Program pertama-tama melakukan sinkronisasi penuh. Setelah sinkronisasi penuh selesai, program secara otomatis beralih ke fase sinkronisasi inkremental dan terus berjalan.

Langkah 2: Periksa konsistensi data

1. nimo-full-check dan nimo-shake berbagi file conf/nimo.conf yang sama, sehingga Anda tidak perlu mengganti direktori atau mengedit file konfigurasi tambahan. Pilih mode pemeriksaan menggunakan parameter mode:

   • scan: Melakukan pemindaian real-time untuk membandingkan data antara sumber dan target. Mode ini paling mudah dikonfigurasi dan tidak memerlukan infrastruktur tambahan, tetapi terus-menerus mengonsumsi kapasitas baca DynamoDB selama pemeriksaan.

   • s3 (Direkomendasikan): Ketika sinkronisasi penuh selesai, nimo-shake secara otomatis mengekspor data sumber ke S3 dan membuat snapshot point-in-time. nimo-full-check menggunakan snapshot ini sebagai garis dasar untuk pemeriksaan, yang menghindari pemindaian ulang DynamoDB sumber. Ini memerlukan parameter terkait S3 dari Langkah 1.

   • incr (Gunakan dengan mode s3): Selama fase sinkronisasi inkremental, nimo-shake menulis primary key dari setiap catatan yang berubah ke tabel pemeriksaan inkremental (ct_{user}_{table}) di PolarDB. nimo-full-check membaca tabel pemeriksaan inkremental dan hanya memeriksa catatan yang berubah.

   • Perbandingan dua metode pemeriksaan

     	Scan Mode	Mode S3 / incr
     Downtime yang diperlukan	Lebih lama. Penulisan bisnis harus dihentikan selama pemeriksaan untuk mencegah data sumber berubah selama pemindaian.	Lebih singkat. Pemeriksaan berdasarkan snapshot. Setelah menghentikan penulisan, Anda hanya perlu memastikan bahwa data inkremental telah tersusul sebelum cutover.
     Dampak pada sumber	Terus-menerus mengonsumsi kapasitas baca DynamoDB.	Pemeriksaan penuh berdasarkan snapshot S3 dan tidak mengonsumsi kapasitas DynamoDB. Pemeriksaan inkremental (mode incr) hanya mengkueri catatan yang berubah, sehingga mengonsumsi lebih sedikit kapasitas.
     Kompleksitas konfigurasi	Rendah.	Lebih tinggi. Memerlukan konfigurasi tambahan untuk S3 dan koneksi PolarDB for PostgreSQL.

2. (Opsional) Verifikasi kontinu inkremental (mode drain, dinonaktifkan secara default): Secara default, mode incr melakukan verifikasi satu kali terhadap semua catatan perubahan yang terakumulasi di tabel pemeriksaan inkremental selama jendela downtime cutover. Ketika sinkronisasi inkremental berjalan dalam periode panjang (jam hingga hari), tabel pemeriksaan inkremental mengakumulasi banyak primary key tertunda, sehingga verifikasi akhir saat cutover memakan waktu lama. Setelah Anda mengaktifkan verifikasi kontinu inkremental (drain), nimo-full-check mode=incr berjalan sebagai proses berumur panjang: selama sinkronisasi inkremental, proses ini terus-menerus memverifikasi dan mengonsumsi catatan yang telah dikonfirmasi konsisten dari tabel pemeriksaan inkremental, menjaga ukuran tabel tersebut tetap kecil sebelum cutover. Saat cutover, hanya jumlah minimal catatan yang tersisa yang perlu diverifikasi akhir, sehingga secara signifikan mengurangi waktu verifikasi dalam jendela downtime. Fitur ini dinonaktifkan secara default dan tidak memengaruhi perilaku yang ada. Aktifkan hanya ketika periode inkremental panjang dan downtime cutover sangat kritis.

   Penting

   • Sakelar check_drain.enable berlaku untuk nimo-shake dan nimo-full-check. Kedua alat berbagi file conf/nimo.conf yang sama, sehingga satu konfigurasi berlaku untuk keduanya.

   • Sebelum mengaktifkan fitur ini di produksi, kami merekomendasikan menyelesaikan verifikasi lalu lintas penuh pada instance pengujian.

   Konfigurasikan parameter berikut di conf/nimo.conf (tidak perlu perubahan secara default):

   Parameter	Deskripsi	Default
   check_drain.enable	Sakelar utama untuk verifikasi kontinu inkremental (drain). Berlaku untuk nimo-shake dan nimo-full-check. Ketika diatur ke false (default), perilakunya identik dengan perilaku default (mode incr dijalankan sekali lalu keluar).	false
   check_drain.finalize_flag_file	Jalur ke file sentinel finalisasi. Saat cutover, operasi menjalankan touch pada file ini, dan proses verifikasi berumur panjang memasuki fase verifikasi akhir pada siklus berikutnya, menghasilkan laporan perbedaan otoritatif, lalu keluar. Diperlukan ketika enable=true.	Kosong
   check_drain.check_qps	Maksimum permintaan BatchGetItem per detik untuk verifikasi drain (batas independen untuk sumber dan target). Parameter ini membatasi tekanan drain pada sumber dan target untuk menghindari persaingan dengan sumber daya sinkronisasi inkremental. Tingkatkan nilai ini jika verifikasi terlalu lambat.	20

   Catatan

   • Selain parameter yang tercantum di atas, conf/nimo.conf juga berisi parameter tuning lanjutan seperti check_drain.cycle_interval_sec, check_drain.settle_sleep_ms, dan check_drain.consistent_read. Pertahankan nilai default dalam kebanyakan kasus. Lihat komentar inline di file konfigurasi untuk detailnya.

   • Setelah Anda mengaktifkan drain, fase cutover tidak lagi memerlukan menjalankan nimo-full-check lagi. Sebagai gantinya, jalankan touch pada file sentinel finalisasi untuk memicu proses berumur panjang menyelesaikan verifikasi akhir dan menghasilkan laporan perbedaan akhir. Untuk informasi lebih lanjut, lihat Lakukan cutover bisnis - Pemeriksaan konsistensi terakhir.

   • Proses berumur panjang untuk mode incr harus dimulai setelah verifikasi garis dasar s3 selesai. Proses verifikasi yang tersisa sama dengan default.

3. Mulai tugas pemeriksaan.

   nohup ./bin/nimo-full-check.linux.amd64 -conf=./conf/nimo.conf > /dev/null 2>&1 &

   Alat pemeriksaan menyimpan log terperinci dan laporan perbedaan data di direktori default logs/ dan nimo-full-check-diff/, masing-masing. Berikut adalah contoh output dari pemeriksaan yang berhasil:

   [INFO] documentChecker[0] with table[{nimo-shake src2}] [success: 91, fail: 0] item matches!
   [INFO] documentChecker[2] with table[{nimo-shake src1}] [success: 96, fail: 0] item matches!
   [INFO] documentChecker[0] with table[{nimo-shake src2}] [success: 92, fail: 0] item matches!
   [INFO] documentChecker[2] with table[{nimo-shake src1}] [success: 97, fail: 0] item matches!
   [INFO] documentChecker[0] with table[{nimo-shake src2}] [success: 93, fail: 0] item matches!
   [INFO] documentChecker[0] with table[{nimo-shake src2}] [success: 94, fail: 0] item matches!
   [INFO] documentChecker[2] with table[{nimo-shake src1}] [success: 98, fail: 0] item matches!
   [INFO] documentChecker[0] with table[{nimo-shake src2}] [success: 95, fail: 0] item matches!
   [INFO] documentChecker[2] with table[{nimo-shake src1}] [success: 99, fail: 0] item matches!
   [INFO] documentChecker[0] with table[{nimo-shake src2}] [success: 96, fail: 0] item matches!
   [INFO] documentChecker[2] with table[{nimo-shake src1}] [success: 100, fail: 0] item matches!
   [INFO] documentChecker[2] with table[{nimo-shake src1}] check completed. real total count: 100
   [INFO] documentChecker[2] with table[{nimo-shake src1}] close executor
   [INFO] documentChecker[2] finishes checking table[src1]
   [INFO] documentChecker[0] with table[{nimo-shake src2}] [success: 97, fail: 0] item matches!
   [INFO] documentChecker[0] with table[{nimo-shake src2}] [success: 98, fail: 0] item matches!
   [INFO] documentChecker[0] with table[{nimo-shake src2}] [success: 99, fail: 0] item matches!
   [INFO] documentChecker[0] with table[{nimo-shake src2}] [success: 100, fail: 0] item matches!
   [INFO] documentChecker[0] with table[{nimo-shake src2}] check completed. real total count: 100
   [INFO] documentChecker[0] with table[{nimo-shake src2}] close executor
   [INFO] documentChecker[0] finishes checking table[src2]
   [INFO] all documentCheckers finish
   [INFO] checker finishes!
   [INFO] full-check completes!

4. (Opsional) Perbaiki data yang tidak konsisten:

   1. Ketika data di DynamoDB sumber tidak konsisten dengan data di kluster PolarDB for PostgreSQL target, tabel yang tidak konsisten tercantum di direktori diff yang ditentukan. Contoh:

      Catatan

      Direktori diff default adalah nimo-full-check-diff. Anda dapat mengonfigurasinya di conf/nimo.conf menggunakan parameter diff_output_file.

      nimo-full-check-diff/
        └── testtable-0
        └── testtable-1

   2. Jalankan tugas perbaikan:

      nohup ./bin/nimo-repair.linux.amd64 -conf=./conf/nimo.conf > /dev/null 2>&1 &

Langkah 3: (Opsional) Konfigurasikan sinkronisasi balik

Sebelum cutover bisnis, Anda dapat mengonfigurasi tautan sinkronisasi balik dari PolarDB for PostgreSQL ke DynamoDB sumber. Tautan ini diaktifkan selama pergantian resmi ke PolarDB untuk mengaktifkan aliran data balik dan menyediakan perlindungan untuk rollback bisnis. Prosedur konfigurasinya adalah sebagai berikut:

Langkah 4: Lakukan cutover bisnis

Setelah latensi sinkronisasi inkremental rendah dan pemeriksaan konsistensi data berhasil, Anda dapat merencanakan cutover bisnis. Ketika siap, ikuti langkah-langkah berikut:

1. Pemeriksaan akhir: Sebelum jendela downtime yang direncanakan, jalankan alat pemeriksaan konsistensi berulang kali hingga Anda memastikan bahwa latensi sinkronisasi inkremental minimal dan jumlah ketidaksesuaian data nol atau dalam kisaran yang dapat diterima.

2. Hentikan penulisan sumber: Pada awal jendela downtime, hentikan semua aplikasi dari menulis ke AWS DynamoDB sumber.

3. Tunggu sinkronisasi selesai: Pantau log nimo-shake untuk memastikan tidak ada data inkremental baru yang perlu disinkronkan.

4. Pemeriksaan konsistensi terakhir: Jalankan alat nimo-full-check lagi untuk memastikan data di sumber dan target sepenuhnya konsisten.

   Catatan

   Jika Anda telah mengaktifkan verifikasi kontinu inkremental (mode drain), Anda tidak perlu memulai nimo-full-check lagi pada langkah ini. Proses verifikasi berumur panjang telah terus-menerus memverifikasi dan mengonsumsi tabel pemeriksaan inkremental selama fase inkremental. Setelah Anda memastikan bahwa laju tulis inkremental nimo-shake telah turun ke nol (antrian telah dikosongkan), buat file sentinel finalisasi (file yang ditentukan oleh check_drain.finalize_flag_file, misalnya, touch /tmp/nimo-finalize). Proses berumur panjang secara otomatis memasuki fase verifikasi akhir, menghasilkan laporan perbedaan otoritatif, lalu keluar.

5. Hentikan alat sinkronisasi: Setelah Anda memastikan data telah tersinkronisasi sepenuhnya, hentikan proses nimo-shake.

6. Alihkan koneksi aplikasi: Hentikan aplikasi bisnis dan ubah konfigurasi koneksi database mereka dari titik akhir AWS DynamoDB ke titik akhir akses DynamoDB PolarDB.

7. (Opsional) Mulai tugas sinkronisasi balik: Selama pergantian bisnis resmi ke PolarDB, mulai tugas sinkronisasi balik. Tugas ini menggunakan Realtime Compute for Apache Flink untuk mengimplementasikan replikasi data balik, yang menyediakan perlindungan untuk rollback bisnis.

8. Mulai aplikasi bisnis: Mulai ulang aplikasi bisnis. Cutover selesai.

9. (Opsional) Hentikan tugas sinkronisasi balik: Setelah cutover selesai dan bisnis berjalan stabil selama periode tertentu, Anda dapat menghentikan tugas sinkronisasi balik (yang mencakup menghentikan pekerjaan Flink dan melepaskan sumber dayanya).