Postgres.app 命令行工具（CLI Tools）完全指南：配置 $PATH、随附工具清单与 man 手册

数据库桌面应用【免费下载链接】PostgresAppThe easiest way to get started with PostgreSQL on the Mac项目地址https://gitcode.com/gh_mirrors/po/PostgresApp点击查看免费下载Postgres.app 不仅提供了一个图形化界面用于启动/停止 PostgreSQL 服务器还在应用包内随附了整套命令行工具包括 PostgreSQL 官方客户端与服务端程序、PostGIS、PROJ.4 与 GDAL 等 GIS 工具链。本文以 docs/de/documentation/cli-tools.md 为骨架结合仓库源码深入讲解如何在 macOS 上把这些工具接入终端、随附了哪些具体工具、以及如何借助 man 手册随时查阅官方文档帮助你彻底摆脱「只在 GUI 里点按钮」的使用方式直接以psql、pg_dump、pg_ctl等命令驱动数据库。本文对应英文版文档 docs/documentation/cli-tools.md安装与卸载相关的整体说明可参见 docs/de/documentation/install.md 与 docs/documentation/install.md。为什么必须先配置$PATHPostgres.app 的二进制文件并不安装在系统标准目录如/usr/bin中而是打包在应用包内部。安装后工具的实际位置为/Applications/Postgres.app/Contents/Versions/latest/bin其中的latest是一个符号链接指向应用包内随附的最新稳定版 PostgreSQL 版本目录。这一点在源码中有明确佐证Postgres/BinaryManager.swift 中getLatestBinary()通过FileManager.destinationOfSymbolicLink(atPath:)解析Contents/Versions/latest这个符号链接的目标从而得到当前最新的二进制版本Postgres/CopyBinaries.sh 则在构建阶段用ln -sfh ${LATEST_STABLE_PG_VERSION} latest创建该链接。因此若你在终端里直接输入psql系统默认找不到这个命令。要让它可用就必须把上述bin目录加入 shell 的$PATH环境变量——这正是文档给出的第一步。配置$PATH的两种官方推荐方式方式一通过/etc/paths.d推荐无需手改 shell 配置文件在 macOS 上登录 shell 启动时会把/etc/paths.d/目录下每个文件中的路径追加到$PATH。文档给出的最简命令如下sudo mkdir -p /etc/paths.d echo /Applications/Postgres.app/Contents/Versions/latest/bin | sudo tee /etc/paths.d/postgresapp这条命令干了三件事sudo mkdir -p /etc/paths.d确保/etc/paths.d目录存在macOS 默认已存在重复执行也不会报错echo ...把二进制目录路径输出sudo tee /etc/paths.d/postgresapp将路径写入名为postgresapp的配置文件需要管理员权限故加sudo。重要注意事项$PATH只在新的终端会话启动时重新读取。因此执行完上述命令后必须关闭当前终端窗口并重新打开新路径才会生效。如果需要撤销这一配置例如卸载 Postgres.app 时删除该文件即可sudo rm /etc/paths.d/postgresapp此清理步骤同样记录在 docs/de/documentation/install.md 的卸载小节中。方式二直接编辑 shell 配置文件如果你更习惯传统做法也可以在自己的 shell 配置文件中追加一行。文档明确指出「你当然也可以直接在你的.profile中配置」。例如# 追加到 ~/.profile或 ~/.zshrc / ~/.bash_profile取决于你使用的 shell export PATH/Applications/Postgres.app/Contents/Versions/latest/bin:$PATH修改后同样需要重新打开终端或执行source ~/.profile使其生效。验证配置是否正确无论使用哪种方式文档给出的验证方法都是执行which psql如果输出类似/Applications/Postgres.app/Contents/Versions/latest/bin/psql说明配置成功如果输出psql not found请检查是否已重开终端、路径文件内容是否正确。你也可以用psql --version进一步确认版本号。提示latest/bin路径中之所以能长期保持不变是因为每次升级 Postgres.app 后latest符号链接都会指向新版本目录详见 Postgres/BinaryManager.swift 对Contents/Versions目录的枚举逻辑——该目录下每个子目录代表一个 PostgreSQL 大版本。Postgres.app 随附的命令行工具清单配置好$PATH后你将获得一整套工具。文档按四个分组完整列出这里逐组呈现与英文文档及 README.md 的清单一致1. PostgreSQL 官方工具族这是最核心的一组覆盖了数据库管理、备份恢复、集群初始化、性能测试等全场景管理类clusterdbcreatedbcreatelangcreateuserdropdbdroplangdropuserreindexdbvacuumdbvacuumlo初始化与启动类initdbpg_ctlpostgrespostmaster备份/恢复类pg_dumppg_dumpallpg_restorepg_basebackuppg_archivecleanup配置与诊断类pg_configpg_controldatapg_test_fsyncpg_test_timing复制与升级类pg_receivexlogpg_resetxlogpg_standbypg_upgrade交互与开发类psqlecpgoid2name性能压测类pgbench其中若干工具的典型用途工具典型用途psqlPostgreSQL 交互式终端执行 SQL 与脚本createdb/dropdb创建 / 删除数据库createuser/dropuser创建 / 删除数据库角色用户pg_dump/pg_restore单库逻辑备份与恢复pg_dumpall全实例所有库 全局对象备份pg_ctl手动启动、停止、重启服务器initdb初始化数据库集群数据目录pg_config查看编译配置如--bindir、--versionpgbench内置基准测试工具2. PROJ.4 坐标转换工具用于地理坐标参考系统CRS的转换与投影cs2csgeodinvgeodinvprojnad2binproj3. GDAL 栅格/矢量地理数据处理工具GDAL 是处理栅格与矢量地理数据的事实标准Postgres.app 随附了其绝大多数命令行工具栅格处理gdal_contourgdal_gridgdal_rasterizegdal_translategdaladdogdalbuildvrtgdaldemgdalenhancegdalinfogdallocationinfogdalmanagegdalservergdalsrsinfogdaltindexgdaltransformgdalwarpnearblack矢量处理ogr2ogrogrinfoogrtindex其他testepsg4. PostGIS 空间数据导入导出工具PostGIS 扩展配套的三个核心工具pgsql2shp从 PostGIS 表导出 Shapefileshp2pgsql将 Shapefile 导入 PostgreSQL/PostGISraster2pgsql将栅格数据如 GeoTIFF导入 PostGIS 栅格表从源码看这些工具是如何打包进应用的这些工具并不是写在文档里的「宣传清单」而是由构建脚本实际解压进应用包的。在 Postgres/CopyBinaries.sh 中可以看到构建阶段从${PG_BINARIES_DIR}/${VERSION}.zip逐个解压出clusterdb、createdb、pg_*系列、psql、reindexdb、vacuumdb等核心工具以及cs2cs、geod、gdal*、ogr*、pgsql2shp、raster2pgsql、shp2pgsql等 GIS 工具链随后再解压动态库lib/*.dylib、lib/postgresql/*、静态库、头文件include/*与共享文件share/*。该脚本还顺带揭示了版本差异细节例如createlang/droplang在 PostgreSQL 10 中被移除脚本中以|| true容忍缺失postmaster在 PostgreSQL 16 中被移除pg_receivexlog/pg_resetxlog在较新版本中更名为pg_receivewal/pg_resetwal文档清单基于较早期版本README 也注明「this list may be outdated」因此实际可用工具以你安装的版本为准。数据目录与其他关键路径了解 CLI 工具后你还会经常接触到下列目录见 docs/de/documentation/install.md 的「Wichtige Verzeichnisse」小节用途路径可执行文件binaries/Applications/Postgres.app/Contents/Versions/latest/bin头文件用于编译扩展/Applications/Postgres.app/Contents/Versions/latest/include库文件/Applications/Postgres.app/Contents/Versions/latest/lib默认数据目录~/Library/Application Support/Postgres/var-XXXX 为 PostgreSQL 大版本号Postgres.app 的服务器进程以你的 macOS 用户身份运行而不是像其他发行版那样创建独立的postgres系统用户——这一设计在 README.md 中有明确说明。首次启动时应用会自动完成四步初始化对应 Postgres/Server.swift 中initDatabaseSync、startSync、createUserSync、createUserDatabaseSync的实现# 1. 初始化数据集群PostgreSQL 15 额外启用 ICU locale 与 data checksums initdb -D DATA_DIRECTORY -U postgres --encodingUTF-8 --localeen_US.UTF-8 # 2. 启动服务器 pg_ctl start -D DATA_DIRECTORY -w -l DATA_DIRECTORY/postgresql.log -o -p 5432 # 3. 创建与系统用户名同名的超级用户 createuser -U postgres -p 5432 --superuser USERNAME # 4. 创建与系统用户名同名的数据库 createdb -p 5432 USERNAME默认情况下服务器监听本机 5432 端口采用trust认证即无需密码。因此配置好$PATH后你可以直接这样连接# 连接默认的、与用户名同名的数据库 psql # 连接 postgres 库 psql -d postgres实战示例用命令行工具完成日常操作以下命令都基于「已配置$PATH」的前提默认连接本机 5432 端口的默认集群# 创建 / 删除数据库 createdb myapp_dev dropdb myapp_dev # 创建带密码的登录角色配合 scram-sha-256 认证 createuser -P -p 5432 myapp_user # 备份单个数据库到文件 pg_dump myapp_dev myapp_dev.sql # 从备份恢复 createdb myapp_dev_new psql -d myapp_dev_new -f myapp_dev.sql # 使用 psql 执行 SQL 脚本 psql -d myapp_dev -f schema.sql # 手动控制服务器等价于在 GUI 中点击 Start/Stop pg_ctl -D ~/Library/Application\ Support/Postgres/var-17 -l ~/Library/Application\ Support/Postgres/var-17/postgresql.log start pg_ctl -D ~/Library/Application\ Support/Postgres/var-17 stop # 查看编译信息 pg_config --version pg_config --bindir配合前面工具清单中提到的 GIS 工具你还能完成空间数据的导入导出例如# 将 Shapefile 导入 PostGIS 数据库 shp2pgsql -s 4326 my_places.shp public.places | psql -d myapp_dev服务器实际启动/停止时所用的底层命令可在 Postgres/Server.swiftpg_ctl start -D ... -w -l log -o -p port与 Postgres/Server.swiftpg_ctl stop -m f -D ... -w中看到与你手动执行完全一致。man 手册随时查阅官方文档Postgres.app 随附了完整的 man 手册页。只要按上文配置好$PATHman 工具同样通过该路径找到文档所在位置就可以直接查阅官方手册man psql man pg_dump man initdb man pg_ctl文档明确指出例如执行man psql即可随时阅读官方说明——这相当于把 PostgreSQL 官方文档的「命令参考」部分离线安装到了你的 Mac 上。补充从 GUI 一键打开 psql 终端除了手动配置$PATH后自行打开终端Postgres.app 的图形界面本身也内置了「在终端打开 psql」的能力。从源码看Postgres/ClientLauncher.swift 的launchClient会直接以server.binPath/psql -pport [-U user] [database]的形式构造命令并支持通过 AppleScript 在 Terminal、iTerm2 中执行或为 Ghostty、Hyper、Kitty、WezTerm、Warp 等不支持 AppleScript 的终端生成临时.command脚本执行对应入口见 Postgres/ConnectionDialog.swift 与 Postgres/ServerView.swift。这意味着即使你没有配置$PATH也可以从 GUI 里体验psql——但要在任意终端会话中自由调用全部工具配置$PATH仍是第一步。小结要点结论核心配置将/Applications/Postgres.app/Contents/Versions/latest/bin写入/etc/paths.d/postgresapp或~/.profile生效时机必须重开终端窗口$PATH才会重新加载验证命令which psql工具范围PostgreSQL 全套官方工具 PROJ.4 GDAL PostGIS官方手册配置好路径后直接man psql等即可离线查阅卸载清理sudo rm /etc/paths.d/postgresapp可选按照本文步骤操作你就能让 Postgres.app 从「一个图形化数据库管理器」升级为「一整套开箱即用的 PostgreSQL 开发环境」在任何终端中自由组合psql、pg_dump、pg_ctl、shp2pgsql等工具完成从建库、备份、运维到空间数据分析的完整工作流。赞分享数据库桌面应用【免费下载链接】PostgresAppThe easiest way to get started with PostgreSQL on the Mac项目地址https://gitcode.com/gh_mirrors/po/PostgresApp点击查看免费下载相关推荐10分钟掌握分布式ID生成IdGen完全指南10分钟掌握分布式ID生成IdGen完全指南 你是否在构建分布式系统时遇到过数据库ID冲突的困扰或者因为UUID无序导致的索引碎片化而头疼作为.NET开发Stylelint 命令行工具(CLI)完全指南Stylelint 命令行工具 CLI 完全指南 Stylelint 作为一款强大的 CSS 样式检查工具其命令行接口 CLI 提供了丰富的功能选项能够满足代码质量静态分析前端NexaSDK命令行工具(CLI)完全指南NexaSDK命令行工具 CLI 完全指南 前言 NexaSDK是一个功能强大的AI模型工具包其命令行界面 CLI 为用户提供了便捷的模型管理、推理和转换功能人工智能大模型推理引擎本地部署多模态上一篇华为设备解锁终极指南PotatoNV让麒麟芯片设备重获自由下一篇如何快速掌握Detect It Easy文件类型识别的终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考