Wie man PostgreSQL-Module in ServBay kompiliert

Wenn Sie in der lokalen ServBay-Webentwicklungsumgebung an PostgreSQL-Projekten arbeiten, benötigen Sie möglicherweise zusätzliche PostgreSQL-Module (auch als Erweiterungen bekannt), um die Funktionalität Ihrer Datenbank zu erweitern. Solche Module bieten neue Datentypen, Funktionen, Operatoren, Indexzugriffsmethoden und mehr.

In dieser Anleitung erfahren Sie detailliert, wie Sie innerhalb der ServBay-Umgebung PostgreSQL-Module kompilieren und installieren. Dabei werden beispielsweise das häufig genutzte Modul postgis (für GIS-Unterstützung) und pg_jieba (für chinesische Textsegmentierung) exemplarisch durchlaufen.

Übersicht

ServBay bietet eine flexible und leistungsstarke Umgebung, die es Entwicklern ermöglicht, auf Basis der enthaltenen Softwarepakete eigene Erweiterungen oder zusätzliche Komponenten zu kompilieren. Das Kompilieren von PostgreSQL-Modulen beinhaltet gewöhnlich das Herunterladen des Quellcodes, die Konfiguration von Build-Optionen, die Nutzung von Build-Werkzeugen wie make oder cmake sowie die Installation und anschließende Aktivierung der Module in Ihrer PostgreSQL-Datenbank.

Der Schlüssel zum erfolgreichen Kompilieren liegt darin, das Build-Umfeld korrekt zu konfigurieren, sodass die spezifischen Header- und Bibliotheksdateien sowie alle notwendigen Abhängigkeiten für die gewünschte PostgreSQL-Version innerhalb von ServBay gefunden werden.

Voraussetzungen

Bevor Sie ein PostgreSQL-Modul kompilieren, müssen Sie das Build-Umfeld gemäß den Vorgaben von ServBay initialisieren. Dieser Schritt ist unabdingbar, da damit die erforderliche Toolchain (wie Compiler, Linker), Umgebungsvariablen (z.B. $PATH, $CFLAGS, $LDFLAGS) und die ServBay-spezifischen Build-Pfade korrekt gesetzt werden.

Detaillierte Anweisungen hierzu finden Sie im Abschnitt Paket in ServBay nachträglich kompilieren der offiziellen ServBay-Dokumentation. Folgen Sie diesen Vorbereitungen sorgfältig – typischerweise erfordern sie das Ausführen eines speziellen Initialisierungsskripts im ServBay-Terminal.

Die Bedeutung der korrekten PostgreSQL-Version

ServBay unterstützt die parallele Installation und Nutzung mehrerer PostgreSQL-Versionen. Da Kompilierung und Einsatz von Modulen eng an spezifische Versionen gekoppelt sind (bspw. wegen unterschiedlicher Header, Bibliotheken oder APIs), müssen Sie beim Kompilieren unbedingt die Zielversion und dazugehörige Konfigurationspfade genau angeben.

Nur durch die Auswahl der passenden PostgreSQL-Konfiguration finden alle Build-Tools die richtigen Abhängigkeiten und erzeugen ein zum gewünschten PostgreSQL kompatibles Modul – andernfalls drohen Kompilierfehler, Ladeprobleme oder unerwartete Laufzeitfehler.

Im folgenden Beispiel wird ServBay mit PostgreSQL 15 (z.B. Version 15.7) verwendet. Passen Sie Pfade bitte entsprechend Ihrer installierten Version an.

ServBay unterstützt Sie durch passende Umgebungsvariablen und das Tool pg_config dabei, die korrekten Pfade zu ermitteln. ${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/pg_config ist hierbei ein Schlüsselwerkzeug – es wird mit PostgreSQL ausgeliefert und zeigt Installationspfade, Build-Optionen, Bibliotheks- sowie Include-Verzeichnisse der gewählten Installation. Bei der Modul-Kompilierung ist die Angabe des passenden pg_config Pfades entscheidend.

Kompilierung des PostGIS-Moduls

Das postgis-Modul ist eine der beliebtesten und leistungsfähigsten Erweiterungen für PostgreSQL, da es GIS-Objekte und Funktionen hinzufügt und dadurch Räumliche Daten unterstützt (Speicherung, Abfrage und Analyse). So kompilieren Sie beispielhaft postgis-3.4.2:

Schritt 1: Quellcode herunterladen

Beziehen Sie das Quellpaket postgis-3.4.2 von der offiziellen PostGIS-Website. Stellen Sie sicher, dass Sie eine Quellcodedistribution (in der Regel als .tar.gz oder .zip) herunterladen.

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

wget ist ein gängiges Kommandozeilenwerkzeug, um Dateien direkt von einer URL herunterzuladen.

Schritt 2: Quellpaket entpacken

Entpacken Sie die Datei postgis-3.4.2.tar.gz und wechseln Sie in das erstellte Verzeichnis.

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

Mit tar zxvf werden .tar.gz-Archive entpackt. cd wechselt anschließend in das entpackte Quellcodeverzeichnis.

Schritt 3: Build-Optionen konfigurieren

PostGIS verwendet GNU Autotools als Build-System. Das Konfigurationsskript prüft alle Systemabhängigkeiten und generiert ein Makefile. In diesem Schritt geben Sie die zu nutzende PostgreSQL-Version in ServBay und alle nötigen Bibliothekspfade an.

./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: Startet das Konfigurationsskript.
• --prefix, --bindir, --datarootdir: Gibt die Zielinstallationspfade für PostGIS im PostgreSQL-Verzeichnis innerhalb von ServBay an. Diese Pfade stellen sicher, dass PostgreSQL die installierten Dateien innerhalb seines Suchpfades findet. ${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7 ist das Installationsverzeichnis von PostgreSQL 15.7 – die Umgebungsvariable wird durch das initiale ServBay-Buildsetting gesetzt.
• --with-protobufdir: Gibt das Verzeichnis für die Protobuf-Bibliothek an, sofern PostGIS diese benötigt. ${SERVBAY_BIN_PATH} verweist auf den Binärpfad der ServBay-Distribution.
• --disable-nls: Deaktiviert Unterstützung für internationale Sprachpakete; in Entwicklungsumgebungen oftmals entbehrlich.
• --without-raster, --without-topology: Raster- bzw. Topology-Unterstützung von PostGIS wird deaktiviert, damit weniger Abhängigkeiten zum Bauen nötig sind. Sie können diese bei Bedarf aktivieren; dann sollten Sie zusätzliche Bibliotheken bereitstellen.
• --with-pgconfig: Wichtigster Parameter – gibt exakt den Pfad zur pg_config der Ziel-PostgreSQL-Version an. Dient dazu, alle PostgreSQL-spezifischen Build-Flags und Verzeichnisse dem Konfigurationsprozess zur Verfügung zu stellen.
• CFLAGS, CXXFLAGS, LDFLAGS: Standardumgebungsvariablen, um zusätzliche Compiler- oder Linkeroptionen zu setzen. ${CFLAGS}, ${CXXFLAGS}, ${LDFLAGS} übernehmen ServBay-Standardeinstellungen.
  • -I${SERVBAY_COMMON_INCLUDE_PATH}/libxml2 -I${SERVBAY_COMMON_INCLUDE_PATH}: Fügt die ServBay-Include-Verzeichnisse hinzu, damit Header wie die von libxml2 verfügbar sind.
  • -L${SERVBAY_COMMON_LIB_PATH} -lxml2 -lz ...: Fügt das gemeinsame ServBay-Bibliotheksverzeichnis und notwendige Linker-Flags hinzu, um Abhängigkeiten wie libxml2, zlib, pthread, iconv, ICU etc. einzubinden. Diese Pakete sind meist Bestandteil der ServBay-Buildumgebung.
  • -std=c++17: Setzt den C++-Standard auf C++17, wie bei modernen Projekten oft gefordert.

Schritt 4: Kompilieren & Installieren

Nach erfolgreicher Konfiguration kompilieren Sie das Projekt mit make und installieren die Ergebnisse durch make install ins zuvor bei --prefix angegebene ServBay-PostgreSQL-Verzeichnis.

make -j ${CPU_NUMBER}
make install

• make -j ${CPU_NUMBER}: Startet den Open-Source-Buildprozess mit paralleler Kompilierung entsprechend der Anzahl Ihrer CPU-Kerne (definiert durch ${CPU_NUMBER}).
• make install: Kopiert die kompilierte Erweiterung sowie zugehörige SQL- und Bibliotheksdateien an den vorgesehenen Zielort in der PostgreSQL-Installation (üblicherweise lib/postgresql, share/postgresql/extension).

Schritt 5: Modul aktivieren

Nach Kompilierung und Installation aktivieren Sie die PostGIS-Erweiterung in Ihrer Datenbank. Stellen Sie sicher, dass Ihre ServBay-Umgebung im Terminal geladen ist, um auf alle Umgebungsvariablen zuzugreifen.

# Führt CREATE EXTENSION aus, um PostGIS in Ihrer Datenbank zu aktivieren
${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/psql -c "CREATE EXTENSION postgis;"

Bei Erfolg ist die Erweiterung eingerichtet. Überprüfen Sie die installierte PostGIS-Version wie folgt:

# Gibt die installierte PostGIS-Version aus
${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/psql -c "SELECT PostGIS_Version();"

Ein korrekt ausgeführter Befehl gibt die PostGIS-Versionsnummer aus – damit ist bestätigt, dass alles erfolgreich kompiliert, installiert und geladen wurde.

Kompilierung des pg_jieba-Moduls

Das Modul pg_jieba ist eine Erweiterung auf Basis der C++-Bibliothek cppjieba zur chinesischen Wortsegmentierung direkt in PostgreSQL, z.B. für Volltextsuche. Der Buildprozess basiert auf CMake. So gehen Sie dabei vor:

Schritt 1: Quellcode beziehen

Klonen Sie das Repository für pg_jieba direkt von GitHub. Da pg_jieba cppjieba als Git-Submodul verwendet, initialisieren und aktualisieren Sie bitte anschließend die Submodule.

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

• git clone ...: Klont das komplette pg_jieba-Repository in Ihr Arbeitsverzeichnis.
• git submodule update --init --recursive: Initialisiert und aktualisiert eventuell verschachtelte Submodule, sodass auch die cppjieba-Quellen im richtigen Verzeichnis vorliegen.

Schritt 2: Build-Konfiguration (CMake)

pg_jieba nutzt CMake zur Build-Konfiguration – ähnlich wie Autotools ein Buildsystem. Dabei geben Sie insbesondere das ServBay-PostgreSQL-Verzeichnis und relevante Build-Parameter an.

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: Führt CMake aus, um im Unterverzeichnis builddir eine saubere Buildumgebung anzulegen.
• -DCMAKE_PREFIX_PATH: Wichtige Option – weist CMake an, PostgreSQL und Abhängigkeiten im gewählten Installationsverzeichnis zu suchen.
• -DCMAKE_OSX_DEPLOYMENT_TARGET: Gibt die minimale unterstützte macOS-Version für die erstellten Binaries an (${BUILD_OS_MIN_VERSION}).
• -DCMAKE_OSX_ARCHITECTURES: Bestimmt die Zielprozessor-Architektur wie x86_64 oder arm64 (${BUILD_CPU_ARCH_CMAKE}). So erzeugen Sie immer mit Ihrem ServBay auf kompatible Weise lauffähige Erweiterungen.

Schritt 3: Kompilieren & Installieren (CMake)

Nach der Konfiguration bauen und installieren Sie pg_jieba wie folgt:

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

• cmake --build builddir: Baut das Projekt im angegebenen Verzeichnis.
• -j ${CPU_NUMBER}: Baut wieder mit maximaler Parallelisierung.
• cmake --install builddir: Installiert alle erzeugten Module in die richtigen ServBay- und PostgreSQL-Unterverzeichnisse (lib/postgresql, share/postgresql/extension).

Schritt 4: Erweiterung aktivieren

Auch hier aktivieren Sie das neue Modul in der Datenbank via SQL:

# CREATE EXTENSION, um pg_jieba in Ihrer Datenbank bereitzustellen
${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/psql -c "CREATE EXTENSION pg_jieba;"

Bei Erfolg können Sie die Installation über die Erweiterungsübersicht prüfen:

# Gibt Installationsinformationen zu pg_jieba aus
${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/psql -c "SELECT * FROM pg_available_extensions WHERE name = 'pg_jieba';"

Erscheint das Modul dort, wurde alles erfolgreich gebaut, installiert und aktiviert.

Häufige Fragen (FAQ)

• Kompilierung schlägt fehl – Header oder Bibliotheken fehlen?
  • Prüfen Sie, ob Sie das ServBay-Buildumfeld korrekt initialisiert haben (Initialisierungsskript ausgeführt? Umgebungsvariablen wie $CFLAGS, $LDFLAGS, ${SERVBAY_COMMON_INCLUDE_PATH}, ${SERVBAY_COMMON_LIB_PATH} korrekt gesetzt?).
  • Prüfen Sie, ob in Ihren Konfigurationsbefehlen der Pfad zu pg_config (Autotools) bzw. -DCMAKE_PREFIX_PATH (CMake) exakt auf die gewünschte PostgreSQL-Version verweist – und ob die Datei pg_config dort vorhanden und ausführbar ist.
  • Einige Module benötigen zusätzliche Systembibliotheken (z.B. GEOS, GDAL bei PostGIS mit Raster- oder Topology-Unterstützung). Die wichtigsten Bibliotheken liefert ServBay meist mit. Fehlen dennoch Abhängigkeiten, installieren Sie diese zusätzlich oder deaktivieren entsprechende Features.
• CREATE EXTENSION schlägt fehl – Moduldatei nicht gefunden?
  • Prüfen Sie, ob make install (Autotools) bzw. cmake --install (CMake) erfolgreich ausgeführt wurden. Werfen Sie einen Blick ins Installationsprotokoll.
  • Prüfen Sie, ob Ihre bei --prefix (Autotools) oder -DCMAKE_PREFIX_PATH (CMake) angegebenen Pfade exakt auf das PostgreSQL-Installationsverzeichnis in ServBay zeigen.
  • Starten Sie ggf. den PostgreSQL-Dienst über das ServBay-Interface neu – manche Module werden erst dann erkannt.
  • Prüfen Sie, ob shared_preload_libraries in Ihrer PostgreSQL-Konfiguration gesetzt sein muss (normalerweise nein; einige Spezialmodule benötigen das allerdings – Details dazu finden Sie in der jeweiligen Moduldokumentation).
• Wie kann ich ein Modul für mehrere PostgreSQL-Versionen erstellen?
  • Wiederholen Sie alle oben genannten Kompilierungsschritte, achten Sie aber besonders bei der Konfiguration (./configure oder cmake), dass Sie jeweils immer auf die gewünschten Versionen und Pfade Ihrer Ziel-PostgreSQL-Installation in ServBay verweisen (z.B. ${SERVBAY_PACKAGE_FULL_PATH}/postgresql/14/14.x/bin/pg_config oder ${SERVBAY_PACKAGE_FULL_PATH}/postgresql/14/14.x für Version 14).

Zusammenfassung

Wenn Sie die oben genannten Schritte sorgfältig befolgen und das bereitgestellte ServBay-Umfeld sowie seine Build-Tools nutzen, können Sie PostgreSQL-Module lokal erfolgreich entwickeln, kompilieren und installieren – und so Ihrer Datenbank flexibel neue Funktionen hinzufügen.

Insbesondere eine korrekte Initialisierung des Buildumfelds, die Wahl der richtigen PostgreSQL-Zielversion sowie eine genaue Überprüfung aller Kompilierungs- und Installationspfade sind für den Erfolg entscheidend.

Wir hoffen, diese Anleitung hilft Ihnen dabei, Ihr PostgreSQL-Setup in ServBay gezielt zu erweitern. Für weiterführende Hilfen nutzen Sie bitte die übrigen ServBay-Dokumente oder suchen Sie Rat in der Community.