Как скомпилировать модули PostgreSQL в ServBay

Во время разработки с использованием локальной web-среды ServBay для PostgreSQL нередко возникает задача компиляции и установки дополнительных модулей PostgreSQL (расширений) для расширения или усиления функциональности базы данных. Такие модули добавляют новые типы данных, функции, операторы, методы доступа к индексам и многое другое.

В этом руководстве подробно описано, как компилировать и устанавливать модули PostgreSQL в среде ServBay, используя самые востребованные расширения — postgis (географические расширения) и pg_jieba (разбиение китайского текста на слова) — в качестве примеров.

Обзор

ServBay предоставляет гибкую и мощную среду, которая позволяет разработчикам дорабатывать интегрированные в неё пакеты либо компилировать дополнительные компоненты. Обычно процесс компиляции модуля PostgreSQL включает скачивание исходного кода модуля, настройку параметров сборки, использование специализированных инструментов сборки (например, make или cmake) для компиляции и установки, а после — активацию модуля в базе данных PostgreSQL.

Ключ к успешной сборке — правильно настроенная компиляционная среда, способная обнаруживать заголовочные файлы, библиотеки и зависимости нужной версии PostgreSQL из набора ServBay.

Предварительные условия

Перед началом компиляции любых модулей PostgreSQL необходимо инициализировать компиляционную среду согласно требованиям ServBay. Это обязательный этап: он обеспечивает установку инструментальной цепочки (компиляторов, компоновщиков и т.д.), системных переменных окружения (таких как $PATH, $CFLAGS, $LDFLAGS и др.), а также специфические пути сборки в рамках ServBay.

Подробные инструкции по инициализации среды вы найдете в разделе Вторичная компиляция в ServBay официальной документации ServBay. Обязательно завершите подготовку среды, как описано в этом документе—чаще всего речь идет о запуске определённого скрипта инициализации в терминале ServBay.

Важность выбора версии PostgreSQL

ServBay поддерживает одновременную установку и работу нескольких версий пакета PostgreSQL. Поскольку процесс компиляции и запуска модулей привязан к конкретной версии (включая заголовочные файлы, библиотеки и внутренние API), при сборке дополнений необходимо чётко указать версию PostgreSQL и соответствующие пути к конфигурациям.

Верно выбранный путь установки PostgreSQL гарантирует обнаружение всех зависимостей сборки и генерацию модулей, полностью совместимых с целевой версией PostgreSQL — это предотвращает ошибки компиляции, сбои при загрузке и непредсказуемые проблемы в работе.

В этом руководстве в качестве примера рассмотрена версия PostgreSQL 15 (например, 15.7), установленная в ServBay. При необходимости подставьте пути, актуальные для вашей версии PostgreSQL.

ServBay облегчает поиск нужных путей за счет переменных окружения и утилиты pg_config. Используйте ${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/pg_config — эта программа встроена в PostgreSQL и показывает установочные и конфигурационные пути, местоположение библиотек, заголовочных файлов и другую важную информацию. Именно pg_config чаще всего используется для указания зависимостей при внешней сборке модулей.

Сборка модуля postgis

postgis — одно из самых востребованных расширений для PostgreSQL, добавляющее поддержку объектов и функций для работы с пространственными данными (геоинформационными системами, GIS). Вот как собрать версию postgis-3.4.2:

Шаг 1: Скачайте исходный код

Сначала получите исходный архив модуля с официального сайта PostGIS. Убедитесь, что скачиваете именно исходный код (архивы формата .tar.gz или .zip).

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

wget — утилита для скачивания файлов по указанной ссылке.

Шаг 2: Распакуйте архив

Распакуйте архив postgis-3.4.2.tar.gz в рабочую директорию и перейдите в неё.

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

tar zxvf — команда распаковки архивов .tar.gz. cd — переход в корневую директорию исходников postgis-3.4.2.

Шаг 3: Настройка параметров сборки

PostGIS собирается с помощью GNU Autotools. На этапе конфигурации проверяются зависимости, определяются особенности платформы и генерируется файл Makefile. Обязательно укажите параметры, которые укажут на вашу версию PostgreSQL внутри 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: запуск сценария конфигурации.
• --prefix, --bindir, --datarootdir: установка модулей во внутренние папки нужной версии PostgreSQL в ServBay. Это ключ к тому, чтобы PostgreSQL "нашёл" установленные расширения — ${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7 (обычно задается скриптами инициализации ServBay).
• --with-protobufdir: путь к библиотеке Protobuf, которую может использовать PostGIS — ${SERVBAY_BIN_PATH} содержит бинарные файлы ServBay.
• --disable-nls: отключение поддержки локализаций (обычно не нужно для разработки).
• --without-raster, --without-topology: отключение поддержки Raster и Topology (при необходимости можно включить, если готовы предоставить все зависимости).
• --with-pgconfig: самый важный параметр! — путь к конкретному pg_config версии PostgreSQL (даёт конфигурационные параметры, без которых невозможна совместимость).
• CFLAGS, CXXFLAGS, LDFLAGS: окружение компилятора и линкера:
  • -I${SERVBAY_COMMON_INCLUDE_PATH}/libxml2 -I${SERVBAY_COMMON_INCLUDE_PATH} — добавляет заголовочные файлы libxml2 и другие общие для ServBay библиотеки.
  • -L${SERVBAY_COMMON_LIB_PATH} ... — добавляет общую папку для библиотек и перечисляет необходимые зависимости (libxml2, zlib, pthread, iconv, ICU и др.), которые входят в состав ServBay.
  • -std=c++17 — стандарт C++17 для современных C++-проектов.

Шаг 4: Сборка и установка

После успешной конфигурации используйте команды make для компиляции и make install для установки модулей в нужную папку PostgreSQL, настроенную ранее.

make -j ${CPU_NUMBER}
make install

• make -j ${CPU_NUMBER}: сборка с максимальным параллелизмом, где ${CPU_NUMBER} — число ядер процессора, определённое средой ServBay.
• make install: копирует скомпилированные файлы (общие библиотеки, SQL-скрипты и др.) в подкаталоги установленной версии PostgreSQL в ServBay (обычно lib/postgresql, share/postgresql/extension и др.).

Шаг 5: Проверка загрузки модуля

После сборки и установки необходимо активировать расширение postgis в вашей базе. Используйте командную строку ServBay или любой удобный клиент PostgreSQL.

Важно быть в терминальной сессии ServBay — это обеспечивает корректные переменные окружения.

# Выполните команду для создания расширения PostGIS
${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/psql -c "CREATE EXTENSION postgis;"

Если команда выполнена успешно — PostGIS успешно создан. Проверить версию дополнения можно так:

# Запрос версии PostGIS
${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/psql -c "SELECT PostGIS_Version();"

Успешный вывод версии PostGIS подтверждает корректную сборку, установку и загрузку расширения.

Сборка модуля pg_jieba

pg_jieba — расширение для PostgreSQL, обеспечивающее китайское сегментирование текста (на основе C++-библиотеки cppjieba). Широко используется при полнотекстовом поиске и аналитике. Сборка происходит с помощью CMake. Ниже — актуальные шаги:

Шаг 1: Получение исходников

Склонируйте репозиторий с GitHub и инициализируйте подмодули (особенно cppjieba):

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

• git clone ...: загрузка репозитория pg_jieba в текущую директорию.
• git submodule update --init --recursive: инициализация и обновление всех git-подмодулей. Это нужно для автоматической загрузки исходников cppjieba в нужную иерархию.

Шаг 2: Настройка сборки (CMake)

Для pg_jieba источником сборочного процесса является CMake. Параметры перекликаются с вышеописанными — важно задать путь к PostgreSQL внутри 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: инициирует сборку в отдельной директории builddir, оставляя исходники чистыми.
• -DCMAKE_PREFIX_PATH: ключевой параметр для поиска библиотек/заголовков PostgreSQL под нужную версию в ServBay.
• -DCMAKE_OSX_DEPLOYMENT_TARGET: указывает минимальную поддерживаемую версию macOS для совместимости.
• -DCMAKE_OSX_ARCHITECTURES: указывает архитектуру процессора (x86_64 или arm64) текущей машины.

Шаг 3: Сборка и установка (CMake)

После настройки используйте команды для сборки и установки:

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

• cmake --build builddir: сборка модулей в папке builddir.
• -j ${CPU_NUMBER}: параллельная сборка (используйте максимальное количество ядер процессора — переменная задается средой ServBay).
• cmake --install builddir: установка в папки, которые определены по -DCMAKE_PREFIX_PATH совместно с информацией из pg_config PostgreSQL.

Шаг 4: Проверка загрузки модуля

Для завершения процесса активируйте расширение pg_jieba в своей базе данных. Выполняйте из терминала ServBay для корректного окружения:

# Создайте расширение pg_jieba
${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/psql -c "CREATE EXTENSION pg_jieba;"

После успешного создания расширения можно проверить его наличие командой:

# Список доступных расширений
${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/psql -c "SELECT * FROM pg_available_extensions WHERE name = 'pg_jieba';"

Если расширение отображается — сборка, установка и активация прошли успешно.

Часто задаваемые вопросы (FAQ)

• Ошибка сборки: не удаётся найти заголовочные или бинарные файлы?
  • Убедитесь, что среда ServBay действительно инициализирована, вы выполнили скрипт инициализации, и все переменные окружения ($CFLAGS, $LDFLAGS, ${SERVBAY_COMMON_INCLUDE_PATH}, ${SERVBAY_COMMON_LIB_PATH} и т.д.) корректно указывают на нужные директории ServBay.
  • Проверьте, что в командах --with-pgconfig (Autotools) или -DCMAKE_PREFIX_PATH (CMake) указан путь к реальной папке с нужной версией PostgreSQL и что файл pg_config существует и исполним.
  • Имейте в виду, что часть расширений требует специфических библиотек сверх стандартных (например, PostGIS c Raster/Topology нуждается в GEOS, GDAL и др.). Если нужной библиотеки нет — или установите её, или отключите соответствующую поддержку флагом.
• Ошибка CREATE EXTENSION: не найден файл модуля?
  • Убедитесь, что команды make install (Autotools) или cmake --install (CMake) завершились успешно и файлы были скопированы в целевые папки.
  • Проверьте, что аргумент --prefix (Autotools) или -DCMAKE_PREFIX_PATH (CMake) был корректно задан на этапе конфигурации — он должен вести ровно в каталог вашей версии PostgreSQL в ServBay.
  • Перезапустите сервис PostgreSQL — иногда перезапуск требуется, чтобы сервер "увидел" новые модули. В ServBay это делается через интерфейс приложения в несколько кликов.
  • Проверьте настройку shared_preload_libraries PostgreSQL — в большинстве случаев для стандартных расширений это не требуется, но некоторые плагины требуют указания своего имени явно (читайте документацию по модулю).
• Как собирать модули для других версий PostgreSQL?
  • Продублируйте все указанные выше шаги, отдельно подставив на этапе конфигурации (в ./configure или cmake) путь к нужной версии PostgreSQL (--with-pgconfig в Autotools или -DCMAKE_PREFIX_PATH в CMake). Например, для PostgreSQL 14 путь может иметь вид ${SERVBAY_PACKAGE_FULL_PATH}/postgresql/14/14.x/bin/pg_config или ${SERVBAY_PACKAGE_FULL_PATH}/postgresql/14/14.x (где 14.x — ваша версия).

Итоги

Следуя описанным шагам, а также используя инструменты и правильную компиляционную среду ServBay, вы легко соберете и подключите нужные модули для PostgreSQL. Благодаря этому база данных приобретёт новый функционал, соответствующий вашим задачам разработки. Запомните: критически важны корректная инициализация среды ServBay, верное указание версии PostgreSQL, а также внимательное отношение к деталям конфигурации и путям установки.

Надеемся, это руководство поможет вам быстро настроить и расширить вашу PostgreSQL-среду в ServBay. При возникновении дополнительных вопросов обращайтесь к документации либо сообществу пользователей ServBay.