Mengupgrade versi utama database yang sudah diterapkan

Halaman ini menjelaskan cara mengupgrade versi utama database dengan mengupgrade instance Cloud SQL sebagai gantinya, bukan memigrasi data.

Pengantar

Penyedia software database secara berkala merilis versi utama baru yang berisi fitur, peningkatan performa, serta peningkatan keamanan yang baru. Cloud SQL menerima versi baru setelah versi baru tersebut dirilis. Setelah Cloud SQL menawarkan dukungan untuk versi utama yang baru, Anda dapat mengupgrade instance untuk menjaga database Anda terus terupdate.

Anda dapat mengupgrade versi database dari instance secara langsung atau dengan memigrasikan data. Upgrade secara langsung adalah cara yang lebih mudah untuk mengupgrade versi utama instance Anda. Anda tidak perlu memigrasikan data atau mengubah string koneksi aplikasi. Dengan upgrade secara langsung, Anda dapat mempertahankan nama, alamat IP, dan setelan lain dari instance saat ini setelah upgrade. Upgrade secara langsung tidak mengharuskan Anda memindahkan file data dan dapat diselesaikan lebih cepat. Dalam beberapa kasus, periode nonaktif lebih singkat daripada yang diperlukan untuk memigrasikan data Anda.

Operasi upgrade secara langsung Cloud SQL untuk PostgreSQL menggunakan pg_upgrade aplikasi utilitas.

Merencanakan upgrade versi utama

  1. Pastikan Anda memiliki peran yang diperlukan untuk melakukan upgrade versi utama: Cloud SQL Owner atau Cloud SQL Admin.

  2. Pilih versi utama target.

    gcloud

    Untuk mengetahui informasi tentang menginstal dan memulai gcloud CLI, lihat Menginstal gcloud CLI. Untuk mengetahui informasi tentang cara memulai Cloud Shell, lihat Menggunakan Cloud Shell.

    Untuk memeriksa versi database yang dapat Anda targetkan untuk upgrade di tempat di instance Anda, lakukan hal berikut:

    1. Jalankan perintah berikut.
      2. gcloud sql instances describe INSTANCE_NAME

      Ganti INSTANCE_NAME dengan nama instance.

    2. Di output perintah, temukan bagian yang diberi label upgradableDatabaseVersions.
    3. Setiap subbagian menampilkan versi database yang tersedia untuk diupgrade. Di setiap subbagian, tinjau kolom berikut.
      • majorVersion: versi utama yang dapat Anda targetkan untuk upgrade di tempat.
      • name: string versi database yang mencakup versi utama.
      • displayName: nama tampilan untuk versi database.

    REST v1

    Untuk memeriksa versi database target yang tersedia untuk upgrade di tempat versi utama, gunakan metode instances.get Cloud SQL Admin API.

    Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

    • INSTANCE_NAME: Nama instance.

    Metode HTTP dan URL: 

    GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME

    Untuk mengirim permintaan, perluas salah satu opsi berikut:

    Anda akan menerima respons JSON seperti berikut:

    
upgradableDatabaseVersions:

{
  major_version: "POSTGRES_15_0"
  name: "POSTGRES_15_0"
  display_name: "PostgreSQL 15.0"
}

    REST v1beta4

    Untuk memeriksa versi database target yang tersedia untuk upgrade langsung versi utama instance, gunakan metode instances.get Cloud SQL Admin API.

    Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

    • INSTANCE_NAME: Nama instance.

    Metode HTTP dan URL: 

    GET https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME

    Untuk mengirim permintaan, perluas salah satu opsi berikut:

    Anda akan melihat respons JSON seperti berikut:

    
upgradableDatabaseVersions:

{
  major_version: "POSTGRES_15_0"
  name: "POSTGRES_15_0"
  display_name: "PostgreSQL 15.0"
}

    Untuk mengetahui daftar lengkap versi database yang didukung Cloud SQL, lihat Kebijakan versi dan versi database.

  3. Pertimbangkan fitur yang ditawarkan di setiap versi utama database dan atasi ketidaksesuaian.

    Versi utama yang baru memperkenalkan perubahan yang tidak kompatibel yang mungkin mengharuskan Anda mengubah kode aplikasi, skema, atau setelan database. Sebelum mengupgrade instance database, tinjau catatan rilis versi utama target untuk menentukan inkompatibilitas yang harus Anda atasi.

  4. Lakukan pemeriksaan awal untuk upgrade.

  5. Uji upgrade dengan uji coba.

    Jalankan uji coba proses upgrade menyeluruh di lingkungan pengujian sebelum Anda mengupgrade database produksi. Anda dapat meng-clone instance untuk membuat salinan data identik yang akan digunakan untuk menguji proses upgrade.

    Selain memvalidasi bahwa upgrade berhasil diselesaikan, jalankan pengujian untuk memastikan aplikasi berperilaku seperti yang diharapkan pada database yang telah diupgrade.

  6. Tentukan waktu untuk mengupgrade.

    Upgrade mengharuskan instance menjadi tidak tersedia selama beberapa waktu. Rencanakan untuk melakukan upgrade saat aktivitas database rendah.

Mempersiapkan untuk upgrade versi utama

Sebelum mengupgrade, selesaikan langkah-langkah berikut.

  1. Periksa nilai LC_COLLATE untuk database template dan postgres. Himpunan karakter untuk setiap database harus en_US.UTF8.

    Jika nilai LC_COLLATE untuk database template dan postgres bukan en_US.UTF8, maka upgrade versi utama gagal. Untuk memperbaiki masalah tersebut, jika salah satu database memiliki himpunan karakter selain en_US.UTF8, ubah nilai LC_COLLATE menjadi en_US.UTF8 sebelum Anda melakukan upgrade.

    Untuk mengubah encoding database:

    1. Hapus database Anda.
    2. Lepas database Anda.
    3. Buat database baru dengan encoding yang berbeda (untuk contoh ini, en_US.UTF8).
    4. Muat ulang data Anda.

    Opsi lainnya adalah mengganti nama database:

    1. Tutup semua koneksi ke database.
    2. Ganti nama database.
    3. Perbarui konfigurasi aplikasi Anda untuk menggunakan nama database baru.
    4. Buat database kosong baru dengan encoding default.

    Sebaiknya lakukan langkah-langkah ini pada instance yang di-clone sebelum menerapkannya ke instance produksi.

  2. Kelola ekstensi PostgreSQL Anda yang tersisa.

    Sebagian besar ekstensi berfungsi pada versi utama database yang telah diupgrade. Lepas semua ekstensi yang tidak lagi didukung di versi target Anda. Misalnya, lepaskan ekstensi chkpass jika Anda mengupgrade ke PostgreSQL 11 atau versi yang lebih baru.

    Anda dapat mengupgrade PostGIS dan ekstensi terkaitnya secara manual ke versi terbaru yang didukung.

    Terkadang, mengupgrade dari PostGIS versi 2.x dapat menciptakan situasi di mana ada objek database yang tersisa yang tidak terkait dengan ekstensi PostGIS. Hal ini dapat memblokir operasi upgrade. Untuk informasi tentang cara menyelesaikan masalah ini, lihat Memperbaiki penginstalan raster postgis yang rusak.

    Terkadang, upgrade ke PostGIS versi 3.1.7 atau yang lebih baru tidak dapat diselesaikan karena objek menggunakan fungsi yang tidak digunakan lagi. Hal ini dapat memblokir operasi upgrade. Untuk memeriksa status upgrade, jalankan SELECT PostGIS_full_version();. Jika ada peringatan, hapus objek menggunakan fungsi yang tidak digunakan lagi dan update ekstensi PostGIS ke versi menengah atau yang lebih tinggi. Setelah Anda menyelesaikan tindakan ini, jalankan kembali perintah SELECT PostGIS_full_version();. Pastikan tidak ada peringatan yang muncul. Kemudian, lanjutkan dengan operasi upgrade.

    Untuk mempelajari lebih lanjut tentang mengupgrade ekstensi PostGIS Anda, lihat Mengupgrade PostGIS. Untuk masalah yang terkait dengan mengupgrade PostGIS, lihat Memeriksa versi instance PostgreSQL Anda.
  3. Kelola flag database kustom Anda. Periksa nama setiap flag database kustom yang dikonfigurasi untuk instance PostgreSQL Anda. Untuk masalah terkait flag ini, lihat Memeriksa flag kustom untuk instance PostgreSQL Anda.
  4. Saat melakukan upgrade dari satu versi utama ke versi utama lainnya, cobalah terhubung ke setiap database untuk melihat apakah ada masalah kompatibilitas. Pastikan bahwa database Anda dapat terhubung satu sama lain. Periksa kolom datallowconn untuk setiap database guna memastikan bahwa koneksi diizinkan. Nilai t berarti diizinkan, dan nilai f menunjukkan bahwa koneksi tidak dapat dibuat.
  5. Jika Anda menggunakan penginstalan Datadog untuk mengupgrade instance Cloud SQL ke PostgreSQL 10 atau versi yang lebih baru, sebelum melakukan upgrade, hapus fungsi pg_stat_activity().

Batasan umum

Batasan berikut memengaruhi upgrade versi utama secara langsung untuk Cloud SQL untuk PostgreSQL:

  • Anda tidak dapat melakukan upgrade versi utama di tempat pada replika eksternal.
  • Mengupgrade instance yang memiliki lebih dari 1,000 database dari satu versi ke versi lainnya mungkin memerlukan waktu dan waktu yang lama.
  • Menggunakan pernyataan select * from pg_largeobject_metadata; untuk mengkueri jumlah objek besar di setiap database PostgreSQL dari instance Cloud SQL Anda. Jika hasil dari semua database Anda lebih dari 10 juta objek besar, upgrade dinyatakan gagal. Cloud SQL melakukan roll back ke versi database sebelumnya.
  • Sebelum melakukan upgrade versi utama secara langsung ke PostgreSQL 16 dan yang lebih baru, upgrade ekstensi PostGIS untuk semua database Anda ke versi 3.4.0. Untuk PostgreSQL 18, upgrade ke PostGIS versi 3.6.0.
  • Sebelum melakukan upgrade versi utama di tempat ke PostgreSQL 17, upgrade ekstensi rdkit untuk semua database Anda ke versi 4.6.1.
  • Sebelum melakukan upgrade versi utama di tempat ke PostgreSQL 16, 17, atau 18, upgrade ekstensi pg_squeeze untuk semua database Anda ke versi 1.6, 1.7, atau 1.8.
  • Jika Anda menggunakan PostgreSQL versi 9.6, 10, 11, atau 12, maka ekstensi PostGIS versi 3.4.0 tidak didukung. Oleh karena itu, untuk melakukan upgrade versi utama secara langsung ke PostgreSQL 16 dan yang lebih baru, Anda harus mengupgrade terlebih dahulu ke versi PostgreSQL menengah (versi 13, 14, atau 15).

  • Jika Anda menginstal ekstensi pg_ivm untuk instance, Anda tidak dapat melakukan upgrade versi utama. Untuk memperbaikinya, uninstal ekstensi ini, lalu lakukan upgrade. Untuk mengetahui informasi selengkapnya tentang ekstensi, lihat Mengonfigurasi ekstensi PostgreSQL.

  • Jika Anda mengaktifkan tanda vacuum_defer_cleanup_age dan force_parallel_mode, Anda tidak dapat melakukan upgrade versi utama. Untuk memperbaikinya, hapus tanda ini, lalu lakukan upgrade. Untuk mengetahui informasi selengkapnya tentang flag, termasuk cara menghapusnya, lihat Mengonfigurasi flag database.

Menilai kesiapan upgrade untuk instance Anda

Cloud SQL memungkinkan Anda menjalankan pemeriksaan awal pada instance sebelum upgrade versi utama. Pemeriksaan awal ini adalah operasi yang berjalan lama (LRO) yang memeriksa apakah instance Anda siap untuk diupgrade. Alat ini membantu menemukan potensi masalah seperti inkompatibilitas, masalah konfigurasi, atau masalah data sebelum operasi upgrade.

Pemeriksaan awal akan mengonfirmasi apakah instance Anda dapat diupgrade, atau mencantumkan masalah yang perlu Anda perbaiki terlebih dahulu dan solusinya. Masalah ini mungkin disebabkan oleh ekstensi yang tidak kompatibel, dependensi yang tidak didukung, atau masalah format data.

Pemeriksaan awal terutama membaca metadata instance Anda dan melakukan pemeriksaan. Tugas ini tidak memengaruhi performa instance Anda atau menyebabkan waktu non-operasional. Sebaiknya jalankan pemeriksaan awal karena akan membantu mencegah kegagalan upgrade dan periode nonaktif yang tidak terduga.

Saat Anda menjalankan pra-pemeriksaan, salah satu hal berikut akan terjadi:

  • Tidak ada masalah yang ditemukan: Pemeriksaan awal berhasil diselesaikan, dan tidak ada masalah yang ditemukan.
  • Masalah yang memblokir upgrade ditemukan: Pemeriksaan awal berhasil diselesaikan, tetapi menemukan error yang menghentikan upgrade. Masalah harus diselesaikan sebelum upgrade.
  • Peringatan non-pemblokiran ditemukan: Pra-pemeriksaan berhasil diselesaikan dan menemukan peringatan, tetapi tidak ada yang menghentikan upgrade.

Bergantung pada hasil pra-pemeriksaan, Anda dapat melanjutkan upgrade atau memperbaiki masalah yang teridentifikasi sebelum melakukan upgrade.

Batasan

Saat menggunakan pra-pemeriksaan upgrade versi utama, pertimbangkan batasan berikut:

  • Status instance harus ditetapkan ke RUNNING.
  • Instance harus berupa instance utama. Pemeriksaan awal tidak mendukung instance replika.

  • Instance tidak boleh memiliki operasi pemblokiran yang tertunda. Jika operasi pemblokiran tertunda, maka pemeriksaan awal akan menghasilkan error dengan pesan berikut:

    Operation failed because another operation was already in progress. Try
your request after the current operation is complete.

  • Pemeriksaan awal perlu terhubung ke semua database di instance. Jika database tidak dapat diakses, terkunci, atau tidak merespons, pemeriksaan awal mungkin gagal atau menampilkan error. Meskipun pemeriksaan awal tidak memengaruhi performa instance atau menyebabkan waktu non-operasional, sebaiknya jalankan pemeriksaan awal saat beban database rendah.

Sebelum memulai

  • Pastikan Cloud SQL Admin API diaktifkan untuk instance Anda.
  • Pastikan Anda memiliki cloudsql.instances.preCheckMajorVersionUpgrade izin IAM.

Lakukan pemeriksaan awal

Untuk melakukan pra-pemeriksaan upgrade versi utama, lakukan hal berikut:

gcloud

  1. Jalankan pemeriksaan awal:

    gcloud sql instances pre-check-major-version-upgrade INSTANCE_NAME \
--target-database-version=TARGET_DATABASE_VERSION \
--project=PROJECT_ID \
[--async]

    Ganti kode berikut:

    • INSTANCE_NAME: nama instance.
    • TARGET_DATABASE_VERSION: versi utama yang ingin Anda gunakan untuk mengupgrade instance. Untuk menemukan versi database, lihat Merencanakan upgrade.
    • PROJECT_ID: ID Google Cloud project Anda.

  2. Dapatkan nama operasi pra-pemeriksaan:

    Gunakan perintah gcloud sql operations list dengan flag --instance:

    gcloud sql operations list --instance=INSTANCE_NAME

    Ganti kode berikut:

    • INSTANCE_NAME: nama instance.

  3. Pantau status pra-pemeriksaan.

    Gunakan perintah gcloud sql operations describe:

    gcloud sql operations describe OPERATION_NAME

    Ganti kode berikut:

    • OPERATION_NAME: nama operasi pra-pemeriksaan yang diambil pada langkah sebelumnya.

REST v1

  1. Jalankan pemeriksaan awal.

    Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

    • PROJECT_ID: ID project
    • INSTANCE_ID: ID instance
    • TARGET_DATABASE_VERSION: Versi utama yang akan diupgrade. Untuk menemukan daftar versi database yang tersedia, lihat Merencanakan upgrade.

    Metode HTTP dan URL: 

    POST https://sqladmin.googleapis.com/sql/v1b/projects/PROJECT-ID/instances/INSTANCE_ID/preCheckMajorVersionUpgrade

    Meminta isi JSON: 

    {
  "preCheckMajorVersionUpgradeContext": {
    "targetDatabaseVersion": "TARGET_DATABASE_VERSION"
  }
}

    Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

    Anda akan melihat respons JSON seperti berikut:

    {
  "message": "Precheck description of finding",
  "message_type": "ERROR",
  "actions_required": [
    "Precheck action required to fix the finding"
  ]
}

  2. Dapatkan nama operasi pemeriksaan awal.

    Gunakan permintaan GET dengan metode operations.list setelah mengganti PROJECT_ID dengan ID project.

    GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations

    Ganti kode berikut:

    • PROJECT_ID: ID Google Cloud project Anda.

  3. Pantau status pra-pemeriksaan.

    Gunakan permintaan GET dengan metode operations.list:

    GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operation/OPERATION_NAME

    Ganti kode berikut:

    • PROJECT_ID: ID Google Cloud project Anda.
    • OPERATION_NAME: nama operasi pra-pemeriksaan yang diambil pada langkah sebelumnya.

REST v1beta4

  1. Jalankan pemeriksaan awal.

    Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

    • PROJECT_ID: ID project
    • INSTANCE_ID: ID instance
    • TARGET_DATABASE_VERSION: Versi utama yang akan diupgrade. Untuk menemukan daftar versi database yang tersedia, lihat Merencanakan upgrade.

    Metode HTTP dan URL: 

    POST https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT-ID/instances/INSTANCE_ID/preCheckMajorVersionUpgrade

    Meminta isi JSON: 

    {
  "preCheckMajorVersionUpgradeContext": {
    "targetDatabaseVersion": "TARGET_DATABASE_VERSION"
  }
}

    Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

    Anda akan melihat respons JSON seperti berikut:

    {
  "message": "Precheck description of finding",
  "message_type": "ERROR",
  "actions_required": [
    "Precheck action required to fix the finding"
  ]
}

  2. Dapatkan nama operasi pemeriksaan awal.

    Gunakan permintaan GET dengan metode operations.list setelah mengganti PROJECT_ID dengan ID project.

    GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations

    Ganti kode berikut:

    • PROJECT_ID: ID Google Cloud project Anda.

  3. Pantau status pra-pemeriksaan.

    Gunakan permintaan GET dengan metode operations.list:

    GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operation/OPERATION_NAME

    Ganti kode berikut:

    • PROJECT_ID: ID Google Cloud project Anda.
    • operation_name: nama operasi pra-pemeriksaan yang diambil pada langkah sebelumnya.

Meninjau temuan pra-pemeriksaan

Setelah pemeriksaan awal selesai, instance Anda siap diupgrade, atau memiliki masalah yang perlu Anda perhatikan.

Siap diupgrade

Jika pra-pemeriksaan selesai dengan berhasil dan array preCheckResponse kosong, berarti tidak ada masalah atau peringatan yang ditemukan. Instance Anda siap untuk upgrade versi utama. Untuk melanjutkan, lihat Melakukan upgrade versi utama.

Belum siap untuk diupgrade

Jika pra-pemeriksaan berhasil dijalankan dan array preCheckResponse berisi masalah, instance Anda belum siap untuk upgrade dan perlu diperhatikan. Masalah yang teridentifikasi dapat atau tidak dapat memblokir upgrade. Masalah ini dicatat dalam preCheckResponse dengan jenis pesan berikut:

Jenis Deskripsi Memblokir upgrade?
INFO Pesan informasi. Tidak
WARNING Masalah potensial ditemukan, tetapi tidak menghalangi upgrade. Cloud SQL merekomendasikan untuk meninjau dan mengatasi peringatan tersebut sebelum melakukan upgrade untuk memastikan kompatibilitas penuh. Tidak
ERROR Ditemukan masalah kritis yang menghalangi upgrade. Masalah ini dapat menyebabkan upgrade gagal. Anda harus menyelesaikannya sebelum mengupgrade instance Anda. Ya

Jika instance Anda hanya memiliki pesan INFO atau WARNING, Anda dapat mengupgradenya, tetapi Anda mungkin mengalami masalah setelah upgrade. Sebaiknya tinjau detail pesan dan selesaikan masalah sebelum melakukan upgrade. Jika instance Anda memiliki pesan ERROR, Anda harus menyelesaikan masalah ini sebelum melakukan upgrade.

Setiap jenis masalah mencakup kolom message dan actions_required. Tinjau setiap masalah untuk memahami jenis dan cara menyelesaikannya. Untuk mengetahui informasi selengkapnya tentang masalah umum dan solusinya, lihat Error pra-pemeriksaan upgrade versi utama umum.

Setelah Anda menyelesaikan masalah, jalankan kembali pra-pemeriksaan untuk mengonfirmasi bahwa instance Anda siap untuk diupgrade. Kemudian, lanjutkan mengupgrade instance Anda setelah pemeriksaan awal selesai.

Melakukan upgrade versi utama

Anda dapat mengupgrade versi utama satu instance Cloud SQL, atau Anda dapat mengupgrade versi utama instance utama dan menyertakan semua replikanya dalam upgrade, termasuk replika bertingkat dan replika lintas region.

Mengupgrade versi utama satu instance

Saat Anda memulai operasi upgrade untuk satu instance, Cloud SQL akan melakukan tindakan berikut:

  1. Memeriksa konfigurasi instance Anda untuk memastikan bahwa instance kompatibel untuk upgrade.
  2. Setelah Cloud SQL memverifikasi konfigurasi, Cloud SQL akan membuat instance tidak tersedia.
  3. Membuat cadangan pra-upgrade.
  4. Melakukan upgrade pada instance.
  5. Membuat instance Anda tersedia.
  6. Membuat cadangan pasca-upgrade.

Konsol

  1. Di konsol Google Cloud , buka halaman Instance Cloud SQL.

    Buka Instance Cloud SQL

  2. Untuk membuka halaman Ringkasan instance, klik nama instance.
  3. Klik Edit.
  4. Di bagian Info instance, klik tombol Upgrade dan konfirmasi bahwa Anda ingin membuka halaman upgrade.
  5. Di halaman Memilih versi database, klik daftar Versi database untuk upgrade dan pilih salah satu versi utama database yang tersedia.
  6. Klik Lanjutkan.
  7. Di kotak ID Instance, masukkan nama instance, lalu klik tombol Mulai upgrade.
Operasi ini memerlukan waktu beberapa menit hingga selesai.

Pastikan versi utama database yang telah diupgrade muncul di bawah nama instance pada halaman Ringkasan instance.

gcloud

  1. Mulai upgrade.

    Gunakan perintah gcloud sql instances patch dengan flag --database-version.

    Sebelum menjalankan perintah, ganti variabel berikut:

    • INSTANCE_NAME: nama instance
    • DATABASE_VERSION: Enum untuk versi utama database, yang harus lebih baru dari versi saat ini. Tentukan versi database untuk versi utama yang tersedia sebagai target upgrade untuk instance. Anda dapat memperoleh enum ini sebagai langkah pertama Plan for upgrade. Jika Anda memerlukan daftar lengkap enum versi database, lihat SqlDatabaseEnums.
    gcloud sql instances patch INSTANCE_NAME \
--database-version=DATABASE_VERSION

    Upgrade versi utama memerlukan waktu beberapa menit untuk diselesaikan. Anda mungkin melihat pesan yang menunjukkan bahwa operasi memerlukan waktu lebih lama dari yang diperkirakan. Anda dapat mengabaikan pesan ini atau menjalankan perintah gcloud sql operations wait untuk menutup pesan.

  2. Dapatkan nama operasi upgrade.

    Gunakan perintah gcloud sql operations list dengan flag --instance.

    Sebelum menjalankan perintah, ganti variabel INSTANCE_NAME dengan nama instance. 

    gcloud sql operations list --instance=INSTANCE_NAME

  3. Pantau status upgrade.

    Gunakan perintah gcloud sql operations describe.

    Sebelum menjalankan perintah, ganti variabel OPERATION dengan nama operasi upgrade yang diambil di langkah sebelumnya. 

    gcloud sql operations describe OPERATION

REST v1

  1. Mulai upgrade secara langsung.

    Gunakan permintaan PATCH dengan metode instances:patch.

    Sebelum menggunakan data permintaan apa pun, ganti variabel berikut:

    • PROJECT_ID: ID project.
    • INSTANCE_NAME: Nama instance.

    Metode HTTP dan URL: 

    PATCH https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME

    Meminta isi JSON: 

    {
  "databaseVersion": DATABASE_VERSION
}

    Ganti DATABASE_VERSION dengan enum untuk versi utama database, yang harus lebih baru dari versi saat ini. Tentukan versi database untuk versi utama yang tersedia sebagai target upgrade untuk instance. Anda dapat memperoleh enum ini sebagai langkah pertama Plan for upgrade. Jika Anda memerlukan daftar lengkap enum versi database, lihat SqlDatabaseVersion.

  2. Dapatkan nama operasi upgrade.

    Gunakan permintaan GET dengan metode operations.list setelah mengganti PROJECT_ID dengan ID project.

    Metode HTTP dan URL: 

    GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations

  3. Pantau status upgrade.

    Gunakan permintaan GET dengan metode operations.get setelah mengganti variabel berikut:

    • PROJECT_ID: ID project.
    • OPERATION_NAME: Nama operasi upgrade yang diambil di langkah sebelumnya.

    Metode HTTP dan URL: 

    GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operation/OPERATION_NAME

Terraform

Untuk memperbarui versi database, gunakan resource Terraform dan penyedia Terraform untuk Google Cloud, versi 4.34.0 atau yang lebih baru.

resource "google_sql_database_instance" "instance" {
  name             = "postgres-instance"
  region           = "us-central1"
  database_version = "POSTGRES_14"
  settings {
    tier = "db-custom-2-7680"
  }
  # set `deletion_protection` to true, will ensure that one cannot accidentally delete this instance by
  # use of Terraform whereas `deletion_protection_enabled` flag protects this instance at the GCP level.
  deletion_protection = false
}

Menerapkan perubahan

Untuk menerapkan konfigurasi Terraform di project Google Cloud , selesaikan langkah-langkah di bagian berikut.

Menyiapkan Cloud Shell

  1. Luncurkan Cloud Shell.

  2. Tetapkan project Google Cloud default tempat Anda ingin menerapkan konfigurasi Terraform.

    Anda hanya perlu menjalankan perintah ini sekali per project, dan dapat dijalankan di direktori mana pun.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Variabel lingkungan akan diganti jika Anda menetapkan nilai eksplisit dalam file konfigurasi Terraform.

Menyiapkan direktori

Setiap file konfigurasi Terraform harus memiliki direktorinya sendiri (juga disebut modul root).

  1. Di Cloud Shell, buat direktori dan file baru di dalam direktori tersebut. Nama file harus memiliki ekstensi .tf—misalnya main.tf. Dalam tutorial ini, file ini disebut sebagai main.tf. 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. Jika mengikuti tutorial, Anda dapat menyalin kode contoh di setiap bagian atau langkah.

    Salin kode contoh ke dalam main.tf yang baru dibuat.

    Atau, salin kode dari GitHub. Tindakan ini direkomendasikan jika cuplikan Terraform adalah bagian dari solusi menyeluruh.

  3. Tinjau dan ubah contoh parameter untuk diterapkan pada lingkungan Anda.
  4. Simpan perubahan Anda.
  5. Lakukan inisialisasi Terraform. Anda hanya perlu melakukan ini sekali per direktori. 
    terraform init

    Secara opsional, untuk menggunakan versi penyedia Google terbaru, sertakan opsi -upgrade: 

    terraform init -upgrade

Menerapkan perubahan

  1. Tinjau konfigurasi dan pastikan resource yang akan dibuat atau diupdate oleh Terraform sesuai yang Anda inginkan: 
    terraform plan

    Koreksi konfigurasi jika diperlukan.

  2. Terapkan konfigurasi Terraform dengan menjalankan perintah berikut dan memasukkan yes pada prompt: 
    terraform apply

    Tunggu hingga Terraform menampilkan pesan "Apply complete!".

  3. Buka Google Cloud project Anda untuk melihat hasilnya. Di konsol Google Cloud , buka resource Anda di UI untuk memastikan bahwa Terraform telah membuat atau mengupdatenya.

Menghapus perubahan

Untuk menghapus perubahan Anda, lakukan langkah-langkah berikut:

  1. Untuk menonaktifkan perlindungan penghapusan, di file konfigurasi Terraform Anda, tetapkan argumen deletion_protection ke false. 
    deletion_protection =  "false"
  2. Terapkan konfigurasi Terraform dengan menjalankan perintah berikut dan memasukkan yes pada prompt: 
    terraform apply

  1. Hapus resource yang sebelumnya diterapkan dengan konfigurasi Terraform Anda dengan menjalankan perintah berikut dan memasukkan yes pada prompt:

    terraform destroy

Saat Anda mengajukan permintaan upgrade secara langsung, Cloud SQL akan melakukan pemeriksaan upgrade awal terlebih dahulu. Jika Cloud SQL menentukan bahwa instance Anda belum siap untuk diupgrade, permintaan upgrade Anda akan gagal dengan pesan yang menyarankan cara mengatasi masalah tersebut. Lihat juga Memecahkan masalah upgrade versi utama.

Menyertakan replika dalam upgrade versi utama

Jika instance utama Anda memiliki replika, Anda dapat menyertakan semua replika dalam upgrade. Cloud SQL dapat mengupgrade semua replika instance utama, termasuk replika lintas region dan replika bertingkat.

Saat Anda menyertakan replika dalam upgrade versi utama, Cloud SQL akan melakukan hal berikut:

  1. Memeriksa konfigurasi instance utama dan replika Anda untuk memastikan bahwa instance dan replika kompatibel untuk upgrade.
  2. Membuat instance utama Anda tidak tersedia.
  3. Membuat cadangan pra-upgrade instance utama.
  4. Menghentikan replikasi untuk semua replika.
  5. Melakukan upgrade pada instance utama.
  6. Jika upgrade pada instance utama berhasil, maka instance utama akan tersedia kembali dan memulai ulang replikasi.
  7. Cloud SQL membuat cadangan pasca-upgrade instance utama.
  8. Cloud SQL akan mengupgrade semua replika.

Meskipun upgrade versi utama replika gagal, instance utama akan tetap tersedia.

Untuk menyertakan replika dalam upgrade versi utama, Anda tidak dapat menggunakan konsolGoogle Cloud atau Terraform. Anda hanya dapat menggunakan gcloud CLI atau Cloud SQL Admin API.

gcloud

  1. Mulai upgrade.

    Gunakan perintah gcloud sql instances patch dengan flag --database-version dan --include-replicas-for-major-version-upgrade.

    Sebelum menjalankan perintah, ganti variabel berikut:

    • INSTANCE_NAME: Nama instance utama.
    • DATABASE_VERSION: Enum untuk versi utama database, yang harus lebih baru dari versi saat ini. Tentukan versi database untuk versi utama yang tersedia sebagai target upgrade untuk instance. Anda dapat memperoleh enum ini sebagai langkah pertama Plan for upgrade. Jika Anda memerlukan daftar lengkap enum versi database, lihat SqlDatabaseEnums.
    gcloud sql instances patch INSTANCE_NAME \
  --database-version=DATABASE_VERSION \
  --include-replicas-for-major-version-upgrade

    Upgrade versi utama memerlukan waktu beberapa menit untuk diselesaikan. Anda mungkin melihat pesan yang menunjukkan bahwa operasi memerlukan waktu lebih lama dari yang diperkirakan. Anda dapat mengabaikan pesan ini atau menjalankan perintah gcloud sql operations wait untuk menutup pesan. Mengupgrade replika dapat memerlukan waktu beberapa menit untuk selesai. Untuk memeriksa status upgrade, lakukan hal berikut:

  2. Dapatkan nama operasi upgrade.

    Gunakan perintah gcloud sql operations list dengan flag --instance.

    Sebelum menjalankan perintah, ganti variabel INSTANCE_NAME dengan nama instance. 

    gcloud sql operations list --instance=INSTANCE_NAME

  3. Pantau status upgrade.

    Gunakan perintah gcloud sql operations describe.

    Sebelum menjalankan perintah, ganti variabel OPERATION dengan nama operasi upgrade yang diambil di langkah sebelumnya. 

    gcloud sql operations describe OPERATION

REST

  1. Mulai upgrade secara langsung.

    Gunakan permintaan PATCH dengan metode instances:patch.

    Sebelum menggunakan data permintaan apa pun, ganti variabel berikut:

    • PROJECT_ID: ID project.
    • INSTANCE_NAME: Nama instance.

    Metode HTTP dan URL: 

    PATCH https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME

    Meminta isi JSON: 

    {
  "databaseVersion": DATABASE_VERSION
  "includeReplicasForMajorVersionUpgrade": true
}

    • Ganti DATABASE_VERSION dengan enum untuk versi utama database, yang harus lebih baru dari versi saat ini. Tentukan versi database untuk versi utama yang tersedia sebagai target upgrade untuk instance. Anda dapat memperoleh enum ini sebagai langkah pertama Plan for upgrade. Jika Anda memerlukan daftar lengkap enum versi database, lihat SqlDatabaseVersion.
    • Di kolom includeReplicasForMajorVersionUpgrade, tentukan true.

  2. Dapatkan nama operasi upgrade.

    Gunakan permintaan GET dengan metode operations.list setelah mengganti PROJECT_ID dengan ID project.

    Metode HTTP dan URL: 

    GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations

  3. Pantau status upgrade.

    Gunakan permintaan GET dengan metode operations.get setelah mengganti variabel berikut:

    • PROJECT_ID: ID project.
    • OPERATION_NAME: Nama operasi upgrade yang diambil di langkah sebelumnya.

    Metode HTTP dan URL: 

    GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operation/OPERATION_NAME

Cadangan upgrade otomatis

Saat Anda melakukan upgrade versi utama, Cloud SQL secara otomatis membuat dua pencadangan on-demand, yang disebut cadangan upgrade:

  • Cadangan upgrade pertama adalah cadangan pra-upgrade, yang segera dibuat sebelum memulai upgrade. Anda dapat menggunakan cadangan ini untuk memulihkan instance database ke statusnya pada versi sebelumnya.
  • Cadangan upgrade kedua adalah cadangan pasca-upgrade, yang segera dibuat setelah penulisan baru diizinkan ke instance database yang diupgrade.

Saat Anda melihat daftar cadangan, cadangan upgrade akan dicantumkan dengan jenis On-demand. Cadangan upgrade diberi label agar Anda dapat mengidentifikasinya dengan cepat. Misalnya, jika Anda mengupgrade dari PostgreSQL 14 ke PostgreSQL 15, cadangan pra-upgrade Anda akan diberi label Pre-upgrade backup, POSTGRES_14 to POSTGRES_15. dan cadangan pasca-upgrade Anda diberi label Post-upgrade backup, POSTGRES_14 to POSTGRES_15.

Seperti pencadangan on demand lainnya, cadangan upgrade akan tetap ada hingga Anda menghapusnya atau menghapus instance. Jika PITR diaktifkan, Anda tidak dapat menghapus cadangan upgrade saat cadangan upgrade berada di periode retensi. Jika perlu menghapus cadangan upgrade, Anda harus menonaktifkan PITR atau menunggu hingga cadangan upgrade tidak lagi berada dalam periode retensi.

Menyelesaikan upgrade versi utama

Setelah selesai mengupgrade instance utama, lakukan langkah-langkah berikut untuk menyelesaikan upgrade:

  1. Muat ulang statistik database.

    Jalankan ANALYZE pada instance utama untuk memperbarui statistik sistem setelah proses upgrade. Statistik yang akurat memastikan bahwa perencana kueri PostgreSQL memproses kueri secara optimal. Tidak adanya statistik dapat menyebabkan rencana kueri yang buruk, yang pada akhirnya dapat menurunkan performa dan menggunakan memori terlalu banyak.

  2. Lakukan pengujian penerimaan.

    Jalankan pengujian untuk memastikan sistem yang diupgrade berjalan seperti yang diharapkan.

Memecahkan masalah upgrade versi utama

Cloud SQL menampilkan pesan error jika Anda mencoba perintah upgrade yang tidak valid, misalnya, jika instance Anda berisi flag database tidak valid untuk versi baru.

Jika permintaan upgrade gagal, periksa sintaksis permintaan upgrade Anda. Jika permintaan memiliki struktur yang valid, coba lihat saran berikut.

Lihat log error

Jika terjadi masalah dengan permintaan upgrade yang valid, Cloud SQL akan menayangkan log error ke projects/PROJECT_ID/logs/cloudsql.googleapis.com%2Fpostgres-upgrade.log. Setiap entri log berisi label dengan ID instance untuk membantu Anda mengidentifikasi instance dengan error upgrade. Cari error upgrade tersebut dan selesaikan error tersebut.

Untuk melihat log error, gunakan konsol Google Cloud::

  1. Di konsol Google Cloud , buka halaman Instance Cloud SQL.

    Buka Instance Cloud SQL

  2. Untuk membuka halaman Ringkasan instance, klik nama instance.

  3. Di panel Operasi dan log di halaman RIngkasan, klik link Melihat log error PostgreSQL.

    Halaman Logs Explorer akan terbuka.

  4. Lihat log sebagai berikut:

    • Untuk mencantumkan semua log in error dalam sebuah project, pilih nama log dalam filter log Nama log.

    Untuk informasi selengkapnya tentang filter kueri, lihat Kueri lanjutan

    • Guna memfilter log error upgrade untuk satu instance, masukkan kueri berikut di kotak Masukkan semua kolom, setelah mengganti DATABASE_ID

    dengan project ID yang diikuti dengan nama instance dalam format ini: project_id:instance_name.

    resource.type="cloudsql_database"
resource.labels.database_id="DATABASE_ID"
logName : "projects/PROJECT_ID/logs/cloudsql.googleapis.com%2Fpostgres-upgrade.log"

    Misalnya, untuk memfilter log error upgrade berdasarkan instance bernama shopping-db yang berjalan di project buylots, gunakan filter kueri berikut:

     resource.type="cloudsql_database"
 resource.labels.database_id="buylots:shopping-db"
 logName : "projects/buylots/logs/cloudsql.googleapis.com%2Fpostgres-upgrade.log"

    Anda dapat meninjau semua log yang dilaporkan dalam jangka waktu tertentu, atau Anda dapat memfilter log berdasarkan tingkat keparahan. Opsi umum untuk pemecahan masalah dapat mencakup pemilihan filter berikut:

    • Darurat
    • Pemberitahuan
    • Kritis
    • Error

Entri log dengan awalan pg_upgrade_dump menunjukkan bahwa telah terjadi error upgrade. Contoh:

pg_upgrade_dump: error: query failed: ERROR: out of shared memory
HINT: You might need to increase max_locks_per_transaction.

Selain itu, entri log yang diberi label dengan nama file kedua .txt mungkin mencantumkan error lain yang mungkin ingin Anda selesaikan sebelum mencoba mengupgrade lagi.

Semua nama file ditemukan dalam file postgres-upgrade.log. Untuk menemukan nama file, lihat kolom labels.FILE_NAME.

Nama file yang mungkin berisi error yang perlu diselesaikan meliputi:

  • tables_with_oids.txt: File ini berisi tabel yang dicantumkan dengan ID objek (OID). Hapus atau ubah tabel agar tidak menggunakan OID.
  • tables_using_composite.txt: File ini berisi tabel yang dicantumkan menggunakan jenis komposit yang ditentukan sistem. Hapus atau ubah tabel agar tidak menggunakan jenis komposit ini.
  • tables_using_unknown.txt: File ini berisi tabel yang dicantumkan menggunakan jenis data UNKNOWN. Hapus atau ubah tabel agar tidak menggunakan jenis data ini.
  • tables_using_sql_identifier.txt: File ini berisi tabel yang dicantumkan menggunakan jenis data SQL_IDENTIFIER. Hapus atau ubah tabel agar tidak menggunakan jenis data ini.
  • tables_using_reg.txt: File ini berisi tabel yang dicantumkan menggunakan jenis data REG* (misalnya, REGCOLLATION atau REGNAMESPACE). Hapus atau ubah tabel agar tidak menggunakan jenis data ini.
  • postfix_ops.txt: File ini berisi tabel yang dicantumkan menggunakan operator akhiran (unary yang berada di sebelah kanan). Hapus atau ubah tabel agar tidak menggunakan operator ini.

Memeriksa memori

Jika instance tidak memiliki memori bersama yang cukup, Anda mungkin akan melihat pesan error: ERROR: out of shared memory. Error ini kemungkinan besar terjadi jika Anda memiliki lebih dari 10,000 tabel.

Sebelum mencoba mengupgrade, tetapkan nilai flag max_locks_per_transaction menjadi sekitar dua kali lipat jumlah tabel dalam instance. Instance dimulai ulang saat Anda mengubah nilai flag ini.

Memeriksa kapasitas koneksi

Jika instance tidak memiliki kapasitas koneksi yang cukup, Anda mungkin akan melihat pesan error ini: ERROR: Insufficient connections.

Cloud SQL merekomendasikan agar Anda meningkatkan nilai flag max_connections dengan jumlah database dalam instance Anda. Instance dimulai ulang saat Anda mengubah nilai flag ini.

Memeriksa referensi kolom yang ambigu

Cloud SQL secara otomatis melakukan pemeriksaan pra-upgrade untuk mengidentifikasi tampilan yang ditentukan pengguna yang bergantung pada tampilan katalog sistem, seperti pg_stat_activity atau pg_stat_replication. Struktur kolom tampilan katalog sistem ini dapat berubah di antara versi utama PostgreSQL. Jika Anda memiliki tampilan yang select * atau mengandalkan urutan kolom tampilan sistem ini, tampilan tersebut mungkin menjadi tidak kompatibel setelah upgrade, sehingga menyebabkan error, seperti ERROR: column reference "column_name" is ambiguous.

Pemeriksaan pra-upgrade mendeteksi tampilan tersebut dengan memeriksa dependensi. Jika tampilan yang tidak kompatibel ditemukan, proses upgrade akan dihentikan dan pesan error akan ditampilkan. Pesan ini mencantumkan tampilan yang tidak kompatibel di setiap database yang perlu ditangani.

Contoh Pesan Error

  • Untuk masalah terkait pg_stat_activity: 

    Please remove the following usages of views that depend on functions returning
data types of pg_stat_activity before attempting an upgrade:
(database: my_db, schema name: public, view name: my_stat_activity_view)

  • Untuk masalah terkait pg_stat_replication:

    Please remove the following usages of views that depend on functions returning
data types of pg_stat_replication before attempting an upgrade:
(database: my_db, schema name: public, view name: my_replication_stats_view)

Untuk mengatasi masalah tersebut dan melanjutkan upgrade: 1. Identifikasi tampilan yang tercantum dalam pesan error pemeriksaan pra-upgrade.

  1. Lepaskan tampilan ini menggunakan DROP VIEW view_name;.

  2. Coba lagi upgrade versi utama.

  3. Setelah upgrade selesai, buat ulang tampilan. Pastikan definisi tampilan baru kompatibel dengan skema tampilan katalog sistem dalam versi PostgreSQL saat ini. Anda mungkin perlu mencantumkan kolom secara eksplisit, bukan menggunakan select * untuk menghindari masalah di masa mendatang.

Untuk contoh masalah yang lebih mendetail dan insight lebih lanjut, lihat diskusi stack overflow ini

Memeriksa SRF dalam pernyataan CASE

Jika Anda mengupgrade instance dari versi 9.6 dan menggunakan fungsi yang menampilkan set dalam pernyataan CASE, Anda mungkin melihat pesan error ERROR: set-returning functions are not allowed in CASE ini. Masalah ini terjadi karena mulai dari versi 10 dan seterusnya, penggunaan fungsi yang menampilkan set dalam pernyataan CASE tidak diizinkan.

Untuk mengatasi masalah ini dan mengupgrade instance Anda dengan berhasil, pastikan bahwa semua pernyataan CASE yang menggunakan fungsi yang menampilkan set dimodifikasi agar tidak digunakan sebelum mencoba mengupgrade lagi. Beberapa SRF yang umum digunakan mencakup:

  • unnest()
  • generate_series()
  • array_agg()
  • regexp_split_to_table()
  • jsonb_array_elements()
  • json_array_elements()
  • sonb_each()
  • json_each()

Memeriksa penayangan yang dibuat di transmisi kustom

Jika Anda memiliki tampilan yang dibuat di transmisi kustom, pesan error yang mirip dengan berikut akan muncul: ERROR: cannot cast type <type_1> to <type_2>. Masalah ini terjadi karena masalah izin pada transmisi yang dibuat khusus.

Untuk mengatasi masalah ini, update instance Anda ke [PostgreSQL version].R20240910.01_02

Untuk mengetahui informasi selengkapnya, lihat Pemeliharaan layanan mandiri.

Memeriksa kepemilikan pemicu peristiwa

Di Cloud SQL, semua pemicu peristiwa harus dimiliki oleh pengguna dengan peran cloudsqlsuperuser. Cloud SQL melakukan pemeriksaan pra-upgrade untuk memvalidasi kepemilikan semua pemicu peristiwa. Jika pemicu peristiwa dimiliki oleh pengguna yang tidak memiliki peran cloudsqlsuperuser, proses upgrade akan dihentikan dan Anda mungkin mendapatkan pesan error, seperti:

Please ensure that the owners of all event triggers have the cloudsqlsuperuser
role assigned to them before attempting an upgrade:
(database: your_db, triggerName your_trigger, owner: non_super_user)

Untuk mengatasi masalah ini, ubah pemilik pemicu peristiwa menjadi pengguna yang memiliki peran cloudsqlsuperuser, seperti postgres, atau berikan peran cloudsqlsuperuser kepada pemilik saat ini.

Untuk mengidentifikasi pemicu peristiwa dengan pemilik yang tidak memiliki peran yang diperlukan, jalankan perintah berikut:

SELECT
  t.evtname AS trigger_name,
  r.rolname AS current_owner
FROM pg_event_trigger t
JOIN pg_roles r ON t.evtowner = r.oid
WHERE NOT pg_has_role(r.rolname, 'cloudsqlsuperuser', 'member');

Hasilnya menampilkan pemicu peristiwa dengan pemilik yang tidak memiliki peran cloudsqlsuperuser.

Memeriksa kolom yang dihasilkan dari tabel yang tidak dicatat

Jika Anda memiliki tabel yang tidak di-log yang memiliki kolom turunan, Anda mungkin akan melihat pesan error ERROR: unexpected request for new relfilenumber in binary upgrade mode. Masalah ini terjadi karena perbedaan karakteristik persistensi antara tabel dan urutannya untuk kolom yang dihasilkan.

Untuk mengatasi masalah ini, lakukan hal berikut:

  1. Hapus tabel yang tidak dicatat: jika memungkinkan, hapus tabel yang tidak dicatat yang ditautkan ke kolom yang dihasilkan. Pastikan kehilangan data dapat dimitigasi dengan aman sebelum melanjutkan.
  2. Mengonversi ke tabel permanen: untuk sementara, konversi tabel yang tidak dicatat ke tabel permanen menggunakan langkah-langkah berikut:
    1. Mengonversi tabel menjadi tabel yang dicatat ALTER TABLE SET LOGGED;
    2. Melakukan upgrade versi utama
    3. Mengonversi tabel kembali menjadi tabel yang tidak dicatat ALTER TABLE SET UNLOGGED

Anda dapat mengidentifikasi semua tabel tersebut menggunakan kueri berikut :

SELECT
  relnamespace::regnamespace,
  c.relname AS table_name,
  a.attname AS column_name,
  a.attidentity AS identity_type
FROM
  pg_catalog.pg_class c
  JOIN pg_catalog.pg_attribute a ON a.attrelid = c.oid
WHERE
  a.attidentity IN ('a', 'd') AND c.relkind = 'r' AND c.relpersistence = 'u'
ORDER BY c.relname, a.attname;

Memeriksa flag kustom untuk instance PostgreSQL

Jika Anda melakukan upgrade ke instance PostgreSQL, versi 14 atau yang lebih baru, periksa nama flag database kustom yang Anda konfigurasi untuk instance tersebut. Hal ini karena PostgreSQL memberlakukan batasan tambahan pada nama yang diizinkan untuk parameter kustom.

Karakter pertama flag database kustom harus alfabetis (A-Z atau a-z). Semua karakter berikutnya dapat berupa alfanumerik, karakter khusus garis bawah (_), atau karakter khusus tanda dolar ($).

Menghapus ekstensi

Jika Anda mengupgrade instance Cloud SQL, Anda mungkin akan melihat pesan error ini: pg_restore: error: could not execute query: ERROR: role "16447" does not exist.

Untuk menyelesaikan masalah ini, ikuti langkah berikut:

  1. Hapus ekstensi pg_stat_statements dan pgstattuple.
  2. Lakukan upgrade.
  3. Instal ulang ekstensi.

Operasi MVU berjalan lebih lama

Ada dua tugas pokok yang terkait dengan upgrade versi utama:

  • Operasi pra-pemeriksaan: Menampilkan error waktu tunggu habis jika tidak selesai dalam tiga jam.
  • Operasi upgrade: Menampilkan error waktu tunggu habis jika tidak selesai dalam enam jam.

Jika instance memiliki operasi MAJOR_VERSION_UPGRADE yang sedang berlangsung selama jangka waktu yang lebih lama dari yang diperkirakan, maka selidiki log error PostgreSQL. Hal ini mungkin disebabkan oleh masalah umum seperti:

  • Sejumlah besar tabel, tampilan, atau indeks
  • Resource tidak mencukupi seperti CPU atau memori
  • Transaksi utama memblokir penonaktifan database agar proses upgrade dapat dimulai. Anda dapat menggunakan konsol Google Cloud untuk memeriksa proses saat ini.

Error umum pemeriksaan awal upgrade versi utama

Masalah yang ditemukan oleh pemeriksaan awal upgrade versi utama termasuk dalam kategori berikut:

  • Ekstensi yang tidak kompatibel: Ini adalah ekstensi Cloud SQL untuk PostgreSQL di instance Anda yang tidak berfungsi dengan versi utama baru.

  • Dependensi yang tidak didukung: Ini adalah dependensi yang tidak didukung oleh versi utama baru atau perlu diupdate agar dapat berfungsi dengannya.

  • Ketidakcocokan database: Ini adalah masalah pada database atau data Anda yang mungkin terjadi setelah upgrade versi utama. Hal ini mencakup perbedaan dalam struktur database, jenis data, encoding, kolasi, atau perubahan katalog sistem khusus untuk versi baru.

Ekstensi yang tidak kompatibel

Tabel berikut mencantumkan error umum terkait ekstensi yang tidak kompatibel yang mungkin ditemukan oleh pra-pemeriksaan upgrade versi utama:

Jenis Contoh error Resolusi
Ekstensi tidak didukung atau tidak digunakan lagi Your installation contains unsupported extensions for the new version. These extensions must be removed before attempting an upgrade: (database: %s, Extension name: %s) Menghapus ekstensi dari semua database yang menggunakannya dengan DROP EXTENSION $extension_name;.
Versi ekstensi yang tidak kompatibel Your installation contains incompatible version extensions. These extensions must be upgraded to a compatible version before attempting an upgrade: (database: %s, Extension name: %s) Perbarui ekstensi ke versi yang kompatibel dengan target versi Cloud SQL untuk PostgreSQL Anda. Untuk versi yang kompatibel, lihat Mengonfigurasi ekstensi Cloud SQL untuk PostgreSQL.
PostGIS file yang tidak dikemas PostGIS version upgrade has not been completed, unpackaged raster files present. Follow the steps at https://postgis.net/documentation/tips/tip-removing-raster-from-2-3/ to fix before major version upgrade. Bersihkan file raster yang tidak dikemas.
Fungsi yang tidak digunakan lagi PostGIS PostGIS version upgrade has not been completed, deprecated functions present. Please drop all objects using deprecated functions and upgrade to a different version of PostGIS before major version upgrade. Temukan dan hapus atau ubah objek database yang menggunakan fungsi PostGIS yang tidak digunakan lagi sebelum mengupgrade ekstensi PostGIS.
Kepemilikan ekstensi Please ensure that the owner of the postgres_fdw extension has the cloudsqlsuperuser role assigned to them before attempting an upgrade: (database: my_db, extension name: postgres_fdw, owner: some_user) Ubah pemilik ekstensi menggunakan ALTER EXTENSION postgres_fdw OWNER TO postgres;.

Dependensi yang tidak didukung

Tabel berikut mencantumkan error umum terkait dependensi yang tidak didukung yang mungkin ditemukan oleh pra-pemeriksaan upgrade versi utama:

Jenis Contoh error Resolusi
Kepemilikan pemicu peristiwa Please ensure that the owners of all event triggers have the cloudsqlsuperuser role assigned to them before attempting an upgrade: (database: your_db, triggerName your_trigger, owner: non_super_user) Hubungkan ke database yang diidentifikasi menggunakan psql atau Cloud SQL Studio dan ubah pemilik pemicu menjadi pengguna postgres.
Pernyataan siap pakai yang belum di-commit Please commit/rollback the following usages of 'Uncommitted Prepared Statements'... (database: my_db, gid: my_prepared_xact) Lakukan commit atau rollback pernyataan yang disiapkan.
Flag yang tidak digunakan lagi flag "force_parallel_mode" is deprecated in new postgres version, Please delete this flag before retrying again Hapus tanda database dari konfigurasi instance.

Ketidakcocokan database

Tabel berikut mencantumkan error umum terkait ketidakcocokan format data yang mungkin ditemukan oleh pra-pemeriksaan upgrade versi utama:

Jenis Contoh error Resolusi
Jenis data tidak diketahui Please remove the following usages of 'Unknown' data types before attempting an upgrade: (database: my_db, relation: my_table, attribute: my_column) Hapus kolom atau tabel, atau ubah jenis data tabel menggunakan ALTER TABLE my_table ALTER COLUMN my_column TYPE TEXT;.
Jenis data reg* Please remove the following usages of 'reg*' data types before attempting an upgrade: (database: my_db, relation: my_table, attribute: my_column) Hapus kolom atau ubah jenis datanya.
Jenis data yang dihapus Please remove the following usages of 'sql_identifier' data types before attempting an upgrade: ... Konversi ke TEXT, timestamptz, atau jenis data lain yang sesuai.
​​aclitem Format Internal Please remove the following usages of 'aclitem' data types before attempting an upgrade: ... Berhenti menggunakan aclitem dalam definisi tabel database Anda.
Jenis data komposit yang ditentukan sistem Please remove the following usages of 'composite' data types before attempting an upgrade: (database: my_db, relation: my_table, attribute: my_column) Ubah kolom yang diidentifikasi untuk menggunakan jenis komposit yang ditentukan pengguna atau jenis data standar. Jenis komposit sistem mungkin tidak konsisten di seluruh versi utama.
Tabel dengan OIDS Please remove the following usages of tables with OIDs before attempting an upgrade: (database: my_db, relation: my_table) Perbarui tabel menggunakan ALTER TABLE my_table SET WITHOUT OIDS;.
Operator postfix yang ditentukan pengguna Please remove the following usages of 'postfix operators' before attempting an upgrade: (database: my_db, operation id: 12345, operation namespace: public, operation name: !!, type namespace: public, type name: mytype) Hapus operator postfix kustom. Anda mungkin perlu menulis ulang kode untuk menggunakan operator awalan atau panggilan fungsi.
Fungsi polimorf yang tidak kompatibel Please remove the following usages of 'incompatible polymorphic' functions before attempting an upgrade: (database: my_db, object kind: function, object name: public.my_poly_func) Hapus atau ubah fungsi untuk menghapus fungsi polimorfik yang tidak kompatibel. Hal ini mungkin berarti menyesuaikan tanda tangan atau logika fungsi agar berfungsi dengan Cloud SQL untuk PostgreSQL 14 dan yang lebih baru.
Konversi encoding yang ditentukan pengguna Please remove the following usages of user-defined encoding conversions before attempting an upgrade: (database: my_db, namespace name: public, encoding conversions name: my_encoding_conv) Menghapus konversi encoding yang ditentukan pengguna. Anda mungkin perlu membuat ulang setelah upgrade dengan tanda tangan yang kompatibel dengan versi baru.
Memeriksa referensi kolom yang ambigu Cloud SQL secara otomatis memeriksa tampilan yang ditentukan pengguna yang mengandalkan tampilan katalog sistem. Struktur kolom tampilan katalog sistem ini dapat berubah di antara versi utama.

Please remove the following usages of views that depend on functions returning data types of pg_stat_activity before attempting an upgrade: (database: my_db, schema name: public, view name: my_stat_activity_view) 		Temukan tampilan yang tercantum dalam pesan error dan hapus menggunakan perintah DROP VIEW. Setelah upgrade, buat ulang tampilan.
Tabel yang tidak dicatat dengan kolom yang dihasilkan atau urutan yang dicatat Please drop the following usages of 'Unlogged Tables with Logged Sequence' before attempting an upgrade: (database: your_db, table name: problematic_table) Anda dapat mengonversi tabel menjadi LOGGED, atau menghapusnya menggunakan perintah DROP TABLE. Buat ulang tabel setelah upgrade.
Memperbaiki masalah jalur penelusuran kosong Please update the search path of the 'll_to_earth' function (database: your_db, search path: ) Ekstensi earthdistance menggunakan earth dan cube types tanpa menentukan jalur penelusuran fungsi. Perbarui jalur penelusuran menggunakan ALTER FUNCTION ll_to_earth SET search_path = public;.

Memulihkan instance utama ke versi utama sebelumnya

Jika sistem database yang telah diupgrade tidak berfungsi seperti yang diharapkan, Anda mungkin perlu memulihkan instance utama ke versi sebelumnya. Anda melakukannya dengan memulihkan cadangan pra-upgrade ke instance pemulihan Cloud SQL, yang merupakan instance baru yang menjalankan versi pra-upgrade.

Untuk memulihkan instance utama ke versi sebelumnya, lakukan langkah-langkah berikut:

  1. Identifikasi cadangan pra-upgrade Anda.

    Lihat Cadangan upgrade otomatis.

  2. Buat instance pemulihan.

    Buat instance Cloud SQL baru menggunakan veri utama yang dijalankan Cloud SQL saat cadangan pra-upgrade dibuat. Tetapkan flag dansetelan instance yang sama dengan yang digunakan instance asli.

  3. Pulihkan cadangan pra-upgrade Anda.

    Pulihkan cadangan pra-upgrade Anda ke instance pemulihan. Mungkin memerlukan waktu beberapa menit untuk menyelesaikan proses.

  4. Tambahkan replika baca Anda.

    Jika Anda menggunakan replika baca, tambahkan replika baca satu per satu.

  5. Hubungkan aplikasi Anda.

    Setelah memulihkan sistem database Anda, perbarui aplikasi Anda dengan detail mengenai instance pemulihan dan replika bacanya. Anda dapat melanjutkan penyaluran traffic pada versi pra-upgrade database Anda.

FAQ

Pertanyaan berikut mungkin muncul saat mengupgrade versi utama database.

Apakah instance saya tidak tersedia selama upgrade?
Tentu saja. Instance Anda tetap tidak tersedia selama beberapa waktu saat Cloud SQL melakukan upgrade.
Berapa lama waktu yang diperlukan untuk melakukan upgrade?

Proses upgrade satu instance biasanya memerlukan waktu kurang dari 10 menit. Jika konfigurasi instance Anda memiliki sejumlah kecil vCPU atau memori, upgrade mungkin memerlukan waktu lebih lama.

Jika instance Anda menghosting terlalu banyak database atau tabel, atau database Anda berukuran sangat besar, upgrade mungkin memerlukan waktu berjam-jam atau bahkan waktu habis, karena total waktu upgrade sesuai dengan jumlah objek dalam database Anda. Jika Anda memiliki beberapa instance yang perlu diupgrade, waktu upgrade Anda akan meningkat secara proporsional. Jika Anda menyertakan replika dalam upgrade, operasi upgrade dapat memerlukan waktu hingga satu jam untuk selesai, bergantung pada jumlah replika yang dimiliki instance utama Anda.

Dapatkah saya memantau setiap langkah dalam proses upgrade?
Meskipun Cloud SQL memungkinkan Anda memantau apakah operasi upgrade masih berlangsung, Anda tidak dapat melacak setiap langkah di setiap upgrade.
Dapatkah saya membatalkan upgrade setelah memulainya?
Tidak, Anda tidak dapat membatalkan upgrade setelah dimulai. Jika upgrade gagal, Cloud SQL akan otomatis memulihkan instance Anda di versi sebelumnya.
Apa yang terjadi dengan setelan saya selama upgrade?

Saat Anda melakukan upgrade versi tama secara langsung, Cloud SQL menyimpan setelan database Anda, termasuk nama instance, alamat IP, nilai flag yang dikonfigurasi secara eksplisit, dan data pengguna. Namun, nilai default variabel sistem mungkin berubah. Misalnya, nilai default flag password_encryption di PostgreSQL 13 dan sebelumnya adalah md5. Saat Anda mengupgrade ke PostgreSQL 14, nilai default flag ini berubah menjadi scram-sha-256.

Untuk mempelajari lebih lanjut, lihat Mengonfigurasi flag database. Jika flag atau nilai tertentu tidak lagi didukung dalam versi target Anda, Cloud SQL secara otomatis akan menghapus flag tersebut selama proses upgrade.

Langkah berikutnya