Cómo compilar módulos de PostgreSQL en ServBay

Cuando desarrollas con PostgreSQL en el entorno local de ServBay, puede que necesites compilar e instalar módulos adicionales de PostgreSQL (también llamados extensiones) para mejorar o ampliar las capacidades de tu base de datos. Estos módulos pueden aportar nuevos tipos de datos, funciones, operadores, métodos de acceso a índices, y más.

En este artículo se explica con detalle cómo compilar e instalar módulos de PostgreSQL en ServBay, usando como ejemplos los módulos populares postgis (soporte para Sistemas de Información Geográfica) y pg_jieba (segmentación de texto en chino).

Descripción general

ServBay proporciona un entorno flexible y completo, permitiendo que los desarrolladores puedan realizar compilaciones secundarias o agregar componentes adicionales sobre sus paquetes integrados. Compilar módulos de PostgreSQL normalmente consiste en descargar el código fuente del módulo, configurar las opciones de compilación, usar herramientas específicas (como make o cmake) para compilar e instalar, y finalmente habilitar el módulo en la base de datos PostgreSQL.

La clave del éxito está en configurar correctamente el entorno de compilación, de modo que encuentre los encabezados, las bibliotecas y las dependencias correspondientes a la versión específica de PostgreSQL instalada en ServBay.

Requisitos previos

Antes de compilar cualquier módulo de PostgreSQL, es imprescindible inicializar el entorno de compilación siguiendo los requerimientos de ServBay. Este paso es obligatorio porque configura la cadena de herramientas necesaria (compiladores, enlazadores, etc.), variables de entorno (como $PATH, $CFLAGS, $LDFLAGS, etc.) y las rutas de configuración específicas de compilación de ServBay.

Para los pasos detallados sobre cómo inicializar el entorno de compilación, consulta la sección Compilación secundaria en ServBay en la documentación oficial. Debes completar la preparación allí indicada, normalmente ejecutando un script específico en la terminal de ServBay para preparar el entorno.

Importancia de especificar la versión de PostgreSQL

ServBay permite instalar y ejecutar varias versiones de PostgreSQL en paralelo. Dado que la compilación y ejecución de los módulos están estrechamente relacionadas con la versión de la base de datos (por ejemplo, dependiendo de encabezados, bibliotecas y APIs internas específicas), es fundamental especificar explícitamente la versión de PostgreSQL y sus rutas de configuración al compilar un módulo.

Seleccionar la ruta de configuración adecuada para la versión correcta de PostgreSQL evitará errores de compilación o de carga, y asegurará que los módulos sean compatibles y funcionen correctamente con la versión destino.

En este ejemplo, usaremos la versión PostgreSQL 15 instalada en ServBay (versión como 15.7). Ajusta las rutas conforme a la versión que estés usando.

ServBay ayuda a localizar las rutas correctas mediante variables de entorno y la herramienta pg_config. ${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/pg_config es una utilidad de PostgreSQL que reporta la información de ruta de instalación, configuración, bibliotecas y encabezados. Es una referencia clave durante la compilación de módulos externos.

Compilación del módulo postgis

postgis es una de las extensiones más populares y potentes para PostgreSQL, ya que añade soporte para objetos y funciones GIS, permitiendo almacenar, consultar y analizar datos espaciales. A continuación se detallan los pasos para compilar el módulo postgis-3.4.2:

Paso 1: Descargar el código fuente

Descarga el paquete fuente postgis-3.4.2 desde el sitio web oficial. Asegúrate de descargar la versión con código fuente (normalmente .tar.gz o .zip).

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

wget es una herramienta en línea de comandos para descargar archivos desde un URL especificado.

Paso 2: Descomprimir el paquete fuente

Descomprime el paquete descargado en un directorio local y accede a esa carpeta.

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

El comando tar zxvf descomprime archivos en formato .tar.gz. cd cambia el directorio actual al raíz del código fuente recién extraído.

Paso 3: Configurar las opciones de compilación

PostGIS utiliza GNU Autotools como sistema de construcción. Este paso verifica dependencias y prepara el archivo Makefile. Debes indicar las rutas de la versión de PostgreSQL correspondiente en ServBay y las rutas de otras bibliotecas necesarias.

./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: Ejecuta el script de configuración.
• --prefix, --bindir, --datarootdir: Especifica que la instalación de PostGIS debe realizarse bajo la estructura de directorios del PostgreSQL de ServBay. ${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7 es la raíz para PostgreSQL 15.7 en ServBay, definida por el script de inicialización del entorno.
• --with-protobufdir: Ruta de la biblioteca Protobuf, posible dependencia de PostGIS. ${SERVBAY_BIN_PATH} es la ruta de binarios de ServBay.
• --disable-nls: Desactiva soporte para idiomas, innecesario en desarrollo.
• --without-raster, --without-topology: Desactiva soporte para Raster y Topología, simplificando la compilación. Puedes habilitarlo si lo requieres (instalando dependencias adicionales).
• --with-pgconfig: Opción clave. Ruta al pg_config de la versión de PostgreSQL objetivo; proporciona flags de compilación y rutas a PostGIS, asegurando compatibilidad.
• CFLAGS, CXXFLAGS, LDFLAGS: Variables estándar para pasar parámetros adicionales a los compiladores de C/C++. ${CFLAGS}, ${CXXFLAGS}, ${LDFLAGS} preservan los valores por defecto establecidos por el entorno ServBay.
  • -I${SERVBAY_COMMON_INCLUDE_PATH}/libxml2 -I${SERVBAY_COMMON_INCLUDE_PATH}: Añade rutas de encabezados comunes, como los de libxml2.
  • -L${SERVBAY_COMMON_LIB_PATH} -lxml2 -lz ...: Añade rutas de bibliotecas y enlaza las dependencias habituales, todas disponibles en el entorno de ServBay.
  • -std=c++17: Especifica el estándar C++17, necesario para muchos proyectos modernos.

Paso 4: Compilar e instalar

Tras una configuración exitosa, utiliza make para compilar el código y make install para instalar los archivos a las rutas especificadas.

make -j ${CPU_NUMBER}
make install

• make -j ${CPU_NUMBER}: Lanza la compilación. La opción -j ${CPU_NUMBER} permite la compilación en paralelo usando los núcleos del CPU asignados por ServBay.
• make install: Copia los archivos generados (bibliotecas compartidas, scripts SQL, etc.) a las carpetas correspondientes dentro del PostgreSQL 15.7 en ServBay (lib/postgresql, share/postgresql/extension, etc.).

Paso 5: Verificar la carga del módulo

Una vez instalados, habilita la extensión postgis usando tu cliente preferido de PostgreSQL, conectándote a la base de datos mediante la terminal de ServBay o el método de tu elección.

Usa el cliente de línea de comandos psql disponible en ServBay (asegúrate de tener activo el entorno ServBay en la terminal):

# Ejecutar CREATE EXTENSION para habilitar PostGIS
${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/psql -c "CREATE EXTENSION postgis;"

Si el comando es exitoso, tendrás PostGIS instalado y habilitado. Puedes validar la versión de la extensión con:

# Consultar la versión de PostGIS
${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/psql -c "SELECT PostGIS_Version();"

Deberías ver la versión de PostGIS como resultado, confirmando que la compilación, instalación y carga en la base de datos fueron exitosas.

Compilación del módulo pg_jieba

pg_jieba es una extensión basada en la biblioteca C++ cppjieba que implementa segmentación de texto chino en PostgreSQL, útil para búsquedas de texto completo. Usa CMake como sistema de construcción. Los pasos para compilarlo son los siguientes:

Paso 1: Obtener el código fuente

Clona el repositorio del módulo pg_jieba desde GitHub. pg_jieba depende de cppjieba como submódulo de Git, así que inicialmente también debes inicializarlo y actualizarlo.

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

• git clone ...: Clona el repositorio de pg_jieba en el directorio actual.
• git submodule update --init --recursive: Inicializa y actualiza los submódulos de Git, como cppjieba, descargando el código fuente necesario para la compilación.

Paso 2: Configurar las opciones de compilación (CMake)

pg_jieba se compila mediante CMake. Al igual que el ./configure de Autotools, usa cmake para generar los archivos de construcción, especificando la ruta del PostgreSQL destino y las opciones específicas para el entorno de 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: Ejecuta CMake en el directorio actual y crea la carpeta builddir para guardar los archivos de construcción.
• -DCMAKE_PREFIX_PATH: Opción clave. Indica a CMake dónde buscar encabezados y bibliotecas, especialmente los de PostgreSQL (en ServBay para 15.7).
• -DCMAKE_OSX_DEPLOYMENT_TARGET: Define la versión mínima de macOS soportada, asegurando compatibilidad.
• -DCMAKE_OSX_ARCHITECTURES: Especifica la arquitectura del CPU objetivo (por ejemplo, x86_64 o arm64), definida por el entorno de ServBay.

Paso 3: Compilar e instalar (CMake)

Tras la configuración, compila el código y ejecuta la instalación con los siguientes comandos:

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

• cmake --build builddir: Compila el código fuente en el directorio de construcción.
• -j ${CPU_NUMBER}: Compila en paralelo, aprovechando todos los núcleos disponibles.
• cmake --install builddir: Instala los archivos generados en el directorio adecuado de PostgreSQL, según lo indicado por -DCMAKE_PREFIX_PATH y la lógica interna de CMake.

Paso 4: Verificar la carga del módulo

Cuando la instalación finalice, activa la extensión en tu base de datos. Usa la terminal de ServBay con el entorno cargado:

# Ejecutar CREATE EXTENSION para habilitar pg_jieba
${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/psql -c "CREATE EXTENSION pg_jieba;"

Si fue exitoso, puedes consultar el listado de extensiones disponibles para corroborar la instalación:

# Listar extensiones instaladas
${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/psql -c "SELECT * FROM pg_available_extensions WHERE name = 'pg_jieba';"

Si el módulo aparece en la lista, la compilación, instalación y habilitación fueron exitosas.

Preguntas frecuentes (FAQ)

• ¿La compilación falla porque no encuentra archivos de encabezado o bibliotecas?
  • Verifica que tienes correctamente inicializado el entorno de compilación de ServBay. Asegúrate de haber ejecutado el script de inicialización y de que las variables de entorno ($CFLAGS, $LDFLAGS, ${SERVBAY_COMMON_INCLUDE_PATH}, ${SERVBAY_COMMON_LIB_PATH}, etc.) están correctamente definidas y referencian las rutas correctas.
  • Comprueba que la ruta especificada para --with-pgconfig (en Autotools) o -DCMAKE_PREFIX_PATH (en CMake) corresponde al PostgreSQL correcto y que el archivo pg_config existe y es ejecutable.
  • Algunos módulos pueden requerir dependencias adicionales (por ejemplo, PostGIS con Raster/Topology requiere GEOS, GDAL, etc.). Si falta alguna, instálala manualmente o desactiva las funciones correspondientes.
• ¿CREATE EXTENSION falla porque no se encuentra el módulo?
  • Verifica que los comandos make install (Autotools) o cmake --install (CMake) se ejecutaron sin errores y que los archivos fueron copiados a los directorios correctos.
  • Confirma que --prefix (Autotools) o -DCMAKE_PREFIX_PATH (CMake) en la configuración apuntan al directorio de la versión objetivo de PostgreSQL en ServBay. Los archivos suelen instalarse en el subdirectorio lib/postgresql.
  • Prueba a reiniciar el servicio de PostgreSQL; algunas veces, un reinicio es necesario para que el sistema detecte nuevos módulos. Desde la interfaz de ServBay puedes reiniciarlo fácilmente.
  • Revisa la configuración de shared_preload_libraries en PostgreSQL. Para la mayoría de las extensiones normales (vía CREATE EXTENSION) no es necesario modificarla, pero algunos módulos especiales pueden requerir que se añadan a dicha lista para cargarse en el arranque. Consulta la documentación del módulo que estés compilando.
• ¿Cómo compilar módulos para diferentes versiones de PostgreSQL?
  • Repite los pasos de compilación anteriores, pero asegúrate de que en la configuración (./configure o cmake) la ruta de --with-pgconfig (Autotools) o -DCMAKE_PREFIX_PATH (CMake) apunte a la versión deseada del PostgreSQL. Por ejemplo, si deseas compilar para PostgreSQL 14, la ruta será del tipo ${SERVBAY_PACKAGE_FULL_PATH}/postgresql/14/14.x/bin/pg_config o ${SERVBAY_PACKAGE_FULL_PATH}/postgresql/14/14.x (donde 14.x es la versión específica instalada).

Resumen

Si sigues los pasos anteriores y aprovechas correctamente las herramientas y el entorno de compilación que ofrece ServBay, podrás compilar e instalar exitosamente los módulos de PostgreSQL que necesites, ampliando así las funcionalidades de tu base de datos según los requisitos de tu desarrollo. La clave está en inicializar correctamente el entorno de ServBay, especificar claramente la versión de PostgreSQL a la que apuntas y revisar cuidadosamente las configuraciones de compilación e instalación.

Esperamos que esta guía te ayude a personalizar tu entorno PostgreSQL en ServBay. Ante dudas o inconvenientes, consulta la documentación oficial o los recursos comunitarios de ServBay.