Hoe PostgreSQL-modules compileren in ServBay

Wanneer je PostgreSQL ontwikkelt in de lokale webontwikkelomgeving van ServBay, kan het nodig zijn om extra PostgreSQL-modules (ook bekend als extensies) te compileren en te installeren om het databasessysteem uit te breiden of te verrijken. Deze modules kunnen onder meer nieuwe datatypes, functies, operatoren, en indexmethoden toevoegen.

Dit artikel beschrijft gedetailleerd hoe je in de ServBay-omgeving PostgreSQL-modules compileert en installeert, met als voorbeelden het compileren van de veelgebruikte modules postgis (ondersteuning voor geografische informatiesystemen) en pg_jieba (Chinese tekstsegmentatie).

Overzicht

ServBay biedt een flexibele en uitgebreide omgeving waarmee ontwikkelaars extra componenten kunnen bouwen of compileren op basis van de geïntegreerde softwarepakketten. Het compileren van PostgreSQL-modules omvat meestal het downloaden van de broncode van de module, het configureren van de compileeropties, het gebruik van specifieke bouwtools (zoals make of cmake) om te compileren en te installeren, en ten slotte het activeren van de module in de PostgreSQL-database.

De sleutel tot succes ligt in het correct instellen van de compileeromgeving, zodat de juiste headerbestanden, bibliotheekbestanden en afhankelijkheden voor de gewenste PostgreSQL-versie binnen ServBay gevonden worden.

Vereisten

Voordat je begint met het compileren van PostgreSQL-modules, moet je de compileeromgeving initialiseren volgens de ServBay-specificaties. Deze stap is absoluut noodzakelijk: hiermee worden de benodigde toolchain (compiler, linker, enz.), omgevingsvariabelen (zoals $PATH, $CFLAGS, $LDFLAGS enz.) en ServBay-specifieke paden voor de bouwconfiguratie ingesteld.

Voor gedetailleerde instructies over het initialiseren van de compileeromgeving, raadpleeg je de sectie Pakket opnieuw compileren met ServBay in de officiële ServBay-documentatie. Voltooi eerst de voorbereidingsstappen zoals in dat document beschreven; meestal betreft dit het uitvoeren van een specifiek initialisatiescript via de ServBay-terminal.

Het belang van de juiste PostgreSQL-versie

ServBay ondersteunt het installeren en gebruiken van meerdere PostgreSQL-versies. Omdat het compileren en uitvoeren van modules nauw samenhangt met een specifieke databaseversie (zoals afhankelijke headerbestanden, bibliotheken en interne API's), is het essentieel om tijdens het compileren de PostgreSQL-versie (en bijbehorende configuratiepaden) waarop je de module wilt draaien, expliciet te specificeren.

Het kiezen van het juiste configuratiepad zorgt ervoor dat de benodigde afhankelijkheden correct worden gevonden en dat de module compatibel is met de beoogde PostgreSQL-versie, waardoor compileerfouten, laaddfouten of onverwachte runtimeproblemen worden voorkomen.

In deze handleiding wordt als voorbeeld PostgreSQL 15 (bijvoorbeeld versie 15.7) gebruikt die binnen ServBay is geïnstalleerd. Pas de paden aan naar jouw daadwerkelijke PostgreSQL-versie indien nodig.

ServBay biedt hulpmiddelen zoals omgevingsvariabelen en het programma pg_config om het juiste pad te vinden. ${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/pg_config is een essentieel hulpmiddel: dit programma wordt standaard meegeleverd met PostgreSQL en kan informatie geven over installatiepaden, compilatie-opties en meer. Tijdens het compileren van externe modules is pg_config essentieel voor het specificeren van afhankelijkheden.

Het compileren van de PostGIS-module

De postgis module is een van de populairste en krachtigste extensies voor PostgreSQL. Het voegt GIS-objecten en functies toe aan PostgreSQL om ruimtelijke data op te slaan, te bevragen en te analyseren. De volgende stappen begeleiden je door het compilatieproces van postgis-3.4.2:

Stap 1: Download de broncode

Download eerst het broncodepakket van postgis-3.4.2 van de officiële PostGIS-website. Zorg ervoor dat je de source-versie downloadt (meestal .tar.gz of .zip).

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

wget is een veelgebruikt commandoregelprogramma voor het downloaden van bestanden via een opgegeven URL.

Stap 2: Pak het bronpakket uit

Pak het gedownloade postgis-3.4.2.tar.gz bestand uit en ga naar de uitgepakte map.

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

Met tar zxvf pak je .tar.gz-bestanden uit. cd wisselt naar de uitgepakte broncode-directory.

Stap 3: Configureer de compileeropties

PostGIS gebruikt GNU Autotools als build-systeem. De configuratiestap controleert afhankelijkheden, stelt build-functionaliteit vast en genereert het nodige Makefile. Hier moeten we via argumenten het pad van de gewenste PostgreSQL-versie binnen ServBay en de benodigde bibliotheken specificeren.

./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: start het configuratiescript.
• --prefix, --bindir, --datarootdir: bepalen waar PostGIS binnen de PostgreSQL-directory in ServBay geïnstalleerd wordt. Zo kan PostgreSQL de module correct detecteren. ${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7 is de hoofdmap van PostgreSQL 15.7 binnen ServBay en wordt automatisch ingesteld.
• --with-protobufdir: stel het pad van de Protobuf-bibliotheek in; deze is mogelijk nodig voor PostGIS. ${SERVBAY_BIN_PATH} is het binaire pad binnen ServBay.
• --disable-nls: schakel National Language Support uit, doorgaans niet vereist voor development.
• --without-raster, --without-topology: schakel support voor Raster en Topology uit voor een eenvoudigere build. Je kan deze inschakelen als je de afhankelijkheden toevoegt.
• --with-pgconfig: belangrijkste parameter, wijst naar het pg_config-programma van de PostgreSQL-versie waarvoor je compileert.
• CFLAGS, CXXFLAGS, LDFLAGS: standaardomgevingsvariabelen voor extra compilatie- en linkerinstructies. ${CFLAGS}, ${CXXFLAGS} en ${LDFLAGS} behouden de standaardflags.
  • -I${SERVBAY_COMMON_INCLUDE_PATH}/libxml2 -I${SERVBAY_COMMON_INCLUDE_PATH}: include-paden toevoegen voor headers van o.a. libxml2.
  • -L${SERVBAY_COMMON_LIB_PATH} ...: link met benodigde libraries in het algemene bibliotheekpad van ServBay.
  • -std=c++17: stel de C++ standaard in op C++17.

Stap 4: Compileren en installeren

Nadat de configuratie geslaagd is, compileer je de broncode met make, en installeer je de binaries met make install naar het juiste ServBay PostgreSQL-pad.

make -j ${CPU_NUMBER}
make install

• make -j ${CPU_NUMBER}: compileert de broncode, waarbij ${CPU_NUMBER} het aantal cpu-cores bepaalt voor parallellisatie.
• make install: kopieert de gecompileerde bestanden naar de ServBay-installatiemap (typisch onder lib/postgresql en share/postgresql/extension).

Stap 5: Controleer of de module werkt

Na installatie kun je PostGIS activeren in de database. Gebruik de psql commandoregels van ServBay in een ServBay-terminal om te zorgen dat de juiste omgevingsvariabelen geladen zijn.

# Gebruik CREATE EXTENSION om PostGIS in te schakelen
${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/psql -c "CREATE EXTENSION postgis;"

Als het commando slaagt, is de extensie actief. Controleer desgewenst de versie:

# Haal de geïnstalleerde PostGIS-versie op
${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/psql -c "SELECT PostGIS_Version();"

Bij een succesvolle installatie zie je het versienummer van PostGIS terug, wat betekent dat de extensie correct gecompileerd, geïnstalleerd en geladen is.

Het compileren van de pg_jieba-module

pg_jieba is een PostgreSQL-extensie op basis van de C++-bibliotheek cppjieba, waarmee segmentatie van Chinese tekst (voor o.a. fulltext search) in PostgreSQL mogelijk wordt. pg_jieba gebruikt CMake als build-systeem. Hieronder vind je de te volgen stappen:

Stap 1: Haal de broncode op

Clone eerst de pg_jieba broncode van GitHub. Vergeet niet de benodigde submodule (cppjieba) te initialiseren en bij te werken.

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

• git clone ...: haalt de broncode van pg_jieba op.
• git submodule update --init --recursive: initialiseert en update de submodules, zodat ook de cppjieba broncode correct wordt opgehaald.

Stap 2: Configureer compileeropties (CMake)

pg_jieba gebruikt CMake. Net als bij Autotools leid je CMake via instellingen naar het juiste PostgreSQL-installatiepad en relevante buildtargets.

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: Initialiseer CMake vanuit de huidige map en genereer builds in builddir.
• -DCMAKE_PREFIX_PATH: essentieel; wijst CMake naar de ServBay PostgreSQL 15.7 directory voor het vinden van dependencies en headers.
• -DCMAKE_OSX_DEPLOYMENT_TARGET: bepaal het minimum ondersteunde macOS-versieniveau (via ${BUILD_OS_MIN_VERSION}).
• -DCMAKE_OSX_ARCHITECTURES: stel de gewenste cpu-architectuur in (zoals x86_64 of arm64, via ${BUILD_CPU_ARCH_CMAKE}).

Stap 3: Compileren en installeren (CMake)

Compileren en installeren doe je met onderstaande commando's:

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

• cmake --build builddir: compileer in de map builddir.
• -j ${CPU_NUMBER}: compileer parallel voor optimale snelheid.
• cmake --install builddir: installeer de extensie in de opgegeven ServBay PostgreSQL-directory.

Stap 4: Controleer of de module werkt

Activeer de pg_jieba extensie in je database en controleer of deze correct is geïnstalleerd:

# Gebruik CREATE EXTENSION om pg_jieba in te schakelen
${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/psql -c "CREATE EXTENSION pg_jieba;"

Controleer of de module zichtbaar is in de lijst met beschikbare extensies:

# Toon alle geïnstalleerde extensies
${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/psql -c "SELECT * FROM pg_available_extensions WHERE name = 'pg_jieba';"

Als de module vermeld staat, is het proces geslaagd.

Veelgestelde vragen (FAQ)

• Compileerfout: headers of bibliotheken niet gevonden?
  • Controleer of je de compileeromgeving van ServBay correct hebt geïnitialiseerd, inclusief alle relevante omgevingsvariabelen ($CFLAGS, $LDFLAGS, ${SERVBAY_COMMON_INCLUDE_PATH}, ${SERVBAY_COMMON_LIB_PATH}).
  • Controleer of je het pad naar de juiste PostgreSQL-versie correct hebt ingevuld bij respectievelijk --with-pgconfig (Autotools) of -DCMAKE_PREFIX_PATH (CMake) en of het bestand pg_config daadwerkelijk aanwezig en uitvoerbaar is.
  • Sommige modules vereisen extra systeemafhankelijkheden buiten de standaardbibliotheken van ServBay (zoals GEOS of GDAL voor PostGIS met raster/topologie-support). Installeer ontbrekende dependencies of schakel ze uit tijdens het compileren om fouten te voorkomen.
• CREATE EXTENSION lukt niet, module niet gevonden?
  • Controleer of make install (Autotools) of cmake --install (CMake) zonder fouten is voltooid en de bestand(en) op de juiste plek zijn geplaatst.
  • Controleer of --prefix (Autotools) of -DCMAKE_PREFIX_PATH (CMake) het juiste installatiepad aangeeft, namelijk het correcte ServBay PostgreSQL-directory. Gewoonlijk worden modules geïnstalleerd in de submap lib/postgresql.
  • Probeer de PostgreSQL-service opnieuw op te starten via de ServBay-app — soms is herstart vereist voordat nieuwe modules herkend worden.
  • Controleer de configuratie van shared_preload_libraries in de PostgreSQL-instellingen. Voor de meeste extensies is dit niet nodig, maar sommige speciale modules vereisen opname in dit configuratieveld. Raadpleeg de specifieke module-documentatie voor details.
• Modules compileren voor verschillende PostgreSQL-versies?
  • Doorloop dezelfde compilatiestappen, maar verwijs bij het configureren (./configure of cmake) consequent naar het pad van de gewenste PostgreSQL-versie via respectievelijk --with-pgconfig (Autotools) of -DCMAKE_PREFIX_PATH (CMake). Bijvoorbeeld, voor PostgreSQL 14 in ServBay: ${SERVBAY_PACKAGE_FULL_PATH}/postgresql/14/14.x/bin/pg_config of ${SERVBAY_PACKAGE_FULL_PATH}/postgresql/14/14.x.

Samenvatting

Door deze stappen te volgen, en optimaal gebruik te maken van de compileeromgeving en tooling van ServBay, kun je succesvol eigen PostgreSQL-modules compileren en installeren binnen je ServBay-omgeving. Hiermee breid je de functionaliteit van je database uit en voldoe je aan specifieke ontwikkelbehoeften. Het correct initialiseren van de compileeromgeving, het instellen van het beoogde PostgreSQL-versiepad, en het zorgvuldig controleren van configuraties en installatiepaden zijn essentieel voor een geslaagde build.

Hopelijk helpt deze handleiding je bij het customizen van je PostgreSQL-omgeving binnen ServBay. Heb je andere vragen of loop je tegen problemen aan, raadpleeg dan de overige ServBay-documentatie of de community.