PostgreSQL major upgrade (pg_upgrade / logical replication)

Ana sürüm yükseltmesi (ör. 16 → 17): yöntem seçimi (pg_upgrade --link / --copy / --clone ya da logical replication ile neredeyse kesintisiz taşıma), pg_upgrade --check, eklenti uyumluluğu, yapılandırmanın taşınması, istatistiklerin yeniden toplanması, standby'ların rsync ya da pg_basebackup ile yeniden kurulması, eski cluster'ın silinmesi ve geri dönüş runbook'u. Tek sunucu, streaming replication (primary + standby'lar) ve Patroni cluster'ı (Patroni'nin resmi major upgrade akışı: Patroni durdurulur, leader'da pg_upgrade, DCS kaydı silinir, replica'lar Patroni ile yeniden kopyalanır). RHEL ailesi ve Debian/Ubuntu (pg_upgradecluster dahil).

Aynı ana sürüm içinde güncelleme (ör. 17.4 → 17.6) için bu rehber değil pg-minor-update kullanılır. Tablo düzeyinde sürekli replikasyon ya da kısmi taşıma için pg-logical-repl, küçük veritabanını başka sunucuya dump ile taşımak için pg-dump-restore.

Yapı: Aynı sunucuda yerinde (pg_upgrade; tek sunucu, primary + standby'lar ya da Patroni cluster'ı) veya yeni sunucuya (logical)

Senaryolar

• Major upgrade — Ana sürüm yükseltmesi (ör. 16 → 17): ön kontrol, yedek, pg_upgrade ya da logical replication, doğrulama ve temizlik.
• Geri dönüş (upgrade başarısız / vazgeçildi) — Upgrade yarıda kaldı ya da yeni sürümde sorun çıktı: eski sürüme dönüş. --link'te yeni cluster başlatıldıysa yalnız yedekten dönülür.

Başlamadan önce

• Kaynak cluster PostgreSQL … ve PGDG repo'sundan kurulu (pg-install). Hedef sürüm … kaynaktan büyük.
• Uygulama ve sürücüler PostgreSQL … ile test edildi; aynı yükseltme önceden bir test ortamında prova edildi. … sürümüne kadar her ana sürümün release notes'undaki "Migration to Version" bölümleri okundu (kaldırılan ayarlar, davranış değişiklikleri).
• Kurulu tüm eklentilerin … için sürümü mevcut (PostGIS, pg_repack, pgaudit, TimescaleDB…). Eklenti … için yoksa upgrade yapılamaz.
• …Yeni veri dizini için mevcut veri boyutu kadar boş alan var.…Eski ve yeni veri dizini aynı dosya sisteminde (hard link şartı); WAL ve yeni katalog için birkaç GB boş alan var.…Dosya sistemi reflink destekliyor (XFS reflink=1 ya da Btrfs) ve iki dizin aynı dosya sisteminde.…
• Logical replication slot / subscription varsa listelendi: …PostgreSQL 17+ kaynakta pg_upgrade logical slotları taşır; ancak tüm değişiklikler tüketilmiş olmalı…PostgreSQL … kaynakta pg_upgrade logical slotları taşımaz; upgrade sonrası yeniden oluşturulmaları gerekir….
• Primary'den her standby'a postgres kullanıcısıyla parolasız SSH var ve standby'larda rsync kurulu. Veri dizini düzeni …/<sürüm>/data biçiminde (rsync ortak üst dizini kullanır).
• Standby'lar streaming durumda; primary'nin pg_hba.conf dosyası replikasyon bağlantısına izin veriyor ve … parolası standby'larda ~postgres/.pgpass içinde.
• Patroni cluster'ı sağlıklı: … şu anki leader, tüm replica'lar streaming ve gecikme yok, Pending restart yok. Cluster adı …, yapılandırma …, REST API parolaları /etc/patroni/patroni.env içinde (pg-patroni düzeni). DCS'nin (etcd) bir snapshot yedeği alındı. Upgrade süresince cluster tamamen kapalı olacak: HAProxy/VIP üzerinden gelen bağlantılar reddedilir.
• Patroni sürümü PostgreSQL …'i destekliyor (Patroni'nin release notes'unda yeni ana sürüm desteği). Eski bir Patroni yeni sürümün parametrelerini ve kontrol dosyasını tanımayabilir; gerekiyorsa önce Patroni'yi rolling olarak güncelleyin.
• Hedef sunucuda PostgreSQL … pg-install ile kuruldu, boş ve çalışıyor; kaynaktaki eklentilerin … sürümleri kurulu. Hedef, kaynağın … portuna erişebiliyor.
• Taşınacak tablolarda primary key ya da replica identity var (yoksa UPDATE/DELETE kaynakta hata verir). Listelenen tablolara PK ekleyin ya da ALTER TABLE … REPLICA IDENTITY FULL uygulayın.
• Güncel ve geri yüklenmesi denenmiş bir yedek var… (pgBackRest)…; mümkünse sunucu/disk snapshot'ı da alınacak.… --link yönteminde yeni cluster başlatıldıktan sonra tek geri dönüş yolu budur.…

Rehberin aşamaları

• Ön kontrol — Patroni cluster'ının durumunu kontrol et · Cluster özelliklerini kaydet · Eklenti RPM/deb'lerini listele · Prepared transaction'ları ve uzun işlemleri kontrol et
• Yeni cluster'ın hazırlanması — Yeni veri dizinini oluştur · Yeni cluster'ı aynı özelliklerle oluştur (initdb) · Yapılandırmayı yeni cluster'a taşı · Yeni sürümde geçersiz ayar var mı kontrol et · Patroni parametrelerini yeni sürüme göre kontrol et
• Yedek ve geri dönüş noktası — Yedek al (pgBackRest full) · Yedek al (pg_dumpall + snapshot)
• Uyumluluk kontrolü (pg_upgrade --check) — pg_upgrade --check
• Kesinti: eski cluster'ı durdur — Uygulamaları durdur · Kesinti anında son yedek (pgBackRest incr) · Kesinti anında son mantıksal yedek · Eski primary'yi durdur · Replica'larda Patroni'yi durdur · Leader'da Patroni'yi durdur …
• Upgrade — pg_upgrade'i çalıştır · pg_upgradecluster ile yükselt · conf.d dosyalarını yeni cluster'a taşı · pgBackRest yapılandırmasını yeni cluster'a çevir · patroni.yml'de bin_dir ve data_dir'i yeni sürüme çevir · pgBackRest stanza'sını yeni sürüme yükselt …
• Yeni cluster'ı başlatma — Yeni cluster'ı başlat · Leader'da Patroni'yi başlat · Standby'ları hemen başlat
• Upgrade sonrası işlemler — Eklentileri güncelle · İstatistikleri topla · pgBackRest kontrolü ve yeni full yedek
• Doğrulama — Sürüm, ayarlar ve veritabanları · Patroni cluster'ını doğrula · Logları kontrol et · Uygulama testleri
• Eski cluster'ı kaldırma — Eski veri dizinini sil · …Replica'lardaki…Standby'lardaki… eski veri dizinini sil · Eski sürümün yazılımını kaldır
• Kaynak sunucunun hazırlanması — wal_level = logical · Kaynağı yeniden başlat · Replikasyon kullanıcısını oluştur · pg_hba.conf'a hedefi ekle · pg_hba'yı yeniden yükle · Publication oluştur
• Hedefte şema ve abonelik — Kaynak parolalarını .pgpass'a yaz · Rolleri (globals) kopyala · Şemayı kopyala · Subscription oluştur · İlk kopyanın bitmesini bekle · Gecikmeyi kontrol et
• Son geçiş (cutover) — Kaynakta yazmayı durdur · Son değişikliklerin aktarıldığını doğrula · Sequence değerlerini aktar · Subscription'ı kaldır · İstatistikleri topla · Uygulamaları hedefe yönlendir …
• Geri dönüş — Yeni cluster'ı durdur · Replica'larda Patroni'yi durdur · Leader'da Patroni'yi durdur · pg_control'ü geri al (--link, yeni cluster başlatılmadı) · …Yedekten geri dön (--link, yeni cluster başlatıldı)…Mantıksal yedekten geri dön (--link, yeni cluster başlatıldı)… · Recovery'yi Patroni'siz tamamla …