Як зібрати модулі PostgreSQL у ServBay

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

У цьому матеріалі детально розглянуто збірку та встановлення модулів PostgreSQL у середовищі ServBay на прикладі поширених postgis (підтримка геоінформаційних систем) та pg_jieba (китайський текстовий сегментатор).

Огляд

ServBay забезпечує гнучке та потужне середовище, в якому розробник може здійснювати доопрацювання інтегрованих пакетів або компілювати додаткові компоненти. Збірка модулів PostgreSQL зазвичай включає завантаження вихідних кодів, налаштування параметрів компіляції, використання відповідних інструментів побудови (наприклад, make або cmake) і подальше встановлення, після чого модуль активується в самій базі даних.

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

Попередні вимоги

Перед початком компіляції будь-якого модуля PostgreSQL обов’язково слід ініціалізувати компіляційне середовище відповідно до інструкцій ServBay. Це потрібно для того, щоб коректно встановити всі потрібні інструменти (компілятор, компоновщик тощо), змінні середовища (наприклад, $PATH, $CFLAGS, $LDFLAGS тощо), а також шляхи до специфічних конфігурацій ServBay.

Детальніше про підготовку середовища читайте в офіційній документації ServBay у розділі Друге компілювання з використанням ServBay. Обов’язково виконайте всі кроки підготовки середовища — зазвичай це означає запуск спеціального скрипту ініціалізації середовища у терміналі ServBay.

Важливість вибору версії PostgreSQL

ServBay підтримує встановлення й запуск кількох версій PostgreSQL паралельно. Оскільки компіляція та робота модулів PostgreSQL тісно пов’язані з конкретною версією (залежать від заголовочних файлів, бібліотек і API), у процесі компіляції завжди потрібно чітко вказувати, для якої версії ви збираєте модуль і шляхи до її конфігурації.

Вибір правильного конфігураційного шляху PostgreSQL гарантує, що збірка знайде всі потрібні залежності та створить модуль, сумісний із потрібною версією PostgreSQL, що дозволить уникнути помилок під час компіляції чи імпорту модуля.

У прикладах нижче ми використовуємо версію PostgreSQL 15 у ServBay (наприклад, 15.7). Шляхи слід скорегувати згідно з реально встановленою версією.

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

Збірка модуля postgis

Модуль postgis — один із найпотужніших і найпоширеніших розширень PostgreSQL, що додає підтримку геоінформаційних об’єктів і функцій, дозволяє зберігати, шукати й аналізувати просторові дані. Нижче наведений докладний алгоритм компіляції версії postgis-3.4.2.

Крок 1: Завантаження вихідного коду

Завантажте пакет з вихідними кодами з офіційного сайту PostGIS. Переконайтеся, що ви захопили саме архів з вихідним кодом (зазвичай формат .tar.gz або .zip).

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

wget — команда для завантаження файлів із вказаного URL.

Крок 2: Розпакування архіву

Розпакуйте архів та перейдіть у створений каталог із вихідними кодами:

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

tar zxvf — команда розпаковує .tar.gz архів, а cd перемикає поточний каталог на директорію з вихідними файлами.

Крок 3: Налаштування компіляції

PostGIS використовує GNU Autotools як систему збирання. На цьому кроці потрібно налаштувати параметри конфігурації, вказавши шляхи до потрібної версії 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: Шляхи, до яких буде встановлено PostGIS, – важливо вказати відповідні каталоги для потрібної версії PostgreSQL у ServBay. ${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7 — коренева директорія встановлення PostgreSQL 15.7 у ServBay, формується автоматично під час налаштування середовища.
• --with-protobufdir: Шлях до бібліотеки Protobuf, потрібної для PostGIS. ${SERVBAY_BIN_PATH} — місце розташування бінарних файлів ServBay.
• --disable-nls: Вимикає підтримку багатомовності (NLS) — для середовища розробника зазвичай не потрібно.
• --without-raster, --without-topology: Вимкнення підтримки Raster і Topology для спрощення збірки (можна додати їх, якщо це потрібно, з додатковими залежностями).
• --with-pgconfig: Критично важлива опція — шлях до виконуваного файлу pg_config обраної версії PostgreSQL. Саме він повідомляє скрипту PostGIS все необхідне для коректної компіляції і сумісності модуля.
• CFLAGS, CXXFLAGS, LDFLAGS: Додаткові параметри для компілятора і компоновщика (вказуються тут і підхоплюють значення, сформовані в середовищі ServBay).
  • -I${SERVBAY_COMMON_INCLUDE_PATH}/libxml2 -I${SERVBAY_COMMON_INCLUDE_PATH}: Додає шляхи до заголовочних файлів бібліотеки libxml2 і загальний інклуд-директорій.
  • -L${SERVBAY_COMMON_LIB_PATH} -lxml2 -lz ...: Додає каталог із загальними бібліотеками ServBay й специфічні бібліотеки, потрібні для PostGIS (libxml2, zlib, pthread, iconv, icu тощо).
  • -std=c++17: Встановлює стандарт C++17 (потрібно для багатьох сучасних C++ проектів).

Крок 4: Компіляція та встановлення

Після успішної конфігурації виконайте компіляцію командою make, а встановлення — командою make install:

make -j ${CPU_NUMBER}
make install

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

Крок 5: Перевірка завантаження модуля

Після успішної компіляції і встановлення необхідно активувати розширення postgis у вашій базі даних PostgreSQL. Підключіться до бази через термінал ServBay і запустіть такі SQL-команди:

# Створення розширення 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: Завантажує підмодуль cppjieba у потрібний підкаталог.

Крок 2: Налаштування компіляції (CMake)

pg_jieba використовує систему збирання CMake, тому запуск налаштування виглядає так:

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: Ключова директива: вказує CMake шукати бібліотеки й заголовочні файли PostgreSQL у потрібному місці.
• -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: Компілює проект у вказаному каталозі збірки.
• -j ${CPU_NUMBER}: Паралельна компіляція за кількістю ядер.
• cmake --install builddir: Встановлює зібрані файли у визначені підкаталоги PostgreSQL у ServBay.

Крок 4: Перевірка завантаження модуля

Після встановлення активуйте розширення pg_jieba у вашій БД PostgreSQL:

# Створення розширення 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}).
  • Перевірте правильність шляхів --with-pgconfig (Autotools) або -DCMAKE_PREFIX_PATH (CMake) — чи вказують вони на потрібну версію PostgreSQL і чи присутній там файл pg_config.
  • Деякі модулі мають додаткові зовнішні залежності (наприклад, PostGIS із Raster або Topology — потрібні GEOS, GDAL тощо). Якщо їх немає в компіляційному середовищі, або не встановлені — їх слід додати вручну чи вимкнути певні опції.
• CREATE EXTENSION завершується помилкою: не знайдено файл модуля?
  • Переконайтеся, що make install (Autotools) чи cmake --install (CMake) проходять без помилок — перевірте логи встановлення.
  • Знову перевірте, що для інсталяції вказаний правильний шлях: --prefix (Autotools) або -DCMAKE_PREFIX_PATH (CMake) мають містити шлях до потрібної версії PostgreSQL у ServBay, а файли мають потрапити до каталогу lib/postgresql.
  • Спробуйте перезапустити службу PostgreSQL через застосунок ServBay — інколи потрібно, щоб нові модулі підхопились базою даних.
  • Перевірте налаштування параметра shared_preload_libraries у PostgreSQL. Для більшості стандартних розширень змінювати його не потрібно, але для окремих нестандартних розширень може знадобитися це налаштування. Уточнюйте у документації конкретного модуля.
• Як збирати модулі під різні версії PostgreSQL?
  • Повторіть процес, але на кроці збірки (./configure чи cmake) вкажіть шлях до потрібної версії PostgreSQL у параметрі --with-pgconfig (Autotools) або -DCMAKE_PREFIX_PATH (CMake), наприклад ${SERVBAY_PACKAGE_FULL_PATH}/postgresql/14/14.x/bin/pg_config чи ${SERVBAY_PACKAGE_FULL_PATH}/postgresql/14/14.x для PostgreSQL 14 (де 14.x — конкретна версія).

Підсумок

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

Сподіваємося, що цей посібник допоможе вам успішно кастомізувати PostgreSQL у ServBay. Якщо виникають питання чи труднощі, звертайтеся до інших документаційних матеріалів ServBay чи ресурсів спільноти.