如何在 ServBay 中编译 PostgreSQL 模块

在使用 ServBay 本地 Web 开发环境进行 PostgreSQL 开发时，您可能需要编译和安装额外的 PostgreSQL 模块（也称为扩展），以增强或扩展数据库的功能。这些模块可以提供新的数据类型、函数、操作符、索引访问方法等。

本文将详细介绍如何在 ServBay 环境中编译和安装 PostgreSQL 模块，并通过编译常用的 postgis（地理信息系统支持）和 pg_jieba（中文分词）模块作为示例。

概述

ServBay 提供了灵活且功能丰富的环境，允许开发者在其集成的软件包基础上进行二次开发或编译额外的组件。编译 PostgreSQL 模块通常涉及下载模块源码、配置编译选项、使用特定的构建工具（如 make 或 cmake）进行编译和安装，最后在 PostgreSQL 数据库中启用模块。

成功的关键在于正确配置编译环境，使其能够找到 ServBay 中特定 PostgreSQL 版本的头文件、库文件以及所需的依赖项。

前提条件

在开始编译任何 PostgreSQL 模块之前，必须按照 ServBay 的要求初始化编译环境。这一步骤是必要的，因为它会设置好编译所需的工具链（编译器、链接器等）、环境变量（如 $PATH, $CFLAGS, $LDFLAGS 等）以及 ServBay 特定的构建配置路径。

有关如何初始化编译环境的详细步骤，请参考 ServBay 官方文档中的使用 ServBay 进行二次编译部分。请务必先完成该文档中描述的环境准备工作，通常涉及在 ServBay 终端中运行特定的环境初始化脚本。

指定 PostgreSQL 版本的重要性

ServBay 支持安装和运行多个版本的 PostgreSQL 软件包。由于 PostgreSQL 模块的编译和运行与特定的数据库版本紧密相关（例如，依赖于特定版本的头文件、库文件和内部 API），因此在使用编译工具进行编译时，务必明确指定您希望为其编译模块的 PostgreSQL 版本及其相关的配置路径。

选择正确的 PostgreSQL 版本配置路径可以确保编译过程能够找到正确的依赖项，并生成与目标 PostgreSQL 版本兼容的模块文件，从而避免编译错误、加载失败或运行时出现不可预测的问题。

本示例将以 ServBay 中安装的 PostgreSQL 15 版本（具体版本号如 15.7）为例进行说明。请根据您实际使用的 PostgreSQL 版本调整相应的路径。

ServBay 通过环境变量和 pg_config 工具帮助您找到正确路径。${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/pg_config 是一个非常有用的工具，它是 PostgreSQL 自带的程序，可以报告特定 PostgreSQL 版本的安装路径、编译配置信息、库路径、头文件路径等。在编译外部模块时，pg_config 是指定依赖的关键。

编译 postgis 模块

postgis 模块是 PostgreSQL 最流行和功能强大的扩展之一，它为 PostgreSQL 增加了地理信息系统（GIS）对象和函数支持，使其能够存储、查询和分析空间数据。以下是编译 postgis-3.4.2 模块的详细步骤：

步骤 1：下载源码

首先，从 PostGIS 官方网站下载 postgis-3.4.2 模块的源码包。请确保下载的是源代码版本（通常是 .tar.gz 或 .zip 格式）。

bash

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

wget 是一个常用的命令行工具，用于从指定的 URL 下载文件。

步骤 2：解压源码包

将下载的 postgis-3.4.2.tar.gz 源码包解压到本地目录，并进入解压后的源码目录。

bash

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 文件。在此步骤中，我们需要通过配置参数指定 ServBay 中特定 PostgreSQL 版本的安装路径以及其他必要的库路径。

bash

./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 安装到 ServBay 中特定 PostgreSQL 版本对应的目录结构下。这确保 PostgreSQL 能够在其标准搜索路径中找到安装的模块文件。${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7 是 ServBay 中 PostgreSQL 15.7 的安装根目录路径，这个路径通常由 ServBay 的编译环境初始化脚本设置。
--with-protobufdir: 指定 Protobuf 库的路径，PostGIS 可能依赖它。${SERVBAY_BIN_PATH} 是 ServBay 软件包的二进制文件路径。
--disable-nls: 禁用国家语言支持，通常在开发环境中不需要。
--without-raster, --without-topology: 禁用 PostGIS 的 Raster 和 Topology 支持，以简化编译过程。您可以根据需要启用它们，但这可能需要额外的依赖库。
--with-pgconfig: 最关键的选项，指定了用于编译的特定 PostgreSQL 版本的 pg_config 工具路径。pg_config 会提供 PostgreSQL 的编译 flags、库路径等信息给 PostGIS 的配置脚本，确保模块与目标 PostgreSQL 版本兼容。
CFLAGS, CXXFLAGS, LDFLAGS: 这些是标准的环境变量，用于向 C/C++ 编译器和链接器传递额外的参数。${CFLAGS}, ${CXXFLAGS}, ${LDFLAGS} 保留了 ServBay 环境初始化时设置的默认 flags。
- -I${SERVBAY_COMMON_INCLUDE_PATH}/libxml2 -I${SERVBAY_COMMON_INCLUDE_PATH}: 添加 ServBay 通用包含目录，确保编译器能找到 libxml2 等库的头文件。${SERVBAY_COMMON_INCLUDE_PATH} 是 ServBay 环境提供的通用头文件路径。
- -L${SERVBAY_COMMON_LIB_PATH} -lxml2 -lz ...: 添加 ServBay 通用库目录，并链接所需的库文件（如 libxml2, zlib, pthread, iconv, icu 等）。${SERVBAY_COMMON_LIB_PATH} 是 ServBay 环境提供的通用库文件路径。这些库是 PostGIS 的常见依赖，ServBay 编译环境通常已包含它们。
- -std=c++17: 为 C++ 编译器指定 C++17 标准，这是许多现代 C++ 项目的要求。

步骤 4：编译和安装

配置成功后，使用 make 命令编译源码，然后使用 make install 命令将编译好的模块文件安装到之前 --prefix 指定的 ServBay PostgreSQL 目录中。

bash

make -j ${CPU_NUMBER}
make install

make -j ${CPU_NUMBER}: 启动编译过程。-j ${CPU_NUMBER} 参数会并行编译，利用您 CPU 的多个核心 (${CPU_NUMBER} 是 ServBay 环境设置的 CPU 核心数)，从而显著加快编译速度。
make install: 将编译生成的文件（包括 PostGIS 共享库文件、SQL 脚本等）复制到 ServBay 中 PostgreSQL 15.7 的安装目录下的相应位置（通常是 lib/postgresql 和 share/postgresql/extension 等子目录）。

步骤 5：验证模块加载

编译和安装完成后，您需要在 PostgreSQL 数据库中启用 postgis 扩展。通过 ServBay 提供的命令行或您首选的 PostgreSQL 客户端连接到您的数据库，并执行以下 SQL 命令。

使用 ServBay 环境中的 psql 命令行工具进行验证：请确保您已经在 ServBay 的终端会话中，以便正确加载 ServBay 的环境变量。

bash

# 执行 CREATE EXTENSION 命令启用 PostGIS
${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/psql -c "CREATE EXTENSION postgis;"

如果执行成功，说明 PostGIS 扩展已成功创建。您可以进一步验证其版本信息：

bash

# 查询 PostGIS 版本
${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/psql -c "SELECT PostGIS_Version();"

如果一切顺利，您应该会看到 PostGIS 的版本号输出，表明模块已成功编译、安装并在数据库中加载。

编译 pg_jieba 模块

pg_jieba 是一个基于 C++ 库 cppjieba 的 PostgreSQL 扩展，用于在 PostgreSQL 中实现中文分词功能，常用于全文搜索等场景。pg_jieba 使用 CMake 作为其构建系统。以下是编译 pg_jieba 模块的步骤：

步骤 1：获取源码

首先，从 GitHub 克隆 pg_jieba 模块的源码库。pg_jieba 依赖于 cppjieba 作为 Git 子模块，因此还需要初始化并更新子模块。

bash

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

git clone ...: 克隆 pg_jieba 的 Git 仓库到当前目录。
git submodule update --init --recursive: 初始化并更新仓库中的所有 Git 子模块。pg_jieba 将 cppjieba 作为子模块包含，这一步确保 cppjieba 源码也被下载到 pg_jieba 源码目录下的正确位置。

步骤 2：配置编译选项 (CMake)

pg_jieba 使用 CMake 构建系统。与 Autotools 的 ./configure 类似，CMake 通过 cmake 命令进行配置，生成特定平台的构建文件（如 Unix Makefiles 或 Ninja）。我们需要指定 PostgreSQL 的安装路径以及 ServBay 环境相关的编译目标。

bash

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: 运行 CMake 配置。-S . 指定源码目录为当前目录，-B builddir 指定在当前目录下创建一个名为 builddir 的子目录作为构建目录。在单独的构建目录中进行编译是 CMake 的推荐做法，可以保持源码目录清洁。
-DCMAKE_PREFIX_PATH: 关键选项，告诉 CMake 在指定的路径中查找依赖库和头文件，特别是 PostgreSQL。这里指向 ServBay 中 PostgreSQL 15.7 的安装根目录。CMake 会在这个路径下的 lib/cmake、share/cmake 等子目录查找配置信息，并结合 pg_config 提供的信息来确定 PostgreSQL 的依赖路径。
-DCMAKE_OSX_DEPLOYMENT_TARGET: 指定 macOS 部署目标版本，确保编译出的二进制文件兼容特定或更高版本的 macOS。${BUILD_OS_MIN_VERSION} 是 ServBay 编译环境设置的最小兼容 macOS 版本。
-DCMAKE_OSX_ARCHITECTURES: 指定要构建的 CPU 架构（如 x86_64 或 arm64）。${BUILD_CPU_ARCH_CMAKE} 是 ServBay 编译环境设置的当前 CPU 架构。这些 macOS 特定的选项确保模块在 ServBay 运行的 macOS 系统上兼容。

步骤 3：编译和安装 (CMake)

配置成功后，使用 cmake --build 命令编译，然后使用 cmake --install 命令进行安装。

bash

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

cmake --build builddir: 在指定的构建目录 builddir 中启动编译过程。
-j ${CPU_NUMBER}: 同样指定并行编译，利用多核 CPU 加速 (${CPU_NUMBER} 来自 ServBay 环境)。
cmake --install builddir: 将编译好的文件安装到之前由 -DCMAKE_PREFIX_PATH（结合 CMake 内部逻辑和 PostgreSQL pg_config 提供的信息）所确定的 ServBay PostgreSQL 安装目录下的正确位置（通常是 lib/postgresql 和 share/postgresql/extension 等子目录）。

步骤 4：验证模块加载

编译和安装完成后，您同样需要在 PostgreSQL 数据库中启用 pg_jieba 扩展。连接到数据库并执行 SQL 命令。

使用 ServBay 环境中的 psql 命令行工具进行验证：确保您已经在 ServBay 的终端会话中。

bash

# 执行 CREATE EXTENSION 命令启用 pg_jieba
${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/psql -c "CREATE EXTENSION pg_jieba;"

如果执行成功，说明 pg_jieba 扩展已成功创建。您可以查询 pg_available_extensions 视图来确认模块信息：

bash

# 查询已安装的扩展列表
${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/psql -c "SELECT * FROM pg_available_extensions WHERE name = 'pg_jieba';"

如果模块已成功加载并在视图中列出，说明编译、安装和启用过程顺利完成。

常见问题 (FAQ)

编译失败，提示找不到头文件或库文件？
- 请检查您是否正确初始化了 ServBay 的编译环境。确保在 ServBay 终端中运行了环境初始化脚本，并且所有相关的环境变量（如 $CFLAGS, $LDFLAGS, ${SERVBAY_COMMON_INCLUDE_PATH}, ${SERVBAY_COMMON_LIB_PATH} 等）已设置并指向正确的 ServBay 路径。
- 检查配置命令中 --with-pgconfig (Autotools) 或 -DCMAKE_PREFIX_PATH (CMake) 指定的 PostgreSQL 版本路径是否正确，并且该路径下的 pg_config 文件确实存在且可执行。
- 某些模块可能有 ServBay 通用库之外的额外系统依赖（例如 PostGIS 在启用 Raster/Topology 支持时需要 GEOS, GDAL 等库）。虽然 ServBay 的编译环境包含了一些常用库，但如果缺少特定依赖，您可能需要手动安装这些依赖或调整编译选项以禁用依赖的功能。
CREATE EXTENSION 失败，提示找不到模块文件？
- 确认 make install (Autotools) 或 cmake --install (CMake) 命令是否成功执行，没有报错。检查安装日志以确认文件是否被复制到正确位置。
- 确认 --prefix (Autotools) 或 -DCMAKE_PREFIX_PATH (CMake) 在配置阶段指定的安装路径是否正确指向了您希望安装模块的 ServBay PostgreSQL 版本目录。模块文件通常会被安装到该路径下的 lib/postgresql 子目录中。
- 尝试重启 PostgreSQL 服务。有时数据库需要重启才能识别新安装的模块文件。您可以通过 ServBay 应用界面方便地重启 PostgreSQL 软件包。
- 检查 PostgreSQL 的 shared_preload_libraries 配置。对于大多数普通扩展 (CREATE EXTENSION 方式加载)，不需要修改此配置，但对于某些特殊类型的模块（例如需要钩子到 PostgreSQL 内部的模块），可能需要将模块名添加到 shared_preload_libraries 中并在启动时加载。请查阅您尝试编译的模块的具体文档。
如何为不同版本的 PostgreSQL 编译模块？
- 重复上述编译步骤，但在配置阶段（./configure 或 cmake）务必将 --with-pgconfig (Autotools) 或 -DCMAKE_PREFIX_PATH (CMake) 参数指向目标 PostgreSQL 版本的 pg_config 路径。例如，如果您想为 ServBay 中安装的 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 14 的具体版本号)。

总结

通过遵循上述步骤，并充分利用 ServBay 提供的编译环境和工具，您可以在 ServBay 本地开发环境中成功编译和安装所需的 PostgreSQL 模块，从而扩展您的数据库功能，满足特定的开发需求。在整个过程中，正确初始化 ServBay 编译环境、指定目标 PostgreSQL 版本以及仔细检查编译配置和安装路径是确保成功的关键。

希望本文能帮助您顺利地在 ServBay 中定制您的 PostgreSQL 环境。如果您遇到其他问题，可以查阅 ServBay 的其他文档或社区资源。

如何在 ServBay 中编译 PostgreSQL 模块 ​

概述 ​

前提条件 ​

指定 PostgreSQL 版本的重要性 ​

编译 postgis 模块 ​

步骤 1：下载源码 ​

步骤 2：解压源码包 ​

步骤 3：配置编译选项 ​

步骤 4：编译和安装 ​

步骤 5：验证模块加载 ​

编译 pg_jieba 模块 ​

步骤 1：获取源码 ​

步骤 2：配置编译选项 (CMake) ​

步骤 3：编译和安装 (CMake) ​

步骤 4：验证模块加载 ​

常见问题 (FAQ) ​

总结 ​

如何在 ServBay 中编译 PostgreSQL 模块

概述

前提条件

指定 PostgreSQL 版本的重要性

编译 postgis 模块

步骤 1：下载源码

步骤 2：解压源码包

步骤 3：配置编译选项

步骤 4：编译和安装

步骤 5：验证模块加载

编译 pg_jieba 模块

步骤 1：获取源码

步骤 2：配置编译选项 (CMake)

步骤 3：编译和安装 (CMake)

步骤 4：验证模块加载

常见问题 (FAQ)

总结