Mendiagnosis masalah untuk migrasi homogen ke Cloud SQL untuk PostgreSQL

Proses tugas migrasi mungkin mengalami error selama runtime.

  • Beberapa error, seperti sandi yang salah di database sumber, dapat dipulihkan, yang berarti error tersebut dapat diperbaiki dan tugas migrasi dilanjutkan secara otomatis.
  • Beberapa error tidak dapat dipulihkan, seperti error dalam replikasi data, yang berarti tugas migrasi harus dimulai ulang dari awal.

Saat error terjadi, status tugas migrasi akan berubah menjadi Failed, dan substatus mencerminkan status terakhir sebelum kegagalan.

Untuk memecahkan masalah error, buka tugas migrasi yang gagal untuk melihat error dan ikuti langkah-langkah yang diuraikan dalam pesan error.

Untuk melihat detail selengkapnya tentang error, buka Cloud Monitoring menggunakan link di tugas migrasi. Log difilter ke tugas migrasi tertentu.

Dalam tabel berikut, Anda dapat menemukan beberapa contoh masalah dan cara mengatasinya:

Untuk masalah ini... Kemungkinan masalah... Coba langkah ini...
Saat memigrasikan ke instance tujuan yang ada, Anda akan menerima pesan error berikut: The destination instance contains existing data or user defined entities (for example databases, tables, or functions). You can only migrate to empty instances. Clear your destination instance and retry the migration job. Instance Cloud SQL tujuan Anda berisi data tambahan. Anda hanya dapat bermigrasi ke instance yang sudah ada dan kosong. Lihat Batasan umum. Promosikan instance tujuan Anda untuk menjadikannya instance baca/tulis, hapus data tambahan, dan coba lagi tugas migrasi. Lihat Menghapus data tambahan dari instance tujuan yang ada.
Gagal terhubung ke instance database sumber. Terjadi masalah konektivitas antara instance database sumber dan instance tujuan. Ikuti langkah-langkah di Men-debug konektivitas.
Kegagalan menjalankan tugas migrasi karena versi database sumber dan tujuan tidak kompatibel. Versi database sumber dan tujuan bukan merupakan kombinasi yang didukung. Secara khusus, versi database sumber yang diberikan tidak kompatibel dengan versi database tujuan. Pastikan versi database tujuan sama atau satu versi utama di atas versi database sumber. Kemudian, buat tugas migrasi baru.
Bahasa definisi data (DDL) atau bahasa manipulasi data (DML) diblokir di sumber. DDL yang memerlukan kunci ACCESS EXCLUSIVE dan berjalan selama fase dump penuh akan diblokir.

Selama proses sinkronisasi awal (dump penuh), DDL atau program yang memerlukan kunci ACCESS EXCLUSIVE seperti ALTER TABLE atau DROP TABLE harus dihindari di tabel. Jika tidak, DDL atau program akan menunggu hingga sinkronisasi awal selesai.

Misalnya, jika tabel masih dalam proses sinkronisasi awal dan perintah ALTER TABLE dijalankan pada tabel yang sama, perintah tersebut tidak akan dijalankan dan perintah DDL dan DML berikutnya akan diblokir hingga sinkronisasi awal selesai.
Pesan Error: No pglogical extension installed on databases (X) Satu atau beberapa database sumber tidak menginstal pglogical. Ikuti panduan ini untuk menginstal pglogical di database pada instance sumber.
Saat bermigrasi ke PostgreSQL versi 15, setelah beberapa upaya percobaan ulang koneksi berikutnya, salah satu gejala berikut akan terjadi: Masalah ini sering kali dikaitkan dengan masalah deadlock di ekstensi pglogical. Untuk mengetahui informasi selengkapnya, lihat Issue Tracker pglogical di GitHub. Coba lagi tugas migrasi, atau migrasikan ke versi PostgreSQL perantara terlebih dahulu. Untuk mengetahui detail selengkapnya, lihat Pesan error: Cannot connect to invalid database.
Pesan Error: Replication user 'x' doesn't have sufficient privileges. Pengguna yang menggunakan Database Migration Service tidak memiliki hak istimewa yang diperlukan untuk melakukan operasi yang ditetapkan. Ikuti panduan ini untuk memastikan bahwa pengguna ini memiliki hak istimewa yang diperlukan.
Pesan Error: Unable to connect to source database server. Layanan Migrasi Database tidak dapat membuat koneksi ke server database sumber. Pastikan instance database sumber dan tujuan dapat berkomunikasi satu sama lain, dan bahwa Anda telah menyelesaikan semua prasyarat yang diperlukan yang muncul saat Anda menentukan setelan untuk tugas migrasi.
Pesan Error: The source database 'wal_level' configuration must be equal to 'logical'. wal_level untuk database sumber ditetapkan ke nilai selain logical. Tetapkan wal_level ke logical.
Pesan Error: The source database 'max_replication_slots' configuration is not sufficient. Parameter max_replication_slots tidak dikonfigurasi dengan benar. Ikuti panduan ini untuk menetapkan parameter ini dengan benar.
Pesan Error: The source database 'max_wal_senders' configuration is not sufficient. Parameter max_wal_senders tidak dikonfigurasi dengan benar. Ikuti panduan ini untuk menetapkan parameter ini dengan benar.
Pesan Error: The source database 'max_worker_processes' configuration is not sufficient. Parameter max_worker_processes tidak dikonfigurasi dengan benar. Ikuti panduan ini untuk menetapkan parameter ini dengan benar.

Pesan Error: Cleanup may have failed on source due to error: generic::unknown: failed to connect to on-premises database.

ATAU

Pesan Error: Error promoting EM replica: finished drop replication with errors.

Setelan yang diperlukan untuk replikasi tidak dapat dihapus selama promosi tugas migrasi.

Untuk setiap database, jalankan perintah sebagai pengguna dengan hak istimewa superuser.

Untuk informasi selengkapnya tentang perintah yang akan dijalankan, lihat Menghapus slot replikasi.

Pesan Error: x509 certificate signed by unknown authority.

Sertifikat CA sumber yang diberikan ke Database Migration Service mungkin hanya berisi root certificate. Namun, sertifikat sumber memerlukan root certificate dan intermediate certificate.

Misalnya, untuk Amazon Relational Database Service, penggunaan sertifikat rds-ca-2019-root.pem dapat menyebabkan masalah ini.

Buat sertifikat CA sumber gabungan yang berisi root certificate dan semua intermediate certificate yang diperlukan.

Untuk kasus penggunaan Amazon Relational Database Service, gunakan sertifikat rds-combined-ca-bundle.pem, bukan sertifikat rds-ca-2019-root.pem.

Pesan Error: ERROR: Out of shared memory HINT: You might need to increase max_locks_per_transaction.

Nilai yang ditetapkan untuk parameter max_locks_per_transaction tidak memadai. Tetapkan nilai untuk parameter ini minimal {max_number_of_tables_per_database}/(max_connections + max_prepared_transactions).

Pesan Error: ERROR: no data left in message.

Paket pglogical tidak diinstal dengan benar di instance sumber. Untuk informasi selengkapnya tentang cara menginstal paket ini dengan benar, lihat Menginstal paket pglogical di instance sumber.

Pesan Error: Cannot assign TransactionIds during recovery.

Sumber yang dikonfigurasi berada dalam mode pemulihan. Konfigurasikan sumber yang tidak dalam mode pemulihan.
Dump penuh lambat. Tujuan Cloud SQL mungkin lambat dalam mengimpor data besar dari database sumber.
  • Saat membuat tujuan, tetapkan ukuran disk data agar mendekati ukuran akhir. Fase dump penuh menggunakan beban kerja penulisan I/O yang intensif, dan ukuran disk yang lebih besar memiliki performa I/O yang lebih baik. Untuk mengetahui informasi selengkapnya, lihat Performa block storage.
  • Pilih tingkat yang lebih tinggi untuk tujuan Cloud SQL guna mendapatkan bandwidth jaringan dan disk maksimum yang tersedia.
  • Sesuaikan flag max_wal_size tujuan Cloud SQL. Biasanya, 32 GB atau 64 GB adalah nilai yang baik untuk ditetapkan untuk flag ini. Memperbarui tanda ini tidak mengharuskan Anda memulai ulang server.
Pesan Error: subscriber {subscriber_name} initialization failed during nonrecoverable step (d), please try the setup again

Tugas migrasi gagal selama fase dump penuh dan tugas tidak dapat dipulihkan. Instance database sumber dimulai ulang atau dalam mode pemulihan, atau koneksi replikasi berakhir karena nilai yang ditetapkan untuk parameter wal_sender_timeout tidak memadai.

Untuk menemukan akar masalah:

  1. Buka halaman Logs Explorer di Konsol Google Cloud .
  2. Dari daftar resource, pilih replika Cloud SQL Anda. Daftar log terbaru untuk replika akan muncul.
  3. Dari nama file log, pilih postgres.log.
  4. Tetapkan tingkat keparahan log ke semua level di atas Warning. Log error pertama mungkin merupakan akar penyebab kegagalan.
  • Pastikan Database Migration Service selalu dapat terhubung ke instance database sumber selama fase dump penuh.
  • Periksa apakah nilai parameter wal_sender_timeout ditetapkan ke angka yang lebih besar (misalnya, 0) pada instance database sumber.
  • Mulai ulang tugas migrasi, lalu coba lagi.
Pesan Error: ERROR: unknown column name {column_name}

Kolom ditambahkan ke tabel yang direplikasi di node utama, tetapi tidak di node replika.

Hanya perubahan bahasa manipulasi data (DML) yang diperbarui secara otomatis selama migrasi berkelanjutan. Mengelola perubahan bahasa definisi data (DDL) agar database sumber dan tujuan tetap kompatibel adalah tanggung jawab pengguna, dan dapat dilakukan dengan dua cara:

  • Hentikan penulisan ke database sumber dan jalankan perintah DDL di sumber dan tujuan. Sebelum menjalankan perintah DDL di tujuan, berikan peran cloudsqlexternalsync kepada pengguna Cloud SQL yang menerapkan perubahan DDL.
  • Gunakan pglogical.replicate_ddl_command untuk mengizinkan perintah DDL dijalankan di sumber dan tujuan pada titik yang konsisten. Pengguna yang menjalankan perintah harus memiliki nama pengguna yang sama di sumber dan tujuan, serta harus merupakan superuser atau pemilik artefak yang dimigrasikan (misalnya, tabel, urutan, tampilan, atau database).

    • Lihat Migrasi berkelanjutan untuk menemukan contoh penggunaan pglogical.replicate_ddl_command.
Pesan Error: ERROR: cannot truncate a table referenced in a foreign key constraint

Pengguna mencoba memotong tabel yang memiliki batasan kunci asing.

Hapus batasan kunci asing terlebih dahulu, lalu potong tabel.
Pesan Error: ERROR: connection to other side has died

Koneksi replikasi berakhir karena nilai yang ditetapkan untuk wal_sender_timeout parameter tidak mencukupi. Error biasanya terjadi selama fase replikasi setelah dump awal berhasil.

Pertimbangkan untuk menaikkan nilai parameter wal_sender_timeout atau menonaktifkan mekanisme waktu tunggu dengan menetapkan nilainya ke 0 pada instance database sumber.
Pesan Peringatan: migration job test configuration has returned the following warnings: Some table(s) have limited support.

Sumber memiliki tabel dengan dukungan terbatas, misalnya tabel tanpa kunci utama.

Ini adalah pesan peringatan. Anda dapat melanjutkan migrasi, tetapi perhatikan bahwa entitas yang tidak didukung (misalnya tabel tanpa kunci utama) tidak akan dimigrasikan. Untuk informasi selengkapnya, tinjau Mengonfigurasi database sumber.

Menghapus data tambahan dari instance tujuan yang ada

Saat memigrasikan ke instance tujuan yang ada, Anda akan menerima pesan error berikut: The destination instance contains existing data or user defined entities (for example databases, tables, or functions). You can only migrate to empty instances. Clear your destination instance and retry the migration job.

Masalah ini dapat terjadi jika instance tujuan Anda berisi data tambahan. Anda hanya dapat bermigrasi ke instance yang sudah ada dan kosong. Lihat Batasan umum.

Hal-hal yang sebaiknya dicoba

Hapus data tambahan dari instance tujuan dan mulai lagi tugas migrasi dengan melakukan langkah-langkah berikut:

  1. Hentikan tugas migrasi.
  2. Pada tahap ini, instance Cloud SQL tujuan Anda berada dalam mode `hanya baca`. Promosikan instance tujuan untuk mendapatkan akses tulis.
  3. Hubungkan ke instance Cloud SQL tujuan Anda.
  4. Hapus data tambahan dari database instance tujuan Anda. Tujuan Anda hanya dapat berisi data konfigurasi sistem. Database tujuan tidak boleh berisi data pengguna (seperti tabel). Ada berbagai pernyataan SQL yang dapat Anda jalankan di database untuk menemukan data non-sistem, misalnya:

    Contoh pernyataan SQL untuk mengambil database non-sistem (klik untuk meluaskan)

    SELECT datname FROM pg_catalog.pg_database
WHERE datname NOT IN ('cloudsqladmin', 'template1', 'template0', 'postgres');

    Contoh pernyataan SQL untuk mengambil data non-sistem di database postgres (klik untuk meluaskan)

    Database postgres adalah database sistem, tetapi dapat berisi data non-sistem. Pastikan Anda menjalankan pernyataan ini di database postgres. Jika menggunakan klien psql untuk terhubung ke instance tujuan, Anda dapat beralih ke database lain tanpa mereset koneksi menggunakan perintah \connect {database_name_here}.

    SELECT table_schema, table_name FROM information_schema.tables
WHERE table_schema != 'information_schema' AND table_schema not like 'pg\_%';

SELECT routine_schema, routine_name FROM information_schema.routines
WHERE routine_schema != 'information_schema' AND routine_schema not like 'pg\_%';

SELECT extname FROM pg_extension WHERE extname != 'plpgsql';
  5. Mulai tugas migrasi.

Membersihkan slot replikasi

Anda akan melihat salah satu pesan berikut:

  • Cleanup may have failed on source due to error: generic::unknown: failed to connect to on-premises database.
  • Error promoting EM replica: finished drop replication with errors.

Masalahnya mungkin adalah

Saat mempromosikan instance Cloud SQL, jika instance sumber tidak dapat dijangkau dari instance Cloud SQL (misalnya, instance sumber tidak berjalan, atau Anda menghapus instance Cloud SQL dari daftar yang diizinkan untuk instance sumber), setelan yang diperlukan untuk replikasi tidak dapat dihapus selama promosi tugas migrasi. Anda harus membersihkan slot replikasi secara manual.

Hal-hal yang sebaiknya dicoba

Untuk setiap database, jalankan perintah berikut sebagai pengguna dengan hak istimewa superuser:

  1. Dapatkan nama slot replikasi dari pesan error, lalu jalankan perintah berikut untuk menghapus slot, satu per satu:

    select pg_drop_replication_slot({slot_name});

  2. Jika nama slot replikasi tidak tersedia dalam pesan error, jalankan perintah berikut untuk membuat kueri slot replikasi yang ada:

    select pg_drop_replication_slot(slot_name) from pg_replication_slots where slot_name like '%cloudsql%' and active = 'f';

  3. Jika tidak ada replika Cloud SQL yang menggunakan instance sumber, jalankan perintah berikut untuk membersihkan setelan pglogical:

    select pglogical.drop_node(node_name) from pglogical.node where node_name like 'cloudsql';

  4. Jika ekstensi pglogical tidak diperlukan lagi, jalankan perintah berikut untuk meng-uninstal ekstensi:

    DROP EXTENSION IF EXISTS pglogical;

Pesan error: Cannot connect to invalid database

Saat bermigrasi ke PostgreSQL versi 15, setelah beberapa upaya percobaan ulang koneksi berikutnya, salah satu gejala berikut akan terjadi:

Masalahnya mungkin adalah

Masalah ini sering kali dikaitkan dengan masalah deadlock di ekstensi pglogical. Untuk mengetahui informasi selengkapnya, lihat issue tracker pglogical di GitHub.

Hal-hal yang sebaiknya dicoba

Melakukan tugas migrasi lagi dengan instance tujuan baru

Coba hapus database tujuan tempat Anda mengalami masalah dan buat ulang tugas migrasi. Ikuti langkah-langkah berikut:

  1. Hapus instance tujuan tempat Anda mengalami masalah. Lihat Menghapus instance dalam dokumentasi Cloud SQL untuk PostgreSQL.
  2. Hapus tugas migrasi yang gagal. Lihat Meninjau tugas migrasi.
  3. Buat ulang tugas migrasi Anda. Lihat Membuat tugas migrasi.

Bermigrasi ke versi perantara

Pertimbangkan untuk bermigrasi ke versi PostgreSQL sebelumnya, seperti PostgreSQL 14. Setelah migrasi berhasil, Anda dapat mencoba mengupgrade ke instance PostgreSQL 15 yang diinginkan. Lihat Mengupgrade versi utama database dengan memigrasikan data dalam dokumentasi Cloud SQL untuk PostgreSQL.

Mengelola pengguna dan peran

Memigrasikan pengguna yang ada

Saat ini, Database Migration Service tidak mendukung migrasi pengguna yang ada dari instance sumber ke instance Cloud SQL tujuan. Anda dapat mengelola migrasi ini dengan membuat pengguna di Cloud SQL secara manual.

Tentang pengguna cloudsqlexternalsync

Selama migrasi, semua objek di replika Cloud SQL dimiliki oleh pengguna cloudsqlexternalsync. Setelah data dimigrasikan, Anda dapat mengubah kepemilikan objek ke pengguna lain dengan menyelesaikan langkah-langkah berikut:

  • Jalankan perintah GRANT cloudsqlexternalsync to {USER}.
  • Di setiap database, jalankan perintah reassign owned by cloudsqlexternalsync to {USER};.
  • Untuk menghapus pengguna cloudsqlexternalsync, jalankan perintah drop role cloudsqlexternalsync.

Mengimpor data ke instance Cloud SQL baru

Jika Anda terlebih dahulu mengekspor data dari instance Cloud SQL yang dimigrasikan Database Migration Service ke Cloud Storage, lalu mengimpor data dari Cloud Storage ke instance Cloud SQL mandiri, impor mungkin gagal karena pengguna cloudsqlexternalsync tidak ada di instance tujuan.

Untuk mengurangi masalah ini, buat pengguna cloudsqlexternalsync di instance tujuan atau hapus pengguna dari instance yang dimigrasikan.