Como compilar módulos do PostgreSQL no ServBay

Ao utilizar o ambiente local de desenvolvimento web do ServBay para desenvolvimento com PostgreSQL, pode ser necessário compilar e instalar módulos extras do PostgreSQL (também chamados de extensões) para ampliar ou estender as funcionalidades do banco de dados. Esses módulos podem fornecer novos tipos de dados, funções, operadores, métodos de acesso a índices e muito mais.

Este artigo explica em detalhes como compilar e instalar módulos do PostgreSQL no ambiente ServBay, utilizando como exemplos os módulos populares postgis (suporte a sistema de informações geográficas) e pg_jieba (segmentação de texto em chinês).

Visão geral

O ServBay oferece um ambiente robusto e flexível que permite aos desenvolvedores criar ou compilar componentes adicionais a partir dos pacotes integrados. Compilar módulos do PostgreSQL geralmente envolve baixar o código-fonte do módulo, configurar as opções de compilação, utilizar ferramentas de construção específicas (como make ou cmake) para compilar e instalar, e finalmente habilitar o módulo no banco de dados PostgreSQL.

O segredo do sucesso é configurar corretamente o ambiente de compilação, de modo que ele consiga localizar os arquivos de cabeçalho, bibliotecas e dependências do PostgreSQL na versão específica instalada no ServBay.

Pré-requisitos

Antes de compilar qualquer módulo do PostgreSQL, é obrigatório inicializar o ambiente de compilação conforme requerido pelo ServBay. Esta etapa é essencial, pois prepara toda a cadeia de ferramentas necessária para compilação (compilador, linker, etc.), variáveis de ambiente (como $PATH, $CFLAGS, $LDFLAGS etc.) e caminhos de configuração específicos do ServBay.

Para as instruções detalhadas sobre como inicializar o ambiente de compilação, consulte a seção Compilação secundária com ServBay na documentação oficial do ServBay. Certifique-se de concluir toda a preparação do ambiente descrita naquele guia, normalmente envolvendo a execução de um script de inicialização de ambiente no terminal do ServBay.

Importância de especificar a versão do PostgreSQL

O ServBay permite instalar e executar múltiplas versões do PostgreSQL. Como a compilação e o funcionamento dos módulos do PostgreSQL dependem fortemente da versão do banco (por exemplo, dependências com arquivos de cabeçalho, bibliotecas e APIs internas), é fundamental especificar claramente a versão do PostgreSQL e os caminhos de configuração correspondentes ao compilar um módulo.

Escolher o caminho de configuração correto garante que o processo de compilação encontre as dependências corretas e gere módulos compatíveis com a versão alvo do PostgreSQL — evitando erros de compilação, falhas no carregamento ou outros problemas imprevisíveis em tempo de execução.

Neste exemplo, utilizamos o PostgreSQL 15 instalado via ServBay (por exemplo, versão 15.7). Ajuste os caminhos conforme a versão do PostgreSQL em uso.

O ServBay auxilia na localização desses caminhos certos usando variáveis de ambiente e a ferramenta pg_config. ${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/pg_config é uma ferramenta essencial fornecida pelo próprio PostgreSQL, capaz de informar os caminhos de instalação, informações de configuração, caminhos de bibliotecas e cabeçalhos daquela versão. O uso do pg_config é crucial para compilar módulos externos corretamente.

Compilando o módulo postgis

O módulo postgis é uma das extensões mais populares e poderosas do PostgreSQL, trazendo suporte a objetos e funções para sistemas de informações geográficas (GIS), possibilitando armazenar, pesquisar e analisar dados espaciais. Veja o passo a passo para compilar o módulo postgis-3.4.2:

Passo 1: Baixe o código-fonte

Primeiramente, baixe o pacote de código-fonte do postgis-3.4.2 no site oficial do PostGIS. Certifique-se de baixar a versão de código-fonte (geralmente nos formatos .tar.gz ou .zip).

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

O wget é uma ferramenta de linha de comando bastante usada para baixar arquivos de uma URL.

Passo 2: Extraia o pacote

Extraia o arquivo compactado postgis-3.4.2.tar.gz para um diretório local e acesse a pasta recém-criada.

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

O comando tar zxvf descompacta arquivos .tar.gz. O cd muda para o diretório raiz do código-fonte extraído.

Passo 3: Configure as opções de compilação

O PostGIS utiliza o GNU Autotools como sistema de build. A etapa de configuração verifica dependências, determina recursos de compilação e gera o arquivo Makefile. Aqui, é essencial informar os caminhos de instalação e bibliotecas do PostgreSQL para a versão correta do ServBay.

./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: executa o script de configuração.
• --prefix, --bindir, --datarootdir: define os diretórios de instalação do PostGIS para a estrutura da versão específica do PostgreSQL no ServBay. Isto garante que os arquivos do módulo sejam localizados corretamente pelo PostgreSQL dentro de sua hierarquia padrão. ${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7 é o diretório raiz, fornecido pelo script de inicialização do ambiente ServBay.
• --with-protobufdir: caminho da biblioteca Protobuf, caso seja dependência. ${SERVBAY_BIN_PATH} aponta para os binários do ServBay.
• --disable-nls: desativa suporte a idiomas, geralmente dispensável em ambientes de desenvolvimento.
• --without-raster, --without-topology: desativa recursos opcionais do PostGIS, facilitando a compilação; ative conforme necessidade (pode exigir dependências extras).
• --with-pgconfig: opção crucial, aponta para o executável pg_config da versão desejada, fornecendo ao script informações de compilação, bibliotecas e caminhos corretos.
• CFLAGS, CXXFLAGS, LDFLAGS: variáveis padrão para incluir parâmetros extras ao compilador/linker. ${CFLAGS}, ${CXXFLAGS}, ${LDFLAGS} mantêm as configurações padrão do ambiente ServBay.
  • -I${SERVBAY_COMMON_INCLUDE_PATH}/libxml2 -I${SERVBAY_COMMON_INCLUDE_PATH}: inclui diretórios de cabeçalhos comuns do ServBay, garantindo que bibliotecas como libxml2 estejam acessíveis.
  • -L${SERVBAY_COMMON_LIB_PATH} -lxml2 -lz ...: adiciona diretório de bibliotecas comuns do ServBay e define as libs necessárias (libxml2, zlib, pthread, iconv, icu etc.).
  • -std=c++17: define a versão do padrão C++ para C++17, comum a muitos projetos atuais em C++.

Passo 4: Compile e instale

Após a configuração, compile com o comando make e instale com make install, depositando os arquivos no diretório do ServBay PostgreSQL definido anteriormente.

make -j ${CPU_NUMBER}
make install

• make -j ${CPU_NUMBER}: inicia a compilação. O parâmetro -j ${CPU_NUMBER} utiliza múltiplos núcleos do processador, acelerando o processo.
• make install: copia os arquivos gerados (biblioteca compartilhada, scripts SQL, etc.) para os subdiretórios apropriados do PostgreSQL 15.7 no ServBay (tipicamente lib/postgresql e share/postgresql/extension).

Passo 5: Verifique o carregamento do módulo

Concluída a instalação, é preciso habilitar a extensão postgis no banco de dados PostgreSQL. Conecte-se usando a CLI do ServBay ou seu cliente SQL favorito e execute:

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

Se tudo correr bem, a extensão estará criada. Para confirmar a versão instalada:

# Consulte a versão do PostGIS
${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/psql -c "SELECT PostGIS_Version();"

A saída deverá mostrar o número da versão, indicando sucesso na compilação, instalação e carregamento da extensão.

Compilando o módulo pg_jieba

O pg_jieba é uma extensão baseada na biblioteca C++ cppjieba, trazendo segmentação de texto chinês para o PostgreSQL, útil em pesquisas full-text e similares. O pg_jieba usa o CMake como sistema de build. Veja os passos para compilar esta extensão:

Passo 1: Obtenha o código-fonte

Clone o repositório do pg_jieba no GitHub. Ele depende do cppjieba como submódulo Git, portanto inicialize e atualize os submódulos após o clone.

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

• git clone ...: clona o repositório do pg_jieba.
• git submodule update --init --recursive: inicializa e atualiza todos os submódulos, incluindo o cppjieba dentro do repositório principal.

Passo 2: Configure as opções de compilação (CMake)

O pg_jieba usa CMake. Semelhante ao ./configure do Autotools, o comando cmake irá gerar os arquivos de build para o seu sistema. Indique o caminho de instalação do PostgreSQL e as opções necessárias do ServBay/macOS.

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: roda o CMake com o diretório-fonte atual e um subdiretório builddir para a saída dos builds.
• -DCMAKE_PREFIX_PATH: opção chave, define onde o CMake irá buscar por bibliotecas e cabeçalhos dependentes do PostgreSQL, aqui apontando para o diretório de instalação do PostgreSQL 15.7 no ServBay.
• -DCMAKE_OSX_DEPLOYMENT_TARGET: define a versão mínima do macOS suportada — ${BUILD_OS_MIN_VERSION} é definido pelo ambiente do ServBay.
• -DCMAKE_OSX_ARCHITECTURES: define para qual arquitetura compilar (ex.: x86_64 ou arm64), baseada em ${BUILD_CPU_ARCH_CMAKE} do ambiente ServBay.

Esses parâmetros garantem compatibilidade total do módulo com o macOS e o ambiente do ServBay.

Passo 3: Compile e instale (CMake)

Com tudo configurado, compile e instale usando os comandos a seguir:

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

• cmake --build builddir: compila os arquivos no diretório builddir.
• -j ${CPU_NUMBER}: compila em paralelo utilizando vários núcleos, conforme variável do ServBay.
• cmake --install builddir: instala os arquivos compilados nos diretórios adequados do PostgreSQL, automaticamente localizados usando as informações do caminho de prefixo e pg_config.

Passo 4: Verifique o carregamento da extensão

Depois de instalar, habilite a extensão no banco de dados PostgreSQL usando:

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

Se a execução for bem-sucedida, a extensão foi criada. Para verificar, consulte:

# Consulte a lista de extensões instaladas
${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/psql -c "SELECT * FROM pg_available_extensions WHERE name = 'pg_jieba';"

Se aparecer nesta lista, significa que o ciclo de compilação, instalação e ativação foi bem-sucedido.

Perguntas frequentes (FAQ)

• Falha na compilação, erro de cabeçalhos ou bibliotecas não encontrados?
  • Verifique se você inicializou corretamente o ambiente de compilação do ServBay. Certifique-se de rodar o script de inicialização no terminal do ServBay e de que todas as variáveis de ambiente (ex.: $CFLAGS, $LDFLAGS, ${SERVBAY_COMMON_INCLUDE_PATH}, ${SERVBAY_COMMON_LIB_PATH}) estão configuradas corretamente.
  • Certifique-se de que o caminho para o pg_config (no Autotools) ou para o -DCMAKE_PREFIX_PATH (no CMake) está corretamente apontando para a versão pretendida do PostgreSQL e que o arquivo pg_config está presente e executável.
  • Alguns módulos têm dependências de sistema além das bibliotecas padrão do ServBay (ex.: para Raster/Topology do PostGIS são necessários GEOS, GDAL, etc.). Instale dependências ausentes manualmente ou desative funcionalidades opcionais relevantes.
• CREATE EXTENSION falha, erro de arquivo de módulo não encontrado?
  • Certifique-se de que o comando make install (Autotools) ou cmake --install (CMake) executou sem erros e os arquivos foram realmente copiados.
  • Verifique se o caminho especificado em --prefix ou -DCMAKE_PREFIX_PATH está correto e corresponde à instalação desejada do PostgreSQL no ServBay.
  • Tente reiniciar o serviço PostgreSQL — às vezes, um reinício é necessário para identificar novas extensões. Você pode reiniciar facilmente pelo painel do ServBay.
  • Para extensões comuns, não é necessário modificar a configuração shared_preload_libraries do PostgreSQL, mas para módulos que exigem hooks internos, talvez seja preciso adicionar o nome do módulo ali e reiniciar o banco. Consulte a documentação específica do módulo.
• Como compilar módulos para diferentes versões do PostgreSQL?
  • Repita os passos anteriores, assegurando-se de que nos comandos de configuração (Autotools ou CMake) o --with-pgconfig ou o -DCMAKE_PREFIX_PATH aponte para o caminho do pg_config da versão alvo (por exemplo, ${SERVBAY_PACKAGE_FULL_PATH}/postgresql/14/14.x/bin/pg_config para PostgreSQL 14).

Conclusão

Seguindo os passos acima e utilizando corretamente o ambiente de compilação e ferramentas fornecidas pelo ServBay, você conseguirá compilar e instalar extensões PostgreSQL localmente, expandindo as funcionalidades do seu banco para atender necessidades específicas de desenvolvimento. Inicializar o ambiente de compilação do ServBay, especificar a versão alvo do PostgreSQL e revisar cuidadosamente caminhos e configurações são fatores chave para o sucesso.

Esperamos que este guia facilite a personalização do seu ambiente PostgreSQL no ServBay. Se surgirem problemas adicionais, consulte a documentação ou recursos da comunidade do ServBay.