Mendiagnosis masalah dalam migrasi PostgreSQL ke AlloyDB 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 akan dilanjutkan secara otomatis.
  • Beberapa error tidak dapat dipulihkan, seperti kerusakan data atau ketidaksesuaian skema, yang berarti tugas migrasi harus dimulai ulang dari awal.

Jika terjadi error, status tugas migrasi akan berubah menjadi Failed, dan substatus akan 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.

Tabel berikut mencantumkan masalah umum dan solusinya:

Untuk masalah ini... Kemungkinan masalah... Coba yang ini...
Saat Anda bermigrasi ke cluster tujuan yang sudah ada, Anda akan menerima pesan error berikut: The destination cluster contains existing data or user defined entities (for example databases, tables, or functions). You can only migrate to empty clusters. Clear your destination cluster and retry the migration job. Cluster AlloyDB untuk PostgreSQL tujuan Anda berisi data pengguna tambahan. Anda hanya dapat bermigrasi ke cluster yang ada dan kosong. Lihat Batasan umum. Hapus data yang bertentangan atau data tambahan dari cluster tujuan, lalu coba lagi tugas migrasi. Lihat Menghapus data tambahan dari cluster tujuan yang ada.
Gagal terhubung ke instance database sumber. Terjadi masalah konektivitas antara instance database sumber dan cluster AlloyDB untuk PostgreSQL tujuan. Ikuti langkah-langkah di Men-debug konektivitas.
Gagal menjalankan tugas migrasi karena versi database sumber dan tujuan tidak kompatibel. Versi database sumber dan tujuan bukan kombinasi yang didukung. Secara khusus, versi database sumber yang diberikan tidak kompatibel dengan versi database tujuan. Pastikan versi database tujuan sama atau merupakan versi utama yang lebih baru dan didukung daripada versi database sumber. Kemudian, buat tugas migrasi baru.
Bahasa definisi data (DDL) atau bahasa pengolahan 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 pada 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 berjalan dan perintah DDL serta DML berikutnya akan diblokir hingga sinkronisasi awal selesai.
Pesan Error: No pglogical extension installed on databases (X) Satu atau beberapa database sumber belum menginstal pglogical. Ikuti panduan ini untuk menginstal pglogical pada database di instance sumber.
Saat bermigrasi ke PostgreSQL versi 15, setelah beberapa upaya percobaan ulang koneksi berikutnya, salah satu gejala berikut akan terjadi:
  • Anda menerima pesan error Cannot connect to invalid database.
  • Metrik tugas migrasi Total penggunaan penyimpanan tujuan tidak menunjukkan progres setelah waktu yang lama saat tugas migrasi melakukan dump database penuh.
Masalah ini sering 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 ditentukan. Ikuti panduan ini untuk memastikan bahwa pengguna ini memiliki hak istimewa yang diperlukan.
Pesan Error: Unable to connect to source database server. Database Migration Service tidak dapat membuat koneksi ke server database sumber. Pastikan instance database sumber dan tujuan dapat berkomunikasi satu sama lain, dan 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. Lihat Konfigurasi level WAL.
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 mengetahui informasi selengkapnya tentang perintah yang harus dijalankan, lihat Membersihkan 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 RDS, penggunaan root certificate mandiri, bukan paket sertifikat, dapat menyebabkan masalah ini.

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

Untuk sumber Amazon RDS, gunakan paket sertifikat yang menyertakan sertifikat perantara dan root. Untuk mengetahui informasi selengkapnya, lihat Download certificate bundles dalam dokumentasi Amazon RDS.

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 mengetahui informasi selengkapnya tentang cara menginstal paket ini dengan benar, lihat Mengonfigurasi database sumber.

Pesan Error: Cannot assign TransactionIds during recovery.

Sumber yang dikonfigurasi berada dalam mode pemulihan. Konfigurasikan sumber yang tidak dalam mode pemulihan.
Dump lengkap berjalan lambat. Instance utama cluster tujuan AlloyDB untuk PostgreSQL mungkin lambat dalam mengimpor data besar dari database sumber.
  • Pilih paket mesin yang lebih tinggi untuk instance utama AlloyDB untuk PostgreSQL tujuan guna mendapatkan bandwidth jaringan dan kapasitas CPU maksimum yang tersedia.
  • Sesuaikan flag max_wal_size tujuan. Biasanya, 32 GB atau 64 GB adalah nilai yang baik untuk ditetapkan pada flag ini. Memperbarui flag ini tidak mengharuskan Anda memulai ulang server database.
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 instance AlloyDB untuk PostgreSQL Anda. Daftar log terbaru untuk instance akan muncul.
  3. Dari nama file log, pilih postgres.log.
  4. Tetapkan tingkat keparahan log ke semua tingkat di atas Warning. Log error pertama mungkin merupakan penyebab utama 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 pengolahan data (DML) yang diperbarui secara otomatis selama migrasi berkelanjutan. Anda harus mengelola perubahan bahasa definisi data (DDL) agar database sumber dan tujuan tetap kompatibel. Anda dapat melakukannya dengan dua cara:

  • Hentikan penulisan ke database sumber dan jalankan perintah DDL di sumber dan tujuan. Sebelum menjalankan perintah DDL di tujuan, berikan peran alloydbexternalsync kepada pengguna AlloyDB untuk PostgreSQL yang menerapkan perubahan DDL.
  • Gunakan pglogical.replicate_ddl_command untuk mengizinkan perintah DDL berjalan 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 parameter wal_sender_timeout tidak memadai. Error biasanya terjadi selama fase replikasi setelah dump awal berhasil.

Pertimbangkan untuk meningkatkan 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 dalam migrasi standar, tabel tanpa kunci utama hanya mereplikasi snapshot awal dan pernyataan INSERT selama fase pengambilan data perubahan (CDC); pernyataan UPDATE dan DELETE tidak direplikasi. Untuk informasi selengkapnya, tinjau Mengonfigurasi database sumber.

Saat Anda memigrasikan database yang dipilih dan tugas migrasi tidak dapat mereplikasi data ke satu atau beberapa database, status Failed akan ditampilkan dalam daftar database. Berbagai error tugas migrasi.

Di kolom Error, klik Lihat error dan perbaiki. Anda juga dapat menghapus database yang gagal dari tugas migrasi.

Untuk mengetahui informasi selengkapnya tentang cara menghapus database yang gagal dari tugas migrasi, lihat Mengelola tugas migrasi.

Menghapus data tambahan dari cluster tujuan yang ada

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

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

Hal-hal yang sebaiknya dicoba

Hapus data yang bertentangan atau data tambahan dari cluster tujuan dan mulai tugas migrasi lagi dengan melakukan langkah-langkah berikut:

  1. Hentikan tugas migrasi.
  2. Hubungkan ke instance utama cluster AlloyDB untuk PostgreSQL tujuan Anda menggunakan psql atau AlloyDB Studio.
  3. Hapus data tambahan dari database cluster tujuan Anda. Tujuan Anda hanya dapat berisi data konfigurasi sistem. Database tujuan tidak boleh berisi data pengguna (seperti tabel atau rutinitas yang ditentukan pengguna). Ada berbagai pernyataan SQL yang dapat Anda jalankan di database untuk menemukan data non-sistem:

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

    SELECT datname FROM pg_catalog.pg_database
WHERE datname NOT IN ('alloydbadmin', '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 cluster 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 NOT IN ('plpgsql', 'alloydb_utility');
  4. Hapus semua database non-sistem, tabel pengguna, dan fungsi yang ditentukan pengguna (UDF) yang diidentifikasi pada langkah sebelumnya.
  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 cluster tujuan AlloyDB untuk PostgreSQL, jika instance sumber tidak dapat dijangkau dari cluster AlloyDB untuk PostgreSQL (misalnya, instance sumber tidak berjalan, atau Anda menghapus cluster AlloyDB untuk PostgreSQL dari daftar yang diizinkan untuk instance sumber), setelan yang diperlukan untuk replikasi tidak dapat dibersihkan 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 mengkueri slot replikasi yang ada:

    SELECT pg_drop_replication_slot(slot_name) FROM pg_replication_slots WHERE slot_name LIKE '%alloydb%' AND active = 'f';

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

    SELECT pglogical.drop_node(node_name) FROM pglogical.node WHERE node_name LIKE '%alloydb%';

  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 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 cluster tujuan baru

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

  1. Hapus tugas migrasi yang gagal. Lihat Meninjau tugas migrasi.
  2. Hapus cluster tujuan tempat Anda mengalami masalah. Lihat Pengelolaan cluster AlloyDB.
  3. Buat ulang tugas migrasi Anda. Lihat Membuat tugas migrasi.
Bermigrasi ke versi perantara

Pertimbangkan untuk bermigrasi ke versi PostgreSQL yang lebih lama, seperti PostgreSQL 14. Setelah migrasi berhasil, Anda dapat mengupgrade ke instance PostgreSQL 15 yang diinginkan. Lihat Mengupgrade versi utama database dalam dokumentasi AlloyDB untuk PostgreSQL.

Menghapus cluster AlloyDB untuk PostgreSQL tanpa induk dalam mode bootstrap

Dalam kasus ekstrem yang jarang terjadi, Anda mungkin mendapati bahwa tugas migrasi telah dihapus, sedangkan cluster AlloyDB untuk PostgreSQL terkait belum dihapus, dan masih dalam mode bootstrap. Anda dapat menghapus cluster menggunakan perintah gcloud alloydb clusters delete dengan opsi --force:

gcloud alloydb clusters delete CLUSTER_ID \
    --region=REGION_ID \
    --force

Perhatikan bahwa menghapus cluster bootstrap saat sedang digunakan oleh tugas migrasi aktif akan menghasilkan perilaku yang tidak ditentukan.

Mengelola pengguna dan peran

Memigrasikan pengguna yang ada

Saat ini, Database Migration Service tidak mendukung migrasi otomatis pengguna dan peran yang ada dari instance sumber ke cluster AlloyDB untuk PostgreSQL tujuan. Anda dapat mengelola migrasi ini dengan membuat pengguna di AlloyDB untuk PostgreSQL secara manual.

Tentang pengguna alloydbexternalsync

Selama migrasi standar, semua objek database di replika AlloyDB untuk PostgreSQL dimiliki oleh pengguna alloydbexternalsync (migrasi mulai cepat menggunakan pengguna postgres). Setelah data dimigrasikan dan tugas migrasi dipromosikan, Anda dapat mengubah kepemilikan objek ke pengguna aplikasi lain dengan menyelesaikan langkah-langkah berikut:

  • Jalankan perintah GRANT alloydbexternalsync TO USER;.
  • Di setiap database, jalankan perintah REASSIGN OWNED BY alloydbexternalsync TO USER;.
  • Untuk menghapus pengguna alloydbexternalsync, jalankan perintah DROP ROLE alloydbexternalsync;.