Come compilare i moduli PostgreSQL in ServBay

Quando sviluppi con ServBay come ambiente locale per il Web e lavori con PostgreSQL, potresti aver bisogno di compilare e installare moduli aggiuntivi di PostgreSQL (noti anche come estensioni) per potenziare o estendere le funzionalità del database. Questi moduli possono aggiungere nuovi tipi di dato, funzioni, operatori, metodi di accesso agli indici e molto altro.

Questa guida spiega in dettaglio come compilare e installare moduli PostgreSQL nell’ambiente ServBay, utilizzando come esempio la compilazione dei moduli diffusi postgis (supporto GIS) e pg_jieba (segmentazione del testo cinese).

Panoramica

ServBay offre un ambiente flessibile e potente che permette agli sviluppatori di effettuare sviluppo secondario o compilare ulteriori componenti su pacchetti software integrati. La compilazione di moduli PostgreSQL di solito prevede il download del sorgente del modulo, la configurazione delle opzioni di compilazione, l’uso di specifici strumenti di build (come make o cmake) per la compilazione e l’installazione, e infine l’abilitazione del modulo all’interno di PostgreSQL.

La chiave del successo è configurare correttamente l’ambiente di compilazione affinché trovi intestazioni, file di libreria e dipendenze richieste per la versione specifica di PostgreSQL disponibile in ServBay.

Prerequisiti

Prima di compilare qualsiasi modulo PostgreSQL, è fondamentale inizializzare l’ambiente di compilazione come richiesto da ServBay. Questa operazione prepara la toolchain necessari (compilatori, linker, ecc.), le variabili d’ambiente ($PATH, $CFLAGS, $LDFLAGS ecc.) e i percorsi di configurazione specifici di ServBay.

Per le istruzioni dettagliate sull’inizializzazione dell’ambiente di compilazione, consulta la sezione Compilazione secondaria con ServBay nella documentazione ufficiale ServBay. Accertati di aver completato tutte le operazioni di preparazione dell’ambiente, generalmente eseguendo uno script di inizializzazione da terminale ServBay.

L’importanza di specificare la versione di PostgreSQL

ServBay permette di installare e utilizzare più versioni di PostgreSQL. Poiché la compilazione e l’esecuzione dei moduli sono strettamente legate alla versione del database (in particolare alle intestazioni, librerie e API interne), è fondamentale indicare chiaramente la versione e il relativo percorso di configurazione che desideri utilizzare per la compilazione del modulo.

Impostare correttamente il percorso della versione di PostgreSQL assicura che durante la compilazione vengano trovate le giuste dipendenze e che i moduli generati siano compatibili con la versione di destinazione, evitando errori di compilazione, problemi di caricamento o malfunzionamenti in fase di esecuzione.

In questo esempio useremo la versione PostgreSQL 15 installata in ServBay (ad esempio, 15.7). Adatta i percorsi in base alla versione di PostgreSQL che stai realmente utilizzando.

ServBay ti aiuta con le variabili d’ambiente e l’utilità pg_config: ${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/pg_config è uno strumento fornito da PostgreSQL che riporta informazioni sul percorso d’installazione, configurazioni di compilazione, percorsi di librerie e intestazioni relativi a una versione specifica. Usare pg_config è indispensabile durante la compilazione di moduli esterni.

Compilazione del modulo postgis

postgis è una delle estensioni più popolari e potenti per PostgreSQL, che aggiunge il supporto per oggetti e funzioni GIS (Geographic Information System), permettendo l’archiviazione, la ricerca e l’analisi di dati spaziali. Di seguito i passaggi dettagliati per compilare la versione postgis-3.4.2:

Passaggio 1: Scarica il codice sorgente

Per prima cosa, scarica il sorgente di postgis-3.4.2 dal sito ufficiale di PostGIS. Assicurati di scaricare il pacchetto in versione sorgente (tipicamente formato .tar.gz o .zip).

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

wget è uno strumento da linea di comando comunemente usato per scaricare file da URL specifici.

Passaggio 2: Estrai il pacchetto sorgente

Estrai postgis-3.4.2.tar.gz in una directory locale e accedi alla directory risultante.

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

Il comando tar zxvf estrae archivi compressi .tar.gz. cd sposta la directory di lavoro nella root del codice sorgente appena estratto.

Passaggio 3: Configura le opzioni di compilazione

PostGIS utilizza GNU Autotools come sistema di build. Il passaggio di configurazione verifica le dipendenze di sistema, determina le caratteristiche di compilazione e genera il file Makefile. Qui, tramite i parametri di configurazione, dobbiamo specificare il percorso d’installazione di PostgreSQL in ServBay e gli altri percorsi delle librerie.

./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: avvia lo script di configurazione.
• --prefix, --bindir, --datarootdir: indica dove installare PostGIS nella struttura della versione PostgreSQL specifica in ServBay. Questo assicura che PostgreSQL trovi i file dei moduli nelle sue directory standard di ricerca. ${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7 è la root di installazione di PostgreSQL 15.7 in ServBay e questo percorso viene impostato dallo script di inizializzazione dell’ambiente di compilazione.
• --with-protobufdir: specifica il percorso della libreria Protobuf, da cui PostGIS può dipendere. ${SERVBAY_BIN_PATH} è il percorso dei binari ServBay.
• --disable-nls: disabilita il supporto multilingua (utile principalmente in ambiente di sviluppo).
• --without-raster, --without-topology: esclude il supporto Raster e Topology per semplificare la compilazione. Puoi abilitarli, ma ciò potrebbe richiedere librerie aggiuntive.
• --with-pgconfig: opzione fondamentale, indica lo specifico percorso di pg_config della versione di PostgreSQL da usare per la compilazione. pg_config fornisce a PostGIS i flag di compilazione e i percorsi; è indispensabile per assicurare compatibilità con la versione target.
• CFLAGS, CXXFLAGS, LDFLAGS: variabili standard per passare argomenti ai compilatori e linker C/C++, con i settaggi predefiniti dell’ambiente ServBay:
  • -I${SERVBAY_COMMON_INCLUDE_PATH}/libxml2 -I${SERVBAY_COMMON_INCLUDE_PATH}: aggiunge le directory delle include generali di ServBay, assicurando che i file di intestazione di libxml2 e altri siano disponibili.
  • -L${SERVBAY_COMMON_LIB_PATH} -lxml2 -lz ...: aggiunge la directory delle librerie comuni ServBay e collega le librerie richieste (libxml2, zlib, pthread, iconv, icu, ecc.), tutte comunemente incluse nell'ambiente di compilazione ServBay.
  • -std=c++17: stabilisce l’uso dello standard C++17 (richiesto da molti progetti moderni).

Passaggio 4: Compila e installa

Dopo la configurazione, usa make per compilare, quindi make install per installare i file nella directory di destinazione precedentemente selezionata con --prefix.

make -j ${CPU_NUMBER}
make install

• make -j ${CPU_NUMBER}: avvia la compilazione. Il parametro -j ${CPU_NUMBER} abilita la compilazione parallela (dove ${CPU_NUMBER} è impostato dall’ambiente ServBay), accelerando il processo.
• make install: copia i file generati (librerie condivise PostGIS, script SQL ecc.) nelle posizioni appropriate nella directory di installazione di PostgreSQL 15.7 (tipicamente lib/postgresql e share/postgresql/extension).

Passaggio 5: Verifica il caricamento del modulo

Dopo la compilazione e installazione, abilita l’estensione postgis all’interno del database PostgreSQL. Usa la CLI (psql) fornita da ServBay (assicurati che le variabili d’ambiente ServBay siano caricate nel terminale):

# Esegui CREATE EXTENSION per abilitare PostGIS
${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/psql -c "CREATE EXTENSION postgis;"

Se il comando è eseguito con successo, l’estensione PostGIS è stata creata. Puoi verificarne la versione:

# Verifica la versione di PostGIS
${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/psql -c "SELECT PostGIS_Version();"

Se tutto è a posto, vedrai la versione di PostGIS stampata sul terminale, confermando che il modulo è stato compilato, installato e caricato nel database con successo.

Compilazione del modulo pg_jieba

pg_jieba è un’estensione PostgreSQL, basata sulla libreria C++ cppjieba, che offre la segmentazione della lingua cinese nel database. È molto usato per la ricerca full-text. Il sistema di build usato è CMake. Ecco i passaggi:

Passaggio 1: Ottieni il sorgente

Prima di tutto, clona il repository GitHub di pg_jieba. Siccome pg_jieba dipende dal submodulo Git cppjieba, bisogna inizializzare e aggiornare anche i submoduli.

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

• git clone ...: clona il repository di pg_jieba nella directory corrente.
• git submodule update --init --recursive: inizializza e aggiorna tutti i submoduli Git del repository. Così facendo, il codice di cppjieba viene scaricato nella directory appropriata sotto il progetto.

Passaggio 2: Configura le opzioni di compilazione (CMake)

pg_jieba usa CMake. Similmente a ./configure per Autotools, CMake (con il comando cmake) genera i file di build specifici per la piattaforma (ad es. Makefile Unix). È necessario specificare il percorso d’installazione di PostgreSQL e i target di compilazione 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: avvia la configurazione CMake, generando la directory di build pulita builddir.
• -DCMAKE_PREFIX_PATH: opzione chiave, indica a CMake dove cercare librerie e intestazioni di PostgreSQL, puntando alla root dell’installazione. Verranno usate anche le info di pg_config.
• -DCMAKE_OSX_DEPLOYMENT_TARGET: imposta il target minimo di versione macOS per garantire compatibilità delle binarie.
• -DCMAKE_OSX_ARCHITECTURES: imposta l’architettura CPU per la build (x86_64, arm64 ecc.), secondo l’ambiente di build ServBay.

Passaggio 3: Compila e installa (CMake)

Dopo la configurazione, compila con cmake --build, quindi installa con cmake --install.

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

• cmake --build builddir: compila i sorgenti nella directory di build specificata.
• -j ${CPU_NUMBER}: attiva la compilazione parallela sfruttando tutti i core disponibili.
• cmake --install builddir: installa i file nella directory corretta di PostgreSQL, come determinata da -DCMAKE_PREFIX_PATH (insieme alle info di pg_config).

Passaggio 4: Verifica il caricamento del modulo

Dopo la compilazione e installazione, abilita l’estensione pg_jieba in PostgreSQL:

# Esegui CREATE EXTENSION per abilitare pg_jieba
${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/psql -c "CREATE EXTENSION pg_jieba;"

Se il comando va a buon fine, l’estensione pg_jieba è attiva. Puoi controllare la presenza tra le estensioni installate:

# Elenca le estensioni installate e verifica pg_jieba
${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/psql -c "SELECT * FROM pg_available_extensions WHERE name = 'pg_jieba';"

Se l’estensione appare nell’elenco, significa che tutto è stato compilato, installato e abilitato correttamente.

FAQ (Domande frequenti)

• La compilazione fallisce dicendo che mancano intestazioni o librerie?
  • Controlla che l'ambiente di compilazione ServBay sia stato inizializzato correttamente. Assicurati di aver eseguito lo script di inizializzazione del terminale ServBay e che tutte le variabili d’ambiente, come $CFLAGS, $LDFLAGS, ${SERVBAY_COMMON_INCLUDE_PATH}, ${SERVBAY_COMMON_LIB_PATH}, puntino ai percorsi giusti.
  • Verifica che il percorso della versione di PostgreSQL passato a --with-pgconfig (Autotools) o -DCMAKE_PREFIX_PATH (CMake) sia corretto e che il relativo file pg_config esista ed è eseguibile.
  • Alcuni moduli potrebbero avere dipendenze di sistema aggiuntive non presenti nei pacchetti comuni di ServBay (ad esempio, PostGIS con Raster/Topology potrebbe richiedere GEOS, GDAL ecc.). Se necessario, installa manualmente le dipendenze oppure disabilita le funzioni opzionali con i parametri di build.
• CREATE EXTENSION fallisce dicendo che il modulo non viene trovato?
  • Verifica che make install (Autotools) oppure cmake --install (CMake) siano andati a buon fine senza errori. Controlla i log di installazione per assicurarti che i file siano nelle cartelle giuste.
  • Controlla che i percorsi passati con --prefix (Autotools) o -DCMAKE_PREFIX_PATH (CMake) puntino alla directory di installazione ServBay corretta per la versione di PostgreSQL. I file modulo dovrebbero essere sotto lib/postgresql.
  • Prova a riavviare il servizio PostgreSQL; a volte è necessario perché il database riconosca nuovi moduli.
  • Controlla il parametro shared_preload_libraries di PostgreSQL. Per la maggior parte delle estensioni semplici (CREATE EXTENSION), non serve modificare nulla, ma moduli che agiscono in profondità potrebbero richiederlo. Consulta sempre la documentazione dello specifico modulo da compilare.
• Come si compila un modulo per una versione diversa di PostgreSQL?
  • Ripeti tutti i passaggi, ma durante la configurazione (./configure o cmake) punta il parametro --with-pgconfig (Autotools) o -DCMAKE_PREFIX_PATH (CMake) alla directory e al file pg_config della versione di destinazione, ad esempio ${SERVBAY_PACKAGE_FULL_PATH}/postgresql/14/14.x/bin/pg_config per ServBay PostgreSQL 14 (14.x è la versione specifica).

Conclusione

Seguendo queste istruzioni e sfruttando l’ambiente e gli strumenti forniti da ServBay, puoi compilare e installare con successo i moduli PostgreSQL richiesti nel tuo ambiente di sviluppo locale, ampliando le funzionalità del database in base alle esigenze di ogni progetto. I passaggi cruciali sono: inizializzare l’ambiente ServBay, specificare la versione corretta di PostgreSQL, e ricontrollare configurazione e percorsi d’installazione.

Ci auguriamo che questa guida ti aiuti a personalizzare facilmente PostgreSQL su ServBay. Se dovessi riscontrare ulteriori difficoltà, consulta la documentazione o le risorse della community di ServBay.