ERROR: could not load library - jak zainstalować rozszerzenie

PostgreSQL

ERROR: could not load library - jak zainstalować rozszerzenie

W skrócie

Rozszerzenia to jedna z najmocniejszych stron PostgreSQL, ale ich instalacja bywa źródłem mylących błędów, zwłaszcza po zmianie wersji klastra. Komunikat o niemożności załadowania biblioteki brzmi groźnie, choć przyczyna prawie zawsze jest prosta. Wyjaśnimy, skąd bierze się ten błąd i jak poprawnie doprowadzić rozszerzenie do działania.

Jak to wygląda w praktyce

Próbujesz wykonać CREATE EXTENSION nazwa; albo zapytanie korzystające z rozszerzenia i dostajesz ERROR: could not load library "/usr/lib/.../nazwa.so": No such file or directory. Wariant tego problemu pojawia się szczególnie po aktualizacji klastra: baza wstaje, ale funkcje z rozszerzenia przestają działać, bo serwer nowej wersji szuka biblioteki w swoim katalogu, a znajduje tam pustkę albo plik ze starej wersji. Widziałeś, że rozszerzenie działało wcześniej, więc tym bardziej nie rozumiesz komunikatu.

Dlaczego tak się dzieje

Rozszerzenie w PostgreSQL składa się z dwóch warstw. Pierwsza to obiekty w bazie: funkcje, typy, operatory tworzone przez CREATE EXTENSION i widoczne w katalogu bazy. Druga to skompilowany kod maszynowy w pliku biblioteki współdzielonej (z rozszerzeniem .so na Linuksie albo .dll na Windows) oraz pliki sterujące, które leżą w katalogach instalacji PostgreSQL, poza samą bazą. Aby rozszerzenie działało, obie warstwy muszą być na miejscu i pochodzić z tej samej wersji serwera.

Błąd could not load library oznacza, że baza ma zapisane, iż korzysta z rozszerzenia, ale plik biblioteki nie istnieje w miejscu, w którym serwer go szuka, albo nie pasuje do wersji. Najczęstszy scenariusz to instalacja pakietu głównego PostgreSQL bez pakietu z rozszerzeniami (contrib) albo upgrade klastra, po którym doinstalowano nowy serwer, lecz nie doinstalowano dla niego pakietów rozszerzeń. Nowa wersja szuka biblioteki w swoim katalogu, a tam jej nie ma - stąd komunikat.

Jak to rozwiązać krok po kroku

1. Ustal dokładną wersję działającego serwera zapytaniem SHOW server_version;. To wersja, dla której musisz mieć pakiet rozszerzenia - nie mieszaj pakietów z różnych wersji.
2. Doinstaluj właściwy pakiet z repozytoriów systemu. Wiele popularnych rozszerzeń, w tym pg_stat_statements, jest w pakiecie contrib nazwanym pod wersję, na przykład postgresql-contrib albo postgresql-16-contrib zależnie od dystrybucji. Rozszerzenia zewnętrzne mają własne pakiety, na przykład postgresql-16-postgis.
3. Jeśli rozszerzenie wymaga wczytania przy starcie, dodaj je do shared_preload_libraries w postgresql.conf i zrestartuj serwer. Dotyczy to między innymi pg_stat_statements - bez tego wpisu jego biblioteka nie zostanie załadowana.
4. Sprawdź, czy pliki sterujące są na miejscu, zaglądając do widoku dostępnych rozszerzeń: SELECT * FROM pg_available_extensions WHERE name = 'nazwa';. Jeśli rozszerzenie się tu pojawia, znaczy że system je widzi i pakiet jest poprawny.
5. Utwórz rozszerzenie w bazie poleceniem CREATE EXTENSION nazwa;. Jeśli po awaryjnym stanie rozszerzenie już figuruje jako utworzone, ale z niedziałającą biblioteką, użyj ALTER EXTENSION nazwa UPDATE; po doinstalowaniu właściwej wersji plików.
6. Przy problemie po upgradzie klastra zadbaj, żeby na serwerze były pakiety rozszerzeń dla NOWEJ wersji, zanim uruchomisz odtworzoną bazę. Brakujące biblioteki są najczęstszą przyczyną błędów po migracji między wersjami głównymi.

Jak sprawdzić, że zadziałało

Po instalacji sprawdź, że rozszerzenie jest utworzone i aktywne w bazie zapytaniem SELECT * FROM pg_extension WHERE extname = 'nazwa'; - obecność wiersza potwierdza poprawny CREATE EXTENSION. Dla rozszerzeń ładowanych przy starcie upewnij się, że biblioteka faktycznie się wczytała: SHOW shared_preload_libraries; powinno wymieniać jej nazwę, a odpytanie jej funkcji lub widoku (na przykład SELECT * FROM pg_stat_statements LIMIT 1;) zwrócić wynik zamiast błędu. Ostatecznym dowodem jest ponowne wykonanie tej operacji, która wcześniej rzucała could not load library - brak błędu i poprawny wynik oznaczają, że biblioteka jest na miejscu i pasuje do wersji serwera.

Wróć do listy: 100 najczęstszych pytań i problemów z PostgreSQL

Sprawdź szkolenie: Administracja, replikacja i tuning baz danych PostgreSQL

To szkolenie może być dofinansowane z KFS lub BUR.

★★★★★Średnia ocena naszych szkoleń w Google: 5/5

Sprawdź szkolenie: Zaawansowana administracja PostgreSQL (HA, DR, monitoring, skalowanie)

To szkolenie może być dofinansowane z KFS lub BUR.

★★★★★Średnia ocena naszych szkoleń w Google: 5/5