从源码编译 pgrust：macOS 环境完整构建教程（附依赖配置）
项目地址: https://gitcode.com/GitHub_Trending/pg/pgrust 为什么要在 macOS 上从源码编译 pgrust？
pgrust 是一个用 Rust 重写 PostgreSQL 的开源项目，目标是保持与 Postgres 18.3 的磁盘兼容，并已通过超过 46,000 条回归查询的验证。对于开发者而言，在 macOS 上从源码编译 pgrust，既能亲身体验 Rust 数据库内核的构建过程，也能为后续二次开发、调试打基础。本文提供一份完整的 macOS 源码编译教程，涵盖依赖安装、环境变量配置、编译、初始化数据目录和启动服务的全部步骤。
pgrust 源码编译前置准备：环境要求一览
在开始编译前，请确认你的 macOS 满足以下条件：
- macOS 版本：Intel 或 Apple Silicon（M1/M2/M3）均可
- Rust 工具链：建议使用最新稳定版（通过
rustup安装） - Homebrew：用于安装 ICU、OpenSSL 等原生依赖
- 磁盘空间：建议预留 10GB 以上（依赖 + 编译产物）
- 网络：需要访问 crates.io 拉取 Rust 依赖
第一步：获取 pgrust 源码
首先将仓库克隆到本地：
git clone https://gitcode.com/GitHub_Trending/pg/pgrust
cd pgrust
仓库结构清晰，核心源码位于 crates/ 目录下，其中 crates/backend/ 存放数据库后端实现，crates/_support/types/ 存放各类类型定义。完整的构建与运行说明可以参考项目根目录的 README.md，其中 "Build From Source" 一节即官方 macOS 构建指引。
第二步：安装 macOS 编译依赖
pgrust 依赖 ICU（字符集支持）、OpenSSL 3（加密通信）和 libpq（psql 客户端）。执行以下命令一键安装：
brew install icu4c openssl@3 libpq
其中：
- icu4c：提供 Unicode 与字符集支持
- openssl@3：SSL/TLS 加密支持
- libpq：PostgreSQL 客户端库，包含 psql 工具
提示：Homebrew 默认不把 openssl@3 和 icu4c 加入 PATH，需要手动配置环境变量，见下一步。
第三步：配置编译所需环境变量（关键步骤）
这是 macOS 编译最容易踩坑的地方。openssl@3 和 icu4c 属于 keg-only 安装，必须手动将库路径导出，否则 pkg-config 无法找到依赖：
export LIBRARY_PATH="$(brew --prefix openssl@3)/lib:${LIBRARY_PATH:-}"
export PKG_CONFIG_PATH="$(brew --prefix openssl@3)/lib/pkgconfig:$(brew --prefix icu4c)/lib/pkgconfig:${PKG_CONFIG_PATH:-}"
export PATH="$(brew --prefix libpq)/bin:$PATH"
配置完成后，建议将其写入 ~/.zshrc（zsh 用户）以便后续复用。验证配置是否生效：
brew --prefix openssl@3
pkg-config --modversion icu-uc
第四步：执行 pgrust 源码编译
pgrust 使用 Cargo workspace 管理依赖（成员列表见 Cargo.toml）。编译时需要通过 PGRUST_PGSHAREDIR 指定 vendored 的 Postgres 18.3 共享文件目录——仓库的 vendor/postgres-18.3/share 中已包含 postgres.bki、system_views.sql 等初始化所需文件：
PGRUST_PGSHAREDIR="$PWD/vendor/postgres-18.3/share" \
cargo build --release --locked --bin postgres
编译选项说明：
--release：启用优化，编译时间较长但性能最佳--locked：严格按照 Cargo.lock 锁定依赖版本，保证可复现--bin postgres：只构建 postgres 可执行文件
编译完成后，产物位于 target/release/postgres。首次编译可能耗时 10~30 分钟，请耐心等待。
第五步：初始化 pgrust 数据目录
pgrust 内置了 --initdb 命令（忠实移植自 C 版 initdb.c），用它创建数据目录：
target/release/postgres --initdb \
-D /tmp/pgrust-data \
-L "$PWD/vendor/postgres-18.3/share" \
--no-locale \
--encoding UTF8 \
-U postgres
-D：指定数据目录位置-L：指定共享文件目录（需与编译时的PGRUST_PGSHAREDIR一致）--no-locale、--encoding UTF8：规避区域设置问题-U postgres：超级用户名
第六步：启动 pgrust 数据库服务
启动前需要调整栈大小限制，并设置 Rust 线程最小栈（pgrust 在解析复杂 SQL 时可能深度递归，默认栈不够用）：
ulimit -s 65520
RUST_MIN_STACK=33554432 target/release/postgres \
-D /tmp/pgrust-data \
-F \
-c listen_addresses= \
-k /tmp \
-p 5432 \
-c io_method=sync \
-c max_stack_depth=60000
-F：前台运行，方便观察日志-c listen_addresses=：仅监听 Unix socket-k /tmp：socket 目录-c io_method=sync：同步 I/O 模式-c max_stack_depth=60000：与栈大小匹配
第七步：连接并验证 pgrust 运行
另开一个终端，用 psql 连接测试：
psql -h /tmp -p 5432 -U postgres -d postgres \
-c "select version(), 1 + 1 as two"
如果看到 version 返回 Postgres 18.3 兼容版本、two 为 2，说明 pgrust 已成功运行。
补充：运行 pgrust 回归测试
pgrust 的最大亮点之一是通过了超过 46,000 条 Postgres 回归查询。编译完成后可运行回归测试验证：
PGRUST_BIN="$PWD/target/release/postgres" \
scripts/run-regression
该脚本（scripts/run-regression）仅依赖 pgrust 自身二进制和 vendored 的 PG 18.3 测试文件，psql 客户端是唯一外部依赖（可用 PGRUST_PSQL 指定路径）。若想快速了解 Docker 方式构建，可参考 docker/README.md。
常见问题与排查技巧
Q1：编译时报找不到 openssl 头文件？ 检查 PKG_CONFIG_PATH 是否包含 $(brew --prefix openssl@3)/lib/pkgconfig。
Q2：启动时报 max_stack_depth 相关错误？ 确认已执行 ulimit -s 65520，且 max_stack_depth 设为 60000、RUST_MIN_STACK 已导出。
Q3：initdb 报找不到 share 文件？ 确认 -L 指向 vendor/postgres-18.3/share，且该目录包含 postgres.bki 等文件。
Q4：端口被占用？ 修改 -p 参数使用其他端口，或先执行 lsof -i :5432 查看占用进程。
总结
至此，你已经在 macOS 上完成了 pgrust 从源码编译、初始化、启动到连接验证的完整流程。pgrust 作为 Rust 重写 Postgres 的代表项目，其编译过程本身也是一次对数据库内核构建体系的学习。接下来可以尝试运行回归测试、阅读 crates/backend/ 源码，甚至参与贡献，体验 Rust 数据库开发的乐趣。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
