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

  1. 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.
  2. Di konsol Google Cloud, pada halaman pemilih project, pilih atau buat project Google Cloud.

    Buka pemilih project

  3. Pastikan penagihan telah diaktifkan untuk project Google Cloud Anda.

  4. Aktifkan API Cloud SQL Admin.

    Mengaktifkan API

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

    Buka pemilih project

  6. Pastikan penagihan telah diaktifkan untuk project Google Cloud Anda.

  7. Aktifkan API Cloud SQL Admin.

    Mengaktifkan API

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

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

    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.

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

  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.

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

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

Opsi 2: Gunakan instance replika yang ada

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

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

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
              p703314288590-df3om0@my-project.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 konsol Google Cloud, buka halaman Buckets 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 langkah sebelumnya, nama akun layanan yang ditampilkan adalah p703314288590-df3om0@my-project.iam.gserviceaccount.com.

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

  6. 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:

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

Langkah selanjutnya