PostgreSQL "could not load library" — Yükseltmeden Sonra Eklenti Neden Kayboldu?
pg_upgrade sonrası eksik veya uyumsuz eklenti kütüphanesi hatasının nedeni, loadable_libraries.txt, shared_preload_libraries ve yeni major sürüm için paket kurulumu.
Operasyonel Doğrulama & Güvenilirlik Standardı
Hata mesajı semptomdur, kök neden değildir. Sunucuyu yeniden başlatmadan veya rastgele ayar değiştirmeden önce aşağıdaki "Nedeni ayırt eden tek sorgu"yu çalıştırarak gerçek senaryoyu netleştirin.
▸Belirti
ERROR: could not load library "/usr/lib/postgresql/17/lib/pg_stat_statements.so":
/usr/lib/postgresql/17/lib/pg_stat_statements.so: undefined symbol: pg_stat_statements_internal
ERROR: could not access file "$libdir/postgis-3": No such file or directory
FATAL: could not load library "/usr/lib/postgresql/17/lib/timescaledb-2.14.so"Bu hata neredeyse her zaman bir major sürüm yükseltmesinden (pg_upgrade) sonra ortaya çıkar ve üç farklı varyant halinde kendini gösterir:
- 1`could not access file "$libdir/..."` + No such file or directory: Kütüphane ikili dosyası (.so / .dll) yeni PostgreSQL sürümünün dizininde fiziksel olarak yoktur. Hedef sürüm için ilgili işletim sistemi paketi kurulmamıştır.
- 2`undefined symbol`: Kütüphane dosyası mevcuttur ancak hedef PostgreSQL sürümünün ABI/API başlıklarıyla derlenmemiştir. Genellikle resmi PGDG (apt.postgresql.org) paketleri ile Linux dağıtımının (Ubuntu/Debian ana deposu) paketleri karıştırıldığında oluşur.
- 3`FATAL: could not load library`: Eksik olan kütüphane
postgresql.confdosyasındashared_preload_librariesiçinde tanımlıdır; veritabanı kümesi ayağa dahi kalkamaz.
$libdir değişkeni dinamik olarak hedefteki yeni sürümün pkglibdir dizinine çözümlenir (örneğin /usr/lib/postgresql/17/lib/). PostgreSQL 16'dan 17'ye geçtiyseniz, 16 dizininde duran postgis-3.so dosyası 17 için hiçbir şey ifade etmez. Veritabanı tablolarınız sorunsuz taşınmıştır ancak bu tabloların C dili fonksiyonlarını çalıştıran paylaşımlı kütüphaneler yeni dizinde eksiktir.▸pg_upgrade Bunu Önceden Haber Vermişti
Çoğu veritabanı yöneticisi yükseltme gecesinde stres altındayken pg_upgrade komutunun bıraktığı uyarıyı kaçırır:
Checking for presence of required libraries fatal
Your installation references loadable libraries that are missing from the
new installation. You can add these libraries to the new installation,
or remove the functions using them from the old installation.
A list of problem libraries is in the file:
loadable_libraries.txtpg_upgrade çalıştırıldığı dizinde otomatik olarak `loadable_libraries.txt` dosyasını oluşturur. Eksik olan tüm kütüphanelerin tam listesi bu dosyanın içindedir; tahmin yürütmeye gerek yoktur.
pg_upgrade --check komutunu çalıştırın. Bu komut hiçbir veriyi kopyalamaz; yalnızca küme uyumluluğunu, sayfa boyutlarını ve eklenti kütüphanelerini denetler. Gece yarısı yaşanacak bir sürprizi bir hafta önceden tespit etmenizi sağlar.▸Nedenini Doğrulayan Teşhis Sorguları
1. Yüklü Eklentileri ve Kütüphane Yollarını Listeleyin
SELECT extname, extversion FROM pg_extension ORDER BY extname;Veritabanında hangi C kütüphane fonksiyonlarının referans verildiğini sorgulayın:
SELECT DISTINCT probin
FROM pg_proc
WHERE probin IS NOT NULL
ORDER BY probin;probin sütunu fonksiyonun hangi paylaşımlı kütüphaneden ($libdir/pg_stat_statements gibi) beslendiğini gösterir.
2. Açılışta Yüklenen Kütüphaneleri Doğrulayın
Sunucu açılamıyorsa postgresql.conf içindeki şu parametreleri kontrol edin:
SHOW shared_preload_libraries;
SHOW dynamic_library_path;3. Dosya Fiziksel Olarak Var mı?
İşletim sistemi kabuğunda hedef PostgreSQL sürümünün kütüphane dizinini listeleyin:
ls -la "$(pg_config --pkglibdir)"▸Adım Adım Kalıcı Çözüm
1. loadable_libraries.txt Dosyasını Okuyun
Eksik kütüphanelerin adlarını dosyadan tek tek belirleyin.
2. Yeni Major Sürüme Uygun Paketleri Kurun
Eski paketler yeni sürümü kurtarmaz; paket adında yeni major sürüm numarası yer almalıdır:
# Debian / Ubuntu (PostgreSQL 17 örneği)
apt-get update
apt-get install -y postgresql-17-postgis-3 postgresql-17-pg-stat-statements
# RHEL / Rocky Linux
dnf install -y postgis35_173. shared_preload_libraries Değerini Normalize Edin
Eğer timescaledb gibi sürüm spesifik bir kütüphane adı yazıldıysa (ör. timescaledb-2.11), bu sürüm numarasını kaldırarak sembolik bağını veya yeni sürüm adını kullanın:
shared_preload_libraries = 'pg_stat_statements,timescaledb'4. Eklenti Tanımlarını Güncelleyin
Paket kurulduktan sonra veritabanı içinde SQL meta tanımlarını yükseltin:
ALTER EXTENSION postgis UPDATE;ALTER EXTENSION UPDATE hata verirse eklentinin sürüm uyumluluk matrisini inceleyin.▸İlgili Hata Rehberleri & Hub Bağlantıları
- •PostgreSQL Database System is Starting Up (H-50) — Yükseltme sonrası açılış ve kurtarma modu
- •PostgreSQL Hub — Sürüm yükseltme ve eklenti yönetimi rehberleri
Diğer Veritabanı Hata Teşhisleri
Kriz anında başvurabileceğiniz diğer doğrulanmış hata rehberleri.
PostgreSQL Bağlantı Tükenmesi ve too many clients Teşhisi
FATAL: sorry, too many clients already ve remaining connection slots hatalarının üç temel kök nedeni, yetki sınırlarıyla salt okunur pg_stat_activity teşhisi ve kalıcı iki katmanlı havuzlama çözümü.
PostgreSQL password authentication failed Hatası: Neden ve Çözüm
psql password authentication failed hatasının dört nedeni: yanlış şifre, md5/SCRAM uyuşmazlığı, pg_hba.conf sırası ve yanlış cluster. Adım adım teşhis.
PostgreSQL connection refused: 8 Adımda Kesin Teşhis
Connection refused, timeout ve "no pg_hba.conf entry" arasındaki fark; listen_addresses, port, firewall ve Docker port yayınlama kontrolleri.