Bermigrasi ke Cloud SQL dari file fisik XtraBackup

MySQL | PostgreSQL | SQL Server

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 reguler.

Cloud SQL mendukung migrasi fisik berbasis file untuk MySQL 5.7 dan 8.0. MySQL 5.6 tidak didukung. Migrasi dari Amazon Aurora atau MySQL di database 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, replika target Anda harus berupa Cloud SQL untuk MySQL versi 8.0.31 atau yang lebih baru.

Prosedur dalam dokumen ini menggunakan Cloud SQL untuk MySQL Admin API. Anda juga dapat menggunakan Database Migration Service untuk melakukan migrasi ini. Untuk informasi selengkapnya tentang cara menggunakan Database Migration Service, lihat Memigrasikan database menggunakan file fisik Percona XtraBackup.

Sebelum memulai

Bagian ini menjelaskan langkah-langkah yang perlu dilakukan sebelum memigrasikan database MySQL Anda ke Google Cloud.

Menyiapkan project Google Cloud

Login ke akun Google Cloud Anda. Jika Anda baru menggunakan Google Cloud, buat akun untuk mengevaluasi performa produk kami dalam skenario dunia nyata. Pelanggan baru juga mendapatkan kredit gratis senilai $300 untuk menjalankan, menguji, dan men-deploy workload.

Di konsol Google Cloud, pada halaman pemilih project, pilih atau buat project Google Cloud.

Buka pemilih project

Pastikan penagihan telah diaktifkan untuk project Google Cloud Anda.

Enable the Cloud SQL Admin API.

Enable the API

Di konsol Google Cloud, pada halaman pemilih project, pilih atau buat project Google Cloud.

Buka pemilih project

Pastikan penagihan telah diaktifkan untuk project Google Cloud Anda.

Enable the Cloud SQL Admin API.

Enable the API

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 Google Cloud SDK.

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

Menyiapkan server eksternal untuk migrasi

Instal salah satu versi utilitas XtraBackup berikut di server eksternal.
- 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 versi XtraBackup yang sama atau lebih tinggi dari versi server sumber. Untuk informasi selengkapnya, lihat Perbandingan versi server dan versi cadangan dalam dokumentasi Percona XtraBackup.
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 Amazon Aurora atau MySQL di database 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 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 pada database eksternal sumber Anda harus dikonfigurasi dengan nilai default 16384.
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

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

Jenis pencadangan lain, seperti pencadangan inkremental dan sebagian, tidak didukung.

Contoh:
```
sudo xtrabackup --backup \
--target-dir=XTRABACKUP_PATH \
--user=USERNAME \
--password=PASSWORD
```
Ganti variabel berikut:
- XTRABACKUP_PATH: lokasi file cadangan output
- USERNAME: pengguna yang memiliki hak istimewa BACKUP_ADMIN di database sumber
- PASSWORD: sandi untuk pengguna
Gunakan utilitas XtraBackup untuk menyiapkan file cadangan. File harus dalam status yang konsisten. Untuk informasi selengkapnya tentang menyiapkan pencadangan penuh, lihat Menyiapkan pencadangan penuh. Contoh:
```
sudo xtrabackup --prepare --target-dir=XTRABACKUP_PATH
```
Ganti XTRABACKUP_PATH dengan lokasi file cadangan output. Proses penyelesaian perintah ini mungkin memerlukan waktu beberapa menit, bergantung pada ukuran database Anda.

Mengupload file fisik XtraBackup ke Cloud Storage

Gunakan utilitas gsutil untuk mengupload file cadangan ke Cloud Storage.

  time gsutil -m rsync -r XTRABACKUP_PATH CLOUD_STORAGE_BUCKET

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

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

Menentukan instance representasi sumber

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

Dalam 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. Sertakan hanya jika SSL/TLS digunakan di server eksternal.
`CLIENT_CERT`	Sertifikat klien pada server eksternal. Hanya diperlukan untuk autentikasi server-klien. Sertakan hanya jika SSL/TLS digunakan di server eksternal.
`CLIENT_KEY`	File kunci pribadi untuk sertifikat klien pada server eksternal. Hanya diperlukan untuk autentikasi server-klien. Hanya sertakan jika SSL/TLS digunakan di server eksternal.

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 telah 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 Google 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 menggunakan instance Cloud SQL yang sudah ada dengan mendemosikan replika.

Opsi 1: Membuat instance replika

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 tentukan untuk server eksternal. Anda juga dapat menentukan versi minor, tetapi versi minor harus sama atau versi yang lebih baru dari versi yang diinstal di server eksternal. Untuk 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 Anda. Misalnya, jika Anda menentukan `ENTERPRISE_PLUS` untuk kolom `edition`, Anda harus menentukan jenis mesin yang dioptimalkan dengan db-perf. Untuk daftar jenis mesin yang didukung, lihat Machine Type.
`DISK_SIZE_GB`	Ukuran penyimpanan untuk replika Cloud SQL, dalam GB. Penting: Anda harus menentukan ukuran penyimpanan yang lebih besar dari ukuran file fisik yang Anda upload ke Cloud Storage.
`EDITION_NAME`	Edisi Cloud SQL yang akan digunakan untuk replika. Nilai yang mungkin adalah `ENTERPRISE_PLUS` (khusus MySQL 8.0) atau `ENTERPRISE`.
`SOURCE_NAME`	Nama yang Anda tetapkan ke instance representasi sumber.

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 Google Cloud.

Opsi 2: Gunakan instance replika yang ada

Pastikan instance replika yang ada memiliki jumlah kapasitas disk kosong yang sama dengan file fisik yang Anda upload ke bucket Cloud Storage. Instance harus memiliki disk yang cukup untuk mendownload jumlah data yang sama dari Cloud Storage.
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.
Demosikan instance replika target yang ada dengan membuat permintaan ke mendemosikan 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/EXISTING_INSTANCE_ID/demote
```
Properti Deskripsi

PROJECT_ID ID untuk project Anda di Google Cloud.

EXISTING_INSTANCE_ID ID untuk instance replika yang ada yang ingin Anda gunakan untuk migrasi.

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

Memverifikasi setelan migrasi Anda

Pastikan instance Anda sudah 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 satu kali. Untuk menyiapkan replikasi berkelanjutan dari server eksternal, tentukan `online`.
`PROJECT_ID`	ID project Anda di Google Cloud.
`REPLICA_NAME`	Nama yang Anda tetapkan ke instance replika target.

Sebagai respons awal, langkah verifikasi ini akan menampilkan akun layanan. Anda harus memberikan izin Cloud Storage ke akun layanan ini untuk melanjutkan proses migrasi. Diharapkan pesan error izin tidak memadai. Berikut adalah contoh respons:

{
    "kind": "sql#externalSyncSettingError",
    "type": "INSUFFICIENT_GCS_PERMISSIONS",
    "detail": "Service account
              [email protected]
              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:

Di konsol Google Cloud, buka halaman Buckets Cloud Storage.

Buka Buckets
Klik tab Izin.
Klik Grant Access.
Di kolom New principals, ketik nama akun layanan yang ditampilkan dalam respons verifikasi. Misalnya, dalam contoh output langkah sebelumnya, nama akun layanan yang ditampilkan adalah [email protected].
Di drop-down Pilih peran, pilih peran Storage Object Viewer.
Klik Save.

Menjalankan 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 akan memeriksa hal-hal berikut:

Ada konektivitas antara replika Cloud SQL dan server eksternal, tetapi hanya jika migrasi bersifat berkelanjutan
Hak istimewa pengguna replikasi sudah cukup
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 memulai replikasi. Untuk informasi lebih lanjut, lihat Mengelola pengguna dengan autentikasi bawaan.

Memulai migrasi

Setelah menyelesaikan verifikasi dan tidak ada error yang ditampilkan, Anda siap untuk 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 satu kali. Untuk menyiapkan replikasi berkelanjutan dari server eksternal, tentukan `online`.
`PROJECT_ID`	ID project Anda di Google Cloud.
`REPLICA_NAME`	Nama yang Anda tetapkan ke instance replika target.

Memantau migrasi

Untuk memeriksa status migrasi, Anda dapat melakukan hal berikut:

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": "[email protected]",
 "insertTime": "******",
 "operationType": "START_EXTERNAL_SYNC",
 "name": "******",
 "targetId": "replica-instance",
 "selfLink": "https://sqladmin.googleapis.com/v1/projects/my-project/operations/OPERATION_ID",
 "targetProject": "my-project"
}

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 Google Cloud.
`START_EXTERNAL_SYNC_OPERATION_ID`	ID operasi tugas migrasi Anda.

Memantau replikasi

Saat 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 Mengonfirmasi 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 konten sesuai dengan yang diharapkan 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 pada proses migrasi XtraBackup:

Anda harus menggunakan Percona XtraBackup untuk mencadangkan data ke bucket Cloud Storage. Utilitas pencadangan lainnya tidak didukung.
Migrasi tidak didukung untuk versi utama atau minor database yang lama. Misalnya, Anda tidak dapat bermigrasi 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 Amazon Aurora atau MySQL di database Amazon RDS tidak didukung.
Anda hanya dapat bermigrasi dari cadangan penuh. Jenis pencadangan lainnya, seperti pencadangan inkremental atau sebagian, tidak didukung.
Migrasi database tidak menyertakan hak istimewa atau pengguna database.
Anda harus menyetel format log biner ke ROW. Jika Anda mengonfigurasi log biner ke format lain, seperti STATEMENT atau MIXED, replikasi mungkin akan gagal.
Cloud Storage membatasi ukuran file yang dapat diupload ke bucket hingga 5 TB.
Anda tidak dapat memigrasikan plugin apa pun dari database eksternal.
Jika Anda telah mengonfigurasi ketersediaan tinggi untuk instance, SLA tidak akan berlaku hingga fase awal migrasi selesai. Fase ini dianggap selesai ketika semua data dari file fisik XtraBackup telah diimpor ke instance Cloud SQL.

Memecahkan masalah

Bagian ini mencantumkan skenario pemecahan masalah umum.

Gagal mengimpor

Jika Anda mendapatkan pesan error yang mirip dengan Attempt 1/2: import failed saat bermigrasi, 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 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 Google Cloud.
`REPLICA_NAME`	Nama yang Anda tetapkan ke instance replika target.

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

Bermigrasi ke Cloud SQL dari file fisik XtraBackup

Sebelum memulai

Menyiapkan project Google Cloud

Menyiapkan bucket Cloud Storage

Instal Google Cloud SDK.

Menyiapkan server eksternal untuk migrasi

Melakukan migrasi

Membuat dan menyiapkan file fisik XtraBackup

Mengupload file fisik XtraBackup ke Cloud Storage

Menentukan instance representasi sumber

Mengidentifikasi instance replika target

Opsi 1: Membuat instance replika

Opsi 2: Gunakan instance replika yang ada

Memverifikasi setelan migrasi Anda

Menambahkan izin Cloud Storage ke akun layanan yang ditampilkan

Menjalankan verifikasi lagi

Menambahkan pengguna ke replika Cloud SQL

Memulai migrasi

Memantau migrasi

Memantau replikasi

Batasan

Memecahkan masalah

Gagal mengimpor

Membatalkan atau menghentikan migrasi

Langkah selanjutnya