Jak kompilować moduły PostgreSQL w ServBay

Podczas pracy z lokalnym środowiskiem deweloperskim ServBay możesz potrzebować skompilować i zainstalować dodatkowe moduły (rozszerzenia) PostgreSQL, aby poszerzyć albo wzbogacić funkcjonalność swojej bazy danych. Moduły te mogą dostarczać nowe typy danych, funkcje, operatory, czy metody dostępu do indeksów.

W tym przewodniku szczegółowo opisano proces kompilacji i instalacji modułów PostgreSQL w środowisku ServBay na przykładzie popularnych rozszerzeń: postgis (wsparcie dla systemów informacji geograficznej) oraz pg_jieba (dzielenie tekstu na słowa w języku chińskim).

Przegląd

ServBay oferuje elastyczne i bogate środowisko umożliwiające deweloperom tworzenie własnych rozwiązań lub kompilowanie dodatkowych elementów w oparciu o zintegrowane pakiety. Kompilacja modułów PostgreSQL najczęściej polega na pobraniu kodu źródłowego modułu, skonfigurowaniu opcji kompilacji, użyciu odpowiednich narzędzi (np. make lub cmake) oraz instalacji, a na koniec – aktywacji modułu w bazie PostgreSQL.

Kluczem do sukcesu jest prawidłowe skonfigurowanie środowiska kompilacji w taki sposób, aby mogło znaleźć nagłówki, biblioteki oraz zależności odpowiadające danej wersji PostgreSQL udostępnianej przez ServBay.

Wymagania wstępne

Przed rozpoczęciem kompilacji jakiegokolwiek modułu konieczne jest zainicjowanie środowiska kompilacji według instrukcji ServBay. Jest to niezbędny krok, ponieważ ustawia on narzędzia wymagane do kompilacji (kompilator, linker itp.), zmienne środowiskowe (takie jak $PATH, $CFLAGS, $LDFLAGS itp.) oraz ścieżki do konfiguracji specyficzne dla ServBay.

Szczegółowe informacje na temat inicjalizacji środowiska kompilacji znajdziesz w oficjalnej dokumentacji ServBay, w sekcji Wykorzystywanie ServBay do ponownej kompilacji. Upewnij się, że przeszedłeś przez te kroki przygotowawcze – zwykle polegają one na uruchomieniu określonych skryptów inicjalizacyjnych w terminalu ServBay.

Znaczenie wyboru wersji PostgreSQL

ServBay umożliwia jednoczesną instalację i uruchamianie wielu wersji PostgreSQL. Ponieważ kompilacja modułów jest ściśle zależna od wersji bazy danych (np. wymagane są określone nagłówki, biblioteki, API wewnętrzne), podczas kompilacji należy jednoznacznie określić wersję PostgreSQL oraz powiązane z nią ścieżki instalacyjne.

Wybranie właściwej ścieżki konfiguracji PostgreSQL zapewnia, że podczas kompilacji zostaną odnalezione odpowiednie zależności, a wyprodukowane pliki modułu będą zgodne z docelową wersją PostgreSQL. Dzięki temu można uniknąć błędów na etapie kompilacji, problemów z ładowaniem lub nieprzewidywalnych błędów w czasie działania.

W przykładach poniżej opisano proces dla PostgreSQL 15 (np. 15.7) zainstalowanego w ServBay. W zależności od używanej przez Ciebie wersji PostgreSQL, dostosuj odpowiednie ścieżki.

ServBay pomaga odnaleźć prawidłowe ścieżki za pomocą zmiennych środowiskowych oraz narzędzia pg_config. ${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/pg_config to narzędzie udostępniane wraz z PostgreSQL, które zwraca ścieżki instalacji, konfiguracji kompilacji, bibliotek i nagłówków danej wersji. Przy kompilacji zewnętrznych modułów pg_config jest kluczowe do prawidłowego wskazania zależności.

Kompilacja modułu postgis

Moduł postgis należy do najpopularniejszych i najpotężniejszych rozszerzeń PostgreSQL. Dodaje do bazy wsparcie dla obiektów i funkcji GIS, pozwalając przechowywać, wyszukiwać i analizować dane przestrzenne. Oto szczegółowy przewodnik, jak skompilować moduł postgis-3.4.2:

Krok 1: Pobierz kod źródłowy

Najpierw pobierz z oficjalnej strony PostGIS pakiet źródłowy postgis-3.4.2. Upewnij się, że pobrałeś wersję z kodem źródłowym (najczęściej w formacie .tar.gz lub .zip).

wget https://download.osgeo.org/postgis/source/postgis-3.4.2.tar.gz

wget to popularne narzędzie linii poleceń do pobierania plików z określonego adresu URL.

Krok 2: Rozpakowanie archiwum

Rozpakuj pobrany plik postgis-3.4.2.tar.gz oraz przejdź do rozpakowanego katalogu źródłowego.

tar zxvf postgis-3.4.2.tar.gz
cd postgis-3.4.2

tar zxvf służy do rozpakowania plików .tar.gz. Komenda cd przenosi do głównego katalogu źródeł postgis-3.4.2.

Krok 3: Konfiguracja kompilacji

PostGIS używa narzędzi GNU Autotools jako systemu budowy. Etap konfiguracji sprawdza zależności, ustala opcje kompilacji i generuje plik Makefile. W tym kroku musisz wskazać, w którym katalogu znajduje się instalacja specyficznej wersji PostgreSQL w ServBay oraz, w razie konieczności, inne ścieżki do bibliotek.

./configure \
  --prefix=${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7 \
  --bindir=${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin \
  --datarootdir=${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/share \
  --with-protobufdir=${SERVBAY_BIN_PATH} \
  --disable-nls \
  --without-raster \
  --without-topology \
  --with-pgconfig=${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/pg_config \
  CFLAGS="${CFLAGS} -I${SERVBAY_COMMON_INCLUDE_PATH}/libxml2 -I${SERVBAY_COMMON_INCLUDE_PATH}" \
  CXXFLAGS="${CXXFLAGS} -std=c++17 -I${SERVBAY_COMMON_INCLUDE_PATH}/libxml2 -I${SERVBAY_COMMON_INCLUDE_PATH}" \
  LDFLAGS="${LDFLAGS} -L${SERVBAY_COMMON_LIB_PATH} -lxml2 -lz -lpthread -liconv -licui18n -licuuc -licudata -lm"

• ./configure: uruchamia skrypt konfiguracyjny.
• --prefix, --bindir, --datarootdir: określają, gdzie zainstalować PostGIS, tak by znalazł się w katalogach odpowiadających konkretnej wersji PostgreSQL w ServBay. ${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7 to domyślny katalog PostgreSQL 15.7 w ServBay, konfigurowany przez skrypt inicjalizacyjny środowiska.
• --with-protobufdir: ścieżka do biblioteki Protobuf, wymaganej przez PostGIS. ${SERVBAY_BIN_PATH} wskazuje folder binarny ServBay.
• --disable-nls: wyłącza obsługę tłumaczeń, zazwyczaj niepotrzebną w środowisku deweloperskim.
• --without-raster, --without-topology: wyłącza wsparcie raster/topologia, aby uprościć kompilację. W razie potrzeby możesz je aktywować, jeśli zainstalujesz dodatkowe zależności.
• --with-pgconfig: najważniejsza opcja – ścieżka do narzędzia pg_config właściwej wersji PostgreSQL. Umożliwia przekazanie flag kompilacji oraz ścieżek do bibliotek/nagłówków wymaganych przez PostGIS.
• CFLAGS, CXXFLAGS, LDFLAGS: standardowe zmienne środowiskowe, przekazujące dodatkowe parametry do kompilatora oraz linkera. ${CFLAGS}, ${CXXFLAGS}, ${LDFLAGS} to flagi domyślne ustawione przez środowisko ServBay.
  • -I${SERVBAY_COMMON_INCLUDE_PATH}/libxml2 -I${SERVBAY_COMMON_INCLUDE_PATH}: dołącza ścieżki do nagłówków m.in. libxml2 – wymaganych przez PostGIS.
  • -L${SERVBAY_COMMON_LIB_PATH} -lxml2 -lz ...: dodaje katalog z bibliotekami oraz wymusza linkowanie wymaganych bibliotek (libxml2, zlib, pthread, iconv, icu itp.).
  • -std=c++17: wymusza użycie standardu C++17 – wymagane przez wiele nowoczesnych projektów.

Krok 4: Kompilacja i instalacja

Po zakończonej konfiguracji użyj komendy make, a następnie make install, by zbudować i zainstalować moduł do wskazanych folderów PostgreSQL w ServBay.

make -j ${CPU_NUMBER}
make install

• make -j ${CPU_NUMBER}: uruchamia proces kompilacji. Opcja -j ${CPU_NUMBER} pozwala na równoległą kompilację z użyciem wielu rdzeni CPU, co znacznie przyspiesza kompilację.
• make install: kopiuje wygenerowane pliki (biblioteki PostGIS, skrypty SQL itp.) do odpowiednich folderów PostgreSQL 15.7 (lib/postgresql, share/postgresql/extension itd.).

Krok 5: Weryfikacja ładowania modułu

Po skompilowaniu i zainstalowaniu modułu aktywuj rozszerzenie postgis w bazie danych PostgreSQL przy pomocy klienta linii poleceń lub innego narzędzia. Upewnij się, że korzystasz ze środowiska terminalowego ServBay, by poprawnie załadować zmienne środowiskowe.

# Utwórz rozszerzenie PostGIS przy użyciu CREATE EXTENSION
${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/psql -c "CREATE EXTENSION postgis;"

Pomyślne wykonanie komendy oznacza, że rozszerzenie zostało poprawnie utworzone. Aby sprawdzić wersję PostGIS:

# Sprawdź wersję PostGIS
${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/psql -c "SELECT PostGIS_Version();"

Jeśli wszystko przebiegło prawidłowo, powinna ukazać się informacja o wersji PostGIS – to znak, że moduł został skompilowany, zainstalowany i poprawnie załadowany do bazy.

Kompilacja modułu pg_jieba

pg_jieba to rozszerzenie PostgreSQL oparte na bibliotece C++ cppjieba, przeznaczone do segmentacji słów w języku chińskim – przydatne m.in. w rozwiązaniach wyszukiwania pełnotekstowego. Do budowy używa systemu CMake. Oto kroki wymagane do kompilacji modułu:

Krok 1: Pobierz kod źródłowy

Najpierw sklonuj repozytorium GitHub z kodem pg_jieba (razem z podmodułem cppjieba).

git clone https://github.com/jaiminpan/pg_jieba.git
cd pg_jieba
git submodule update --init --recursive

• git clone ...: klonuje repozytorium pg_jieba.
• git submodule update --init --recursive: inicjalizuje oraz pobiera podmoduły, w tym bibliotekę cppjieba.

Krok 2: Konfiguracja kompilacji (CMake)

pg_jieba wykorzystuje CMake jako podstawowy system budowania. Podobnie jak w Autotools, należy najpierw przeprowadzić konfigurację, wskazując m.in. ścieżki do PostgreSQL i inne wymagania środowiska ServBay.

cmake -S . -B builddir \
  -DCMAKE_PREFIX_PATH=${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7 \
  -DCMAKE_OSX_DEPLOYMENT_TARGET=${BUILD_OS_MIN_VERSION} \
  -DCMAKE_OSX_ARCHITECTURES=${BUILD_CPU_ARCH_CMAKE}

• cmake -S . -B builddir: uruchamia konfigurację CMake; -S . wskazuje katalog źródłowy, -B builddir – katalog budowy.
• -DCMAKE_PREFIX_PATH: kluczowa opcja – określa, gdzie CMake ma szukać bibliotek, nagłówków (tu – katalog PostgreSQL 15.7 w ServBay).
• -DCMAKE_OSX_DEPLOYMENT_TARGET: ustala minimalną wersję macOS, dla której budowane są binaria (wartość pobierana ze zmiennej środowiskowej ServBay).
• -DCMAKE_OSX_ARCHITECTURES: definiuje architekturę CPU (np. x86_64 lub arm64).

Krok 3: Kompilacja i instalacja (CMake)

Kiedy konfiguracja zakończy się pomyślnie, uruchom proces budowy i instalacji:

cmake --build builddir -j ${CPU_NUMBER}
cmake --install builddir

• cmake --build builddir: buduje moduł w wybranym katalogu.
• -j ${CPU_NUMBER}: pozwala na równoległą kompilację na wielu rdzeniach.
• cmake --install builddir: instaluje pliki w katalogu PostgreSQL określonym przez -DCMAKE_PREFIX_PATH i wewnętrzną logikę CMake/pg_config.

Krok 4: Weryfikacja ładowania modułu

Po zakończeniu procesu uruchom polecenia SQL, by aktywować rozszerzenie pg_jieba w bazie.

W terminalu ServBay użyj polecenia:

# Utwórz rozszerzenie pg_jieba przy użyciu CREATE EXTENSION
${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/psql -c "CREATE EXTENSION pg_jieba;"

W razie sukcesu możesz sprawdzić dostępność modułu w bazie danych:

# Wyświetl dostępne rozszerzenia
${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/psql -c "SELECT * FROM pg_available_extensions WHERE name = 'pg_jieba';"

Jeśli rozszerzenie pojawia się na liście, oznacza to, że proces przebiegł poprawnie i moduł jest gotowy do działania.

Często zadawane pytania (FAQ)

• Kompilacja nie powiodła się z powodu braku nagłówków lub bibliotek?
  • Sprawdź, czy właściwie zainicjowałeś środowisko kompilacji ServBay. Upewnij się, że wykonałeś odpowiedni skrypt inicjalizacyjny w terminalu ServBay oraz czy zmienne środowiskowe ($CFLAGS, $LDFLAGS, ${SERVBAY_COMMON_INCLUDE_PATH}, ${SERVBAY_COMMON_LIB_PATH} itp.) są ustawione i wskazują na prawidłowe ścieżki ServBay.
  • Sprawdź, czy opcje --with-pgconfig (Autotools) lub -DCMAKE_PREFIX_PATH (CMake) mają poprawne ścieżki do docelowej wersji PostgreSQL oraz czy plik pg_config rzeczywiście istnieje i jest wykonywalny.
  • Niektóre moduły mogą wymagać innych bibliotek poza tymi dostarczanymi przez ServBay (np. PostGIS z raster/topologią wymaga GEOS, GDAL itd.). Jeśli czegoś brakuje, doinstaluj brakujące biblioteki lub wyłącz odpowiednie opcje przy konfiguracji.
• Błąd CREATE EXTENSION – brak pliku modułu?
  • Sprawdź, czy make install (Autotools) lub cmake --install (CMake) zakończyło się bez błędów. Przejrzyj logi i upewnij się, że pliki trafiły do odpowiednich katalogów.
  • Zweryfikuj, czy opcje --prefix (Autotools) lub -DCMAKE_PREFIX_PATH (CMake) faktycznie wskazują na katalog docelowej wersji PostgreSQL.
  • Spróbuj zrestartować usługę PostgreSQL. Czasami wymaga ona restartu, by wykryć nowo zainstalowany moduł. W ServBay można to zrobić za pomocą interfejsu aplikacji.
  • Sprawdź konfigurację shared_preload_libraries w PostgreSQL. Dla większości rozszerzeń nie jest to konieczne, ale niektóre moduły (wykorzystujące hooki) mogą wymagać ręcznego dodania ich nazw do tej opcji przy starcie serwera. Sprawdź dokumentację kompilowanego modułu.
• Jak skompilować moduły dla innych wersji PostgreSQL?
  • Powtórz powyższe kroki kompilacji, wskazując w konfiguracji (czy to ./configure czy cmake) odpowiednią ścieżkę do pg_config (Autotools) lub katalogu PostgreSQL (CMake) odpowiadających żądanej wersji. Przykładowo, dla PostgreSQL 14 w ServBay należy podać ${SERVBAY_PACKAGE_FULL_PATH}/postgresql/14/14.x/bin/pg_config lub ${SERVBAY_PACKAGE_FULL_PATH}/postgresql/14/14.x (gdzie 14.x to wersja PostgreSQL 14 zainstalowana w ServBay).

Podsumowanie

Stosując się do powyższych kroków i w pełni wykorzystując środowisko kompilacji oraz narzędzia ServBay, możesz z powodzeniem kompilować i instalować niezbędne moduły PostgreSQL, dostosowując bazę danych do swoich wymagań deweloperskich. Kluczem do sukcesu jest prawidłowa inicjalizacja środowiska kompilacji, poprawne wskazanie wersji docelowej PostgreSQL oraz dbałość o ścieżki konfiguracji i instalacji.

Mamy nadzieję, że ten poradnik usprawni proces dostosowywania Twojego środowiska PostgreSQL w ServBay. W razie dodatkowych problemów skorzystaj z pozostałych dokumentów lub zasobów społeczności ServBay.