Bermigrasi ke Cloud SQL dari file fisik XtraBackup

Halaman ini menjelaskan cara memigrasikan database MySQL dari server eksternal ke Cloud SQL menggunakan file fisik Percona XtraBackup for MySQL.

Cloud SQL mendukung migrasi database MySQL di server eksternal ke instance Cloud SQL untuk MySQL menggunakan Percona XtraBackup. Anda membuat file fisik dengan utilitas XtraBackup, lalu menguploadnya ke Cloud Storage. Dengan menggunakan file fisik, Anda dapat meningkatkan kecepatan keseluruhan migrasi hingga 10 kali lipat dibandingkan migrasi berbasis file dump logis biasa.

Cloud SQL mendukung migrasi berbasis file fisik untuk MySQL 5.7 dan 8.0. MySQL 5.6 dan 8.4 tidak didukung. Migrasi dari database Amazon Aurora atau MySQL di Amazon RDS tidak didukung. Selain itu, instance replika target di Cloud SQL untuk MySQL harus diinstal dengan versi utama MySQL yang sama dengan server eksternal Anda. Namun, replika target dapat menggunakan versi minor yang lebih baru. Misalnya, jika database eksternal Anda menggunakan MySQL 8.0.31, maka replika target Anda harus berupa Cloud SQL untuk MySQL versi 8.0.31 atau yang lebih baru.

Sebelum memulai

Bagian ini memberikan langkah-langkah yang perlu Anda lakukan sebelum memigrasikan database MySQL ke Trusted Cloud.

Menyiapkan project Trusted Cloud

1. In the Trusted Cloud console, on the project selector page, select or create a Trusted Cloud project.

   Go to project selector

2. Verify that billing is enabled for your Trusted Cloud project.

3. Enable the Cloud SQL Admin API.

   Enable the API

4. Pastikan Anda memiliki peran Cloud SQL Admin, Storage Admin, dan Compute Viewer di akun pengguna.

   Buka halaman IAM

Menyiapkan bucket Cloud Storage

Jika Anda belum melakukannya, buat bucket Cloud Storage.

Instal Trusted Cloud SDK

Untuk menggunakan perintah gcloud CLI di server eksternal Anda, instal SDK Trusted Cloud .

Menyiapkan server eksternal untuk migrasi

1. Instal salah satu versi utilitas XtraBackup berikut di server eksternal Anda.

   • Untuk MySQL 5.7, instal Percona XtraBackup 2.4.
   • Untuk MySQL 8.0, instal Percona XtraBackup 8.0.x.

   Untuk MySQL 8.0, Anda harus menginstal XtraBackup versi yang sama atau lebih tinggi dari versi server sumber Anda. Untuk mengetahui informasi selengkapnya, lihat Perbandingan versi server dan versi cadangan dalam dokumentasi Percona XtraBackup.

2. Pastikan server eksternal Anda memenuhi semua persyaratan yang diperlukan untuk replikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan server eksternal untuk replikasi.

   Selain persyaratan server eksternal untuk replikasi, migrasi dari file fisik XtraBackup memiliki persyaratan berikut:

   • Database MySQL Anda harus berupa database lokal atau database MySQL yang dikelola sendiri di VM Compute Engine. Migrasi dari database Amazon Aurora atau MySQL di Amazon RDS tidak didukung.
   • Anda harus mengonfigurasi parameter innodb_data_file_path dengan hanya satu file data yang menggunakan nama file data default ibdata1. Jika database Anda dikonfigurasi dengan dua file data atau memiliki file data dengan nama yang berbeda, Anda tidak dapat memigrasikan database menggunakan file fisik XtraBackup. Misalnya, database yang dikonfigurasi dengan innodb_data_file_path=ibdata01:50M:autoextend tidak didukung untuk migrasi.
   • Parameter innodb_page_size di database eksternal sumber Anda harus dikonfigurasi dengan nilai default 16384.

3. Jika Anda belum menyiapkannya, buat akun pengguna replikasi. Anda memerlukan nama pengguna dan sandi untuk akun pengguna ini.

Melakukan migrasi

Selesaikan semua langkah di bagian berikut untuk memigrasikan database MySQL eksternal Anda ke Cloud SQL.

Membuat dan menyiapkan file fisik XtraBackup

1. Di server eksternal, gunakan XtraBackup untuk melakukan pencadangan penuh database sumber. Untuk mengetahui informasi selengkapnya tentang cara membuat cadangan penuh, lihat Membuat cadangan penuh di dokumentasi Percona XtraBackup.

   Jenis cadangan lainnya, seperti cadangan inkremental dan parsial, tidak didukung.

   Untuk meningkatkan performa proses pencadangan, lakukan hal berikut:

   • Menyalin beberapa file secara paralel selama langkah pencadangan dengan menggunakan --parallel=threads
   • Tingkatkan alokasi memori selama langkah persiapan dengan menggunakan --use-memory=size

   Contoh:

   sudo xtrabackup --backup \
   --target-dir=XTRABACKUP_PATH \
   --user=USERNAME \
   --password=PASSWORD \
   --parallel=THREADS

   Ganti variabel berikut:

   • XTRABACKUP_PATH: lokasi file cadangan output
   • USERNAME: pengguna yang memiliki hak istimewa BACKUP_ADMIN di database sumber
   • PASSWORD: sandi untuk pengguna
   • THREADS: jumlah thread yang akan digunakan saat menyalin beberapa file data secara bersamaan saat membuat cadangan

2. Gunakan utilitas XtraBackup untuk menyiapkan file cadangan. File harus dalam status yang konsisten. Untuk mengetahui informasi selengkapnya tentang cara menyiapkan cadangan penuh, lihat Menyiapkan cadangan penuh. Contoh:

   sudo xtrabackup --prepare --target-dir=XTRABACKUP_PATH \
       --use-memory=MEMORY

   Ganti variabel berikut:

   • XTRABACKUP_PATH: lokasi file cadangan output
   • MEMORY: memori yang dialokasikan untuk persiapan. Tentukan 1 GB hingga 2 GB. Untuk mengetahui informasi selengkapnya tentang opsi -use-memory, lihat dokumentasi Percona XtraBackup.

   Waktu yang diperlukan untuk menyiapkan file cadangan dapat bervariasi bergantung pada ukuran database.

Mengupload file fisik XtraBackup ke Cloud Storage

Gunakan gcloud CLI untuk mengupload file cadangan ke Cloud Storage.

  gcloud storage rsync XTRABACKUP_PATH CLOUD_STORAGE_BUCKET --recursive
  

Ganti XTRABACKUP_PATH dengan lokasi file cadangan output dan CLOUD_STORAGE_BUCKET dengan jalur bucket Cloud Storage.

Tidak ada batasan ukuran file XtraBackup Anda. Namun, ada batas 5 TB untuk ukuran setiap file tunggal yang dapat Anda upload ke bucket Cloud Storage.

Menentukan instance representasi sumber

1. Buat file source.json yang menentukan instance representasi sumber untuk server eksternal Anda. Instance representasi sumber menyediakan metadata untuk server eksternal di Cloud SQL.

   Di file source.json, berikan informasi dasar berikut tentang server eksternal Anda.

   {
   "name": "SOURCE_NAME",
    "region": "REGION",
    "databaseVersion": "DATABASE_VERSION",
    "onPremisesConfiguration": {
       "hostPort": "SOURCE_HOST:3306",
       "username": "REPLICATION_USER_NAME",
       "password": "REPLICATION_USER_PASSWORD",
       "dumpFilePath": "CLOUD_STORAGE_BUCKET"
       "caCertificate": "SOURCE_CERT",
       "clientCertificate": "CLIENT_CERT",
       "clientKey": "CLIENT_KEY"
     }
   }

   Properti	Deskripsi
   SOURCE_NAME	Nama instance representasi sumber yang akan dibuat.
   REGION	Region tempat Anda ingin menempatkan instance representasi sumber. Tentukan region yang sama tempat Anda akan membuat instance replika Cloud SQL target.
   DATABASE_VERSION	Versi database yang berjalan di server eksternal Anda. Satu-satunya opsi yang didukung adalah MYSQL_5_7 atau MYSQL_8_0.
   SOURCE_HOST	Alamat dan port IPv4 untuk server eksternal atau alamat DNS untuk server eksternal. Jika Anda menggunakan alamat DNS, alamat tersebut dapat berisi hingga 60 karakter.
   USERNAME	Akun pengguna replikasi di server eksternal.
   PASSWORD	Sandi untuk akun pengguna replikasi.
   CLOUD_STORAGE_BUCKET	Nama bucket Cloud Storage yang berisi file fisik XtraBackup.
   CLIENT_CA_CERT	Sertifikat CA di server eksternal. Hanya sertakan jika SSL/TLS digunakan di server eksternal.
   CLIENT_CERT	Sertifikat klien pada server eksternal. Hanya diperlukan untuk autentikasi server-klien. Hanya sertakan jika SSL/TLS digunakan di server eksternal.
   CLIENT_KEY	File kunci pribadi untuk sertifikat klien di server eksternal. Hanya diperlukan untuk autentikasi server-klien. Hanya sertakan jika SSL/TLS digunakan di server eksternal.

2. Buat instance representasi sumber dengan membuat permintaan ke Cloud SQL Admin API menggunakan perintah curl berikut. Dalam data untuk permintaan, berikan file source.json yang Anda buat.

   gcloud auth login
   ACCESS_TOKEN="$(gcloud auth print-access-token)"
   curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
       --header 'Content-Type: application/json' \
       --data @./source.json \
       -X POST \
   https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances

   Properti	Deskripsi
   PROJECT_ID	ID untuk project Anda di Trusted Cloud.

Mengidentifikasi instance replika target

Buat file yang mengidentifikasi replika target di Cloud SQL untuk migrasi. Anda dapat memigrasikan data ke instance baru dengan membuat replika, atau Anda dapat menggunakan instance Cloud SQL yang ada dengan menurunkan replika.

Opsi 1: Buat instance replika

1. Untuk membuat instance replika, gunakan contoh file replica.json berikut:

   {
   "name": "REPLICA_NAME",
   "region": "REGION",
   "databaseVersion": "DB_VERSION",
   "settings": {
      "tier": "INSTANCE_TIER",
      "dataDiskSizeGb": "DISK_SIZE_GB",
      "edition": "EDITION_NAME"
   },
   "masterInstanceName": "SOURCE_NAME"
   }

   Properti	Deskripsi
   REPLICA_NAME	Nama replika Cloud SQL yang akan dibuat.
   REGION	Tentukan region yang sama dengan yang Anda tetapkan ke instance representasi sumber.
   DATABASE_VERSION	Versi database yang akan digunakan dengan replika Cloud SQL. Opsi untuk versi ini adalah MYSQL_5_7 atau MYSQL_8_0. Versi utama database ini harus cocok dengan versi database yang Anda tetapkan untuk server eksternal. Anda juga dapat menentukan versi minor, tetapi versi minor harus sama atau lebih baru dari versi yang diinstal di server eksternal. Untuk mengetahui daftar string yang tersedia untuk MySQL, lihat SqlDatabaseVersion.
   INSTANCE_TIER	Jenis mesin untuk menghosting instance replika Anda. Anda harus menentukan jenis mesin yang cocok dengan edisi instance dan jenis arsitektur server eksternal Anda. Misalnya, jika Anda memilih ENTERPRISE_PLUS untuk kolom edition, Anda harus menentukan jenis mesin yang dioptimalkan untuk performa db. Untuk mengetahui daftar jenis mesin yang didukung, lihat Jenis Mesin.
   DISK_SIZE_GB	Ukuran penyimpanan untuk replika Cloud SQL, dalam GB.
   EDITION_NAME	Edisi Cloud SQL yang akan digunakan untuk replika. Kemungkinan nilainya adalah ENTERPRISE_PLUS (khusus MySQL 8.0) atau ENTERPRISE.
   SOURCE_NAME	Nama yang Anda tetapkan ke instance representasi sumber.

2. Buat instance replika target dengan membuat permintaan ke Cloud SQL Admin API menggunakan perintah curl berikut. Dalam data untuk permintaan, berikan file JSON yang Anda buat.

   gcloud auth login
   ACCESS_TOKEN="$(gcloud auth print-access-token)"
   curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
       --header 'Content-Type: application/json' \
       --data @./replica.json \
       -X POST \
   https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances

   Properti	Deskripsi
   PROJECT_ID	ID untuk project Anda di Trusted Cloud.

Opsi 2: Menggunakan instance replika yang ada

1. Pastikan instance replika yang ada memiliki atribut berikut:

   • Jenis arsitektur yang sama (x86 atau ARM) dengan server eksternal.
   • Setidaknya ruang disk kosong yang sama dengan file fisik yang Anda upload ke bucket Cloud Storage. Instance harus memiliki disk yang cukup untuk mendownload data dalam jumlah yang sama dari Cloud Storage.

2. Untuk menggunakan instance replika yang ada, gunakan contoh file replica.json berikut:

   {
   "demoteContext": {
       "sourceRepresentativeInstanceName": "SOURCE_NAME"
     }
   }

   Properti	Deskripsi
   SOURCE_NAME	Nama yang Anda tetapkan ke instance representasi sumber.

3. Turunkan instance replika target yang ada dengan membuat permintaan ke Cloud SQL Admin API yang diturunkan dengan perintah curl berikut. Dalam data untuk permintaan, berikan file JSON yang Anda buat.

   gcloud auth login
   ACCESS_TOKEN="$(gcloud auth print-access-token)"
   curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
       --header 'Content-Type: application/json' \
       --data @./replica.json \
       -X POST \
   https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/EXISTING_INSTANCE_ID/demote

   Properti	Deskripsi
   PROJECT_ID	ID untuk project Anda di Trusted Cloud.
   EXISTING_INSTANCE_ID	ID untuk instance replika yang ada yang ingin Anda gunakan untuk migrasi.

Memverifikasi setelan migrasi Anda

Periksa apakah instance Anda disiapkan dengan benar untuk migrasi dengan menjalankan perintah berikut.

gcloud auth login
ACCESS_TOKEN="$(gcloud auth print-access-token)"
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     --header 'Content-Type: application/json' \
     --data '{
             "syncMode": "SYNC_MODE",
             "skipVerification": false,
             "migrationType": "PHYSICAL"
               }' \
     -X POST \
https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/REPLICA_NAME/verifyExternalSyncSettings

Properti	Deskripsi
SYNC_MODE	Tentukan offline untuk mengonfigurasi migrasi sebagai proses sekali saja. Untuk menyiapkan replikasi berkelanjutan dari server eksternal, tentukan online.
PROJECT_ID	ID project Anda di Trusted Cloud.
REPLICA_NAME	Nama yang Anda tetapkan ke instance replika target.

Sebagai respons awal, langkah verifikasi ini menampilkan akun layanan. Anda harus memberi akun layanan ini izin Cloud Storage untuk melanjutkan proses migrasi. Pesan error izin yang tidak memadai sudah diperkirakan. Berikut adalah contoh respons:

{
    "kind": "sql#externalSyncSettingError",
    "type": "INSUFFICIENT_GCS_PERMISSIONS",
    "detail": "Service account
              p703314288590-df3om0@my-project.s3ns-system.iam.gserviceaccount.com
              is missing necessary permissions storage.objects.list and
              storage.objects.get to access Google Cloud Storage bucket"
}

Menambahkan izin Cloud Storage ke akun layanan yang ditampilkan

Untuk menambahkan izin yang diperlukan, lakukan hal berikut:

1. Di Trusted Cloud konsol, buka halaman Bucket Cloud Storage.

   Buka Buckets

2. Klik tab Izin.

3. Klik Grant Access.

4. Di kolom New principals, ketik nama akun layanan yang ditampilkan dalam respons verifikasi. Misalnya, dalam contoh output dari langkah sebelumnya, nama akun layanan yang ditampilkan adalah p703314288590-df3om0@my-project.s3ns-system.iam.gserviceaccount.com.

5. Di menu drop-down Pilih peran, pilih peran Storage Object Viewer.

6. Klik Simpan.

Jalankan verifikasi lagi

Setelah Anda menambahkan izin yang diperlukan ke akun layanan, jalankan kembali langkah verifikasi untuk memastikan akun layanan memiliki akses ke bucket Cloud Storage.

Langkah verifikasi memeriksa hal-hal berikut:

• Konektivitas antara replika Cloud SQL dan server eksternal ada, tetapi hanya jika migrasi berkelanjutan
• Hak istimewa pengguna replikasi sudah memadai
• Versi kompatibel
• Replika Cloud SQL belum direplikasi
• Binlog diaktifkan di server eksternal

Jika ada masalah yang terdeteksi, Cloud SQL akan menampilkan pesan error.

Menambahkan pengguna ke replika Cloud SQL

Anda tidak dapat mengimpor atau memigrasikan akun pengguna database dari server eksternal. Jika Anda perlu menambahkan akun pengguna database ke replika Cloud SQL, tambahkan akun tersebut sebelum Anda memulai replikasi. Untuk mengetahui informasi selengkapnya, lihat Mengelola pengguna dengan autentikasi bawaan.

Mulai migrasi

Setelah Anda menyelesaikan verifikasi dan tidak ada error yang ditampilkan, Anda siap memulai migrasi. Untuk memigrasikan server eksternal, gunakan startExternalSync API.

Gunakan perintah berikut:

gcloud auth login
ACCESS_TOKEN="$(gcloud auth print-access-token)"
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     --header 'Content-Type: application/json' \
     --data '{
               "syncMode": "SYNC_MODE",
               "skipVerification": false,
               "migrationType": "PHYSICAL"
              }' \
     -X POST \
https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/REPLICA_NAME/startExternalSync

Properti	Deskripsi
SYNC_MODE	Tentukan offline untuk mengonfigurasi migrasi sebagai proses sekali saja. Untuk menyiapkan replikasi berkelanjutan dari server eksternal, tentukan online.
PROJECT_ID	ID project Anda di Trusted Cloud.
REPLICA_NAME	Nama yang Anda tetapkan ke instance replika target.

Memantau migrasi

Untuk memeriksa status migrasi, Anda dapat melakukan hal berikut:

1. Ambil ID operasi tugas migrasi dari respons startExternalSync API. Contoh:

   {
   "kind": "sql#operation",
    "targetLink": "https://sqladmin.googleapis.com/v1/projects/my-project/instances/replica-instance",
    "status": "PENDING",
    "user": "user@example.com",
    "insertTime": "******",
    "operationType": "START_EXTERNAL_SYNC",
    "name": "******",
    "targetId": "replica-instance",
    "selfLink": "https://sqladmin.googleapis.com/v1/projects/my-project/operations/OPERATION_ID",
    "targetProject": "my-project"
   }
   

2. Gunakan ID operasi dalam perintah berikut.

   gcloud auth login
   ACCESS_TOKEN="$(gcloud auth print-access-token)"
   curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
       --header 'Content-Type: application/json' \
       -X GET \
   https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/START_EXTERNAL_SYNC_OPERATION_ID

   Properti	Deskripsi
   PROJECT_ID	ID untuk project Anda di Trusted Cloud.
   START_EXTERNAL_SYNC_OPERATION_ID	ID operasi tugas migrasi Anda.

Pantau replikasi

Setelah instance replika target di Cloud SQL menyelesaikan pemuatan data awal, instance tersebut terhubung ke server eksternal dan menerapkan semua update yang dilakukan setelah operasi ekspor.

Untuk memantau status replikasi, lihat Konfirmasi status replikasi Anda.

Setelah replika Cloud SQL menerima semua perubahan dari server eksternal dan tidak ada penundaan replikasi pada replika Cloud SQL, hubungkan ke database Anda. Jalankan perintah database yang sesuai untuk memastikan bahwa konten sesuai harapan jika dibandingkan dengan server eksternal.

Setelah mempromosikan replika target ke instance mandiri, Anda dapat menghapus file fisik XtraBackup di bucket Cloud Storage. Pertahankan server eksternal Anda hingga validasi yang diperlukan selesai.

Batasan

Bagian ini mencantumkan batasan terkait proses migrasi XtraBackup:

• Anda harus menggunakan Percona XtraBackup untuk mencadangkan data ke bucket Cloud Storage. Utilitas pencadangan lainnya tidak didukung.
• Migrasi tidak didukung ke versi utama atau minor database yang lebih lama. Misalnya, Anda tidak dapat melakukan migrasi dari MySQL 8.0 ke 5.7 atau dari MySQL 8.0.36 ke 8.0.16.
• Migrasi database dari file fisik XtraBackup hanya didukung untuk database MySQL lokal atau database MySQL yang dikelola sendiri yang berjalan di VM Compute Engine. Migrasi dari database Amazon Aurora atau MySQL di Amazon RDS tidak didukung.
• Anda hanya dapat melakukan migrasi dari pencadangan penuh. Jenis pencadangan lainnya, seperti pencadangan inkremental atau sebagian, tidak didukung.
• Migrasi database tidak mencakup pengguna atau hak istimewa database.
• Anda harus menetapkan format log biner ke ROW. Jika Anda mengonfigurasi log biner ke format lain, seperti STATEMENT atau MIXED, replikasi mungkin gagal.
• Cloud Storage membatasi ukuran file yang dapat Anda upload ke bucket hingga 5 TB.
• Anda tidak dapat memigrasikan plugin apa pun dari database eksternal.
• Jika Anda telah mengonfigurasi ketersediaan tinggi untuk instance Anda, SLA tidak berlaku hingga fase awal migrasi selesai. Fase ini dianggap selesai setelah semua data dari file fisik XtraBackup diimpor ke instance Cloud SQL.
• Anda tidak dapat melakukan migrasi ke atau dari database MySQL 8.4.
• Migrasi database antar-mesin dengan jenis arsitektur yang berbeda tidak didukung. Misalnya, Anda tidak dapat memigrasikan database MySQL yang dihosting di mesin dengan arsitektur ARM ke mesin dengan arsitektur x86.

Memecahkan masalah

Bagian ini mencantumkan skenario pemecahan masalah umum.

Gagal mengimpor

Jika Anda mengalami pesan error yang mirip dengan Attempt 1/2: import failed saat melakukan migrasi, Anda harus menentukan PHYSICAL untuk migrationType saat memulai migrasi.

Jika Anda tidak menentukan migrationType, jenisnya akan ditetapkan secara default ke LOGICAL.

Membatalkan atau menghentikan migrasi

Jika Anda perlu membatalkan atau menghentikan migrasi, Anda dapat menjalankan perintah berikut:

gcloud auth login
ACCESS_TOKEN="$(gcloud auth print-access-token)"
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     --header 'Content-Type: application/json' \
    -X POST \
https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/REPLICA_NAME/restart

Properti	Deskripsi
PROJECT_ID	ID project Anda di Trusted Cloud.
REPLICA_NAME	Nama yang Anda tetapkan ke instance replika target.

Langkah berikutnya

• Promosikan replika menjadi instance utama.
• Menambahkan replika baca ke instance Anda
• Konfigurasi instance Anda untuk ketersediaan tinggi (HA)