pgrust 命令行速查手册：从启动到关闭的常用命令大全

pgrust 命令行速查手册：从启动到关闭的常用命令大全

【免费下载链接】pgrustPostgres rewritten in Rust, now faster than Postgres and Clickhouse项目地址: https://gitcode.com/GitHub_Trending/pg/pgrust

如果你正在寻找一份pgrust 命令行速查手册，这篇教程就是为你准备的。pgrust 是一个用 Rust 重写 PostgreSQL 18.3 的开源项目，它完全兼容 PostgreSQL 的数据目录格式，已经通过超过 4.6 万条回归测试。本文将从初始化数据目录、启动服务、连接数据库，到关闭与回归测试，带你梳理 pgrust 从启动到关闭的常用命令全集，新手也能照着一步步操作。

pgrust 是什么？一分钟了解这个 Rust 版 PostgreSQL

pgrust（Postgres in Rust）的核心目标不是简单翻译代码，而是让 PostgreSQL 更容易从内部被改造：保持行为与 PostgreSQL 一致，以真实 PostgreSQL 测试为基准，借助 Rust 语言和 AI 辅助编程探索更深层的服务器改造。

它有几个非常吸引人的特性：

• 🎯 兼容 PostgreSQL 18.3，磁盘格式兼容，可以直接启动已有的 PostgreSQL 18.3 数据目录
• 🧪 通过 46,000+ 条回归测试，输出与 PostgreSQL 保持一致
• ⚡ 新版本采用"每连接一线程"模型替代"每连接一进程"，事务负载比 PostgreSQL 快 50%，分析型负载快约 300 倍
• 🦀 全部代码为 Rust 编写，更安全、更易维护

⚠️ 注意：pgrust 目前尚未达到生产就绪状态，性能也还在优化中，适合学习、实验和早期尝鲜。

pgrust 环境准备：三种方式快速获得可执行文件

在使用 pgrust 命令行之前，需要先拿到postgres可执行文件。这里有三种方式：

方式一：Docker 一键启动（最简单）

对于只想快速体验的普通用户，Docker 是最省事的选择：

docker run -d --name pgrust -e POSTGRES_PASSWORD=secret malisper/pgrust:v0.1

等待就绪后，进入容器内的 psql 客户端：

docker exec -it -e PGPASSWORD=secret pgrust psql -h 127.0.0.1 -U postgres

用完可以删除容器：

docker rm -f pgrust

Docker 镜像的启动逻辑封装在 docker/entrypoint.sh 中，它会自动完成初始化、临时服务器启动与最终服务器拉起，并注入 pgrust 特有的 GUC 参数（io_method=sync、max_stack_depth=60000等）。

方式二：源码编译（推荐进阶用户）

pgrust 使用 Cargo 作为构建工具，整个项目是一个大型 Rust workspace，入口二进制在 crates/backend/main/ 下。先克隆仓库：

git clone https://gitcode.com/GitHub_Trending/pg/pgrust cd pgrust

Ubuntu/Debian 系统先安装依赖：

sudo apt-get update sudo apt-get install -y build-essential pkg-config libicu-dev libssl-dev libldap2-dev libpam0g-dev postgresql-client-18

然后编译 release 版本：

PGRUST_PGSHAREDIR="$PWD/vendor/postgres-18.3/share" \ cargo build --release --locked --bin postgres

编译产物位于target/release/postgres。

方式三：浏览器在线体验

pgrust 官方还提供 WebAssembly 浏览器演示，无需安装任何东西即可在线体验，适合先"看看效果"再动手。

pgrust 初始化命令：--initdb 参数详解（建库第一步）

pgrust 的 initdb 不是独立的二进制，而是内嵌在postgres主程序里，通过--initdb参数触发（源码见 crates/backend/main/main_main/src/lib.rs 中的早期分发逻辑）。

最快初始化方法

target/release/postgres --initdb \ -D /tmp/pgrust-data \ -L "$PWD/vendor/postgres-18.3/share" \ --no-locale \ --encoding UTF8 \ -U postgres

initdb 常用参数速查

这些参数由 crates/backend/main/initdb/src/lib.rs 中的参数解析器处理，它会创建完整的目录树（base、pg_wal、pg_xact等）、写入PG_VERSION文件，并从 share 目录拷贝postgresql.conf、pg_hba.conf等配置文件。

💡 小贴士：--initdb会用同一二进制重新执行--boot（引导模式建目录）和--single（单用户模式跑初始化 SQL），完整复刻了 C 版 initdb 的流程。

pgrust 启动命令：postgres 服务启动参数全解

初始化完成后，就可以启动 pgrust 服务了。注意两个前置要求：栈大小限制和Rust 线程栈大小，这是 pgrust 特有的启动要求。

标准启动命令

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

参数含义：

• ulimit -s 65520：调大 C 栈限制（pgrust 每语句帧较大，默认栈会拒绝启动）
• RUST_MIN_STACK=33554432：设置 Rust 线程最小栈为 32MB
• -D：数据目录
• -F：关闭 fsync（开发调试常用）
• -c listen_addresses=：仅监听本地 Unix socket，不开放 TCP
• -k /tmp：Unix socket 目录
• -p 5432：监听端口
• -c io_method=sync：pgrust 专用 GUC，指定同步 IO 方式
• -c max_stack_depth=60000：pgrust 专用 GUC，配合大栈限制

postgres 服务端全部参数（--help 输出）

pgrust 完整移植了 PostgreSQL 服务端的命令行选项，定义在 crates/backend/main/main_main/src/help.rs 中，运行时用postgres --help即可查看：

此外还有开发者选项（-f、-O、-P、-t、-T、-W）和单用户模式选项（--single、-E、-j、-r），完整列表直接运行--help即可看到。

pgrust 连接命令：psql 客户端登录与验证

pgrust 目前没有自己的 psql 客户端，需要借助 PostgreSQL 18 的 psql 连接。启动服务后，在另一个终端执行：

psql -h /tmp -p 5432 -U postgres -d postgres \ -c "select version(), 1 + 1 as two"

• -h /tmp：指定 Unix socket 目录（对应启动时的-k /tmp）
• -p 5432：端口
• -U postgres：用户名（对应 initdb 时的-U postgres）
• -d postgres：数据库名

看到version()输出为 PostgreSQL 18.3 且1 + 1返回 2，说明 pgrust 服务已正常对外提供 SQL 能力。🎉

pgrust 常用运维命令：版本、配置与帮助查询

日常运维中，以下"只读"命令非常实用，它们不需要完整启动服务：

查看版本

target/release/postgres --version # 输出: postgres (PostgreSQL) 18.3

查看帮助

target/release/postgres --help

打印某个配置项的值

target/release/postgres -C max_stack_depth

输出全部配置参数

target/release/postgres --describe-config

🛡️ 安全提示：以上只读命令（-C、--describe-config）即使在 root 权限下也允许执行；但正常的服务启动和 initdb 会拒绝以 root 运行，这是 PostgreSQL 一贯的安全策略。

pgrust 关闭命令：优雅停止服务

pgrust 的关闭方式与 PostgreSQL 一致，主要有两种：

方式一：前台 Ctrl+C 或发送 SIGINT

如果你是用前台方式启动的服务，直接Ctrl+C即可触发优雅关闭（fast shutdown）。Docker 镜像也采用 SIGINT 作为停止信号，docker stop会优雅关停。

方式二：kill 信号

# 优雅关闭（fast shutdown），等待事务完成 kill -INT $(pgrep -f "target/release/postgres") # 立即关闭（immediate shutdown），不等待 kill -QUIT $(pgrep -f "target/release/postgres")

⚠️ 注意：pgrust 尚不支持pg_ctl stop（项目没有移植 pg_ctl），关闭服务请使用信号方式或容器管理命令。

pgrust 回归测试命令：跑通 4.6 万条 SQL 测试

pgrust 的一大亮点是自带回归测试体系。脚本 scripts/run-regression 会拉起一个 pgrust 实例，用仓库内置的 PostgreSQL 18.3 测试文件跑完整回归套件：

PGRUST_BIN="$PWD/target/release/postgres" \ scripts/run-regression

常用环境变量：

• PGRUST_BIN：指定 pgrust 的 postgres 二进制（默认target/release/postgres）
• PGRUST_PSQL：指定 psql 客户端路径（默认自动探测 PATH）
• PGPORT：测试端口（默认 55434）
• OUTDIR：输出目录

也可以只跑指定测试：

scripts/run-regression select

仓库还提供了其他测试脚本，如 scripts/run-pg-regress、scripts/run-pg-isolation、scripts/run-auth-tap 等，覆盖回归、隔离、认证等多个维度。

pgrust 命令速查表：从启动到关闭一张图搞定

常见问题 FAQ

Q1：pgrust 和 PostgreSQL 是什么关系？pgrust 是用 Rust 重写的 PostgreSQL 18.3，保持磁盘格式和行为兼容，可以直接使用 PostgreSQL 的数据目录与 psql 客户端。

Q2：pgrust 能直接启动 PostgreSQL 已有的数据目录吗？可以！这正是 pgrust 的设计目标之一——磁盘兼容，能直接从现有 PostgreSQL 18.3 数据目录启动。

Q3：为什么启动时报栈相关的错误？pgrust 需要较大的栈空间，请务必先执行ulimit -s 65520并设置RUST_MIN_STACK=33554432，否则可能拒绝启动。

Q4：pgrust 支持 pg_ctl 吗？目前不支持。关闭服务请使用信号方式（SIGINT/SIGQUIT）或容器管理命令。

Q5：pgrust 生产环境可用吗？官方明确说明尚未生产就绪，扩展（如 PL/Python、PL/Perl）兼容性有限，建议用于学习和实验。

总结

这份 pgrust 命令行速查手册涵盖了从--initdb初始化、postgres启动、psql连接，到版本查询、配置查看、优雅关闭和回归测试的完整命令链。核心代码位于 crates/backend/main/ 目录，Docker 封装在 docker/entrypoint.sh，测试脚本集中在 scripts/ 下。收藏这份速查表，你就能快速上手这个"比 PostgreSQL 更快的 Rust 数据库"了！🚀

【免费下载链接】pgrustPostgres rewritten in Rust, now faster than Postgres and Clickhouse项目地址: https://gitcode.com/GitHub_Trending/pg/pgrust