PHP小码农

Appearance

macOS 安装（Homebrew） ​

macOS 上安装 PostgreSQL 最便捷的方式是使用 Homebrew，它会把 PostgreSQL 的二进制文件、数据目录与后台服务统一纳入包管理。本节介绍 brew install postgresql@18 的完整流程、服务启停、PATH 配置、数据目录位置，并给出 Postgres.app 这一备选方案。

前置知识

阅读本节前，建议先了解：Linux 安装（APT / YUM）

基础概念 ​

  • Homebrew：macOS 上的包管理器，把软件安装到独立的「前缀目录」（Intel Mac 为 /usr/local，Apple Silicon 为 /opt/homebrew）
  • 公式（Formula）：Homebrew 中的一个软件包定义，如 postgresql@18
  • 服务（Service）：通过 brew services 管理的后台进程，底层由 launchd 托管
  • 数据目录（Data Directory）：Homebrew 默认放在 /opt/homebrew/var/postgresql@18（Apple Silicon）或 /usr/local/var/postgresql@18（Intel）
  • 本地开发 vs 生产：macOS 通常只作为开发环境，生产环境应使用 Linux
安装方式版本可控性数据目录适用场景
Homebrew好（可指定 @16/@17/@18）前缀目录下的 var/开发、CI
Postgres.app一般（跟应用版本走）应用内 Data 目录图形化偏好者
Docker最好由 Volume 控制需要与生产一致
源码编译最好自定义需特殊编译选项

版本说明

Homebrew 的 postgresql@18 公式跟随上游发布。若只想安装最新稳定大版本，也可以直接 brew install postgresql，它会被链接到当前的最新稳定版。

安装与配置 ​

安装 Homebrew ​

bash
# 检查是否已安装
brew --version
text
Homebrew 4.5.0
bash
# 未安装时执行官方安装脚本（需要网络与管理员密码）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Apple Silicon 上需要把 brew 加入 PATH
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

安装 PostgreSQL 18 ​

bash
# 更新公式索引（不要跳过，否则可能找不到 @18）
brew update

# 查看当前可安装的 PostgreSQL 版本
brew search postgresql
text
==> Formulae
postgresql@14   postgresql@15   postgresql@16   postgresql@17   postgresql@18
postgresql ✔    postgresql@17 ✔
bash
# 安装 PostgreSQL 18
brew install postgresql@18

# Homebrew 对 @ 版本公式默认 keg-only，需要手动加入 PATH
echo 'export PATH="/opt/homebrew/opt/postgresql@18/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 验证
psql --version
pg_config --bindir
text
psql (PostgreSQL) 18.0 (Homebrew)

启动与停止服务 ​

bash
# 启动并设置开机自启（推荐，等价于 brew services start）
brew services start postgresql@18
text
==> Successfully started `postgresql@18` (label: homebrew.mxcl.postgresql@18)
bash
# 仅本次运行，不设置开机自启（适合临时调试）
brew services run postgresql@18

# 查看所有服务状态
brew services list
text
Name              Status  User  File
postgresql@18     started ch    ~/Library/LaunchAgents/homebrew.mxcl.postgresql@18.plist
bash
# 停止服务（同时移除开机自启）
brew services stop postgresql@18

# 重启
brew services restart postgresql@18

# 查看为服务生成的 launchd 配置
cat ~/Library/LaunchAgents/homebrew.mxcl.postgresql@18.plist

也可以绕过 brew services，直接使用 PostgreSQL 自带的 pg_ctl：

bash
# 前台启动，日志输出到终端（便于观察启动过程）
/opt/homebrew/opt/postgresql@18/bin/postgres -D /opt/homebrew/var/postgresql@18

# 或使用 pg_ctl 后台启动
pg_ctl -D /opt/homebrew/var/postgresql@18 -l /opt/homebrew/var/log/postgresql@18.log start

路径与数据目录 ​

项目Apple SiliconIntel Mac
安装前缀/opt/homebrew/usr/local
二进制目录/opt/homebrew/opt/postgresql@18/bin/usr/local/opt/postgresql@18/bin
数据目录/opt/homebrew/var/postgresql@18/usr/local/var/postgresql@18
配置文件数据目录内的 postgresql.conf同左
服务日志/opt/homebrew/var/log/postgresql@18.log/usr/local/var/log/postgresql@18.log
bash
# 打印 Homebrew 前缀（自动适配 Intel / Apple Silicon）
echo $(brew --prefix)
echo $(brew --prefix)/var/postgresql@18

# 查看数据目录内容
ls -lh $(brew --prefix)/var/postgresql@18

详细说明 ​

首次初始化与连接 ​

Homebrew 在 brew install 阶段会自动执行 initdb（若数据目录为空），超级用户为当前登录的 macOS 用户名，而不是 postgres：

bash
# 确认数据目录是否已初始化
ls $(brew --prefix)/var/postgresql@18/PG_VERSION
text
/opt/homebrew/var/postgresql@18/PG_VERSION
bash
# 直接连接（默认数据库与用户名都等于当前系统用户）
psql postgres
text
psql (18.0 (Homebrew))
Type "help" for help.

ch=# SELECT current_user, current_database();
 current_user | current_database
--------------+------------------
 ch           | postgres
(1 row)

如果安装时数据目录已存在但为空，或安装后目录被删除，可手动初始化：

bash
# macOS 下的 Homebrew 初始化（数据目录必须为空）
initdb --locale=C -E UTF-8 $(brew --prefix)/var/postgresql@18

# 初始化完成后新建一个默认数据库（initdb 默认没有与用户同名的库）
createdb

端口与配置文件 ​

Homebrew 使用默认端口 5432，配置文件位于数据目录内：

ini
# /opt/homebrew/var/postgresql@18/postgresql.conf
# 默认仅监听回环地址，本机开发足够
listen_addresses = 'localhost'
port = 5432

# 日志相关（Homebrew 安装默认未开启 logging_collector）
logging_collector = off
ini
# /opt/homebrew/var/postgresql@18/pg_hba.conf
# Homebrew 默认对本机连接使用 trust，本地开发方便但不适合多人共享的机器
local   all             all                                     trust
host    all             all             127.0.0.1/32            trust
host    all             all             ::1/128                 trust
bash
# 修改配置后重载（不需要重启）
pg_ctl -D $(brew --prefix)/var/postgresql@18 reload

# 或通过 SQL 重载
psql -c "SELECT pg_reload_conf();"

连接方式汇总 ​

bash
# 通过 Unix Socket（最快，不走 TCP）
psql -h $(brew --prefix)/var/run/postgresql -d postgres

# 通过 TCP 回环地址
psql -h 127.0.0.1 -p 5432 -U ch -d postgres

# 连接字符串 URI 形式（驱动中常用）
psql "postgresql://ch@127.0.0.1:5432/postgres?sslmode=disable"

多个版本并存 ​

Homebrew 允许同时安装多个大版本，它们各自有独立的二进制目录与数据目录：

bash
# 查看已安装的 PostgreSQL 版本
brew list --versions | grep postgresql
text
postgresql@16 16.6
postgresql@18 18.0
bash
# 使用指定版本的客户端
/opt/homebrew/opt/postgresql@16/bin/psql --version
/opt/homebrew/opt/postgresql@18/bin/psql --version

# 端口冲突：为 18 改成 5433，避免与 16 的 5432 冲突
# 修改 /opt/homebrew/var/postgresql@18/postgresql.conf 中的 port = 5433
bash
# 手动同时运行两个版本
pg_ctl -D /opt/homebrew/var/postgresql@16 -l /tmp/pg16.log start
pg_ctl -D /opt/homebrew/var/postgresql@18 -l /tmp/pg18.log start
psql -p 5432 -c "SHOW server_version;"   # 16.x
psql -p 5433 -c "SHOW server_version;"   # 18.x

Postgres.app 备选方案 ​

Postgres.app 是 macOS 上流行的原生应用，把 PostgreSQL 打包为 .app，双击即可启动：

bash
# 通过 Homebrew Cask 安装 Postgres.app
brew install --cask postgres-extension-pack
brew install --cask postgres-app

# Postgres.app 自带命令行工具，建议加入 PATH
# 应用内的 bin 目录形如：
# /Applications/Postgres.app/Contents/Versions/18/bin
echo 'export PATH="/Applications/Postgres.app/Contents/Versions/latest/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
对比项HomebrewPostgres.app
启动方式brew services / pg_ctl双击应用图标
数据目录$(brew --prefix)/var/postgresql@18~/Library/Application Support/Postgres/var-18
多版本各版本独立公式应用内切换
自动初始化安装时完成首次启动完成
可脚本化强（适合 CI）弱（依赖 GUI）
适用人群开发者、CI偏好图形界面的本地用户
bash
# 通过 Postgres.app 初始化数据目录（无需 GUI）
/Applications/Postgres.app/Contents/Versions/latest/bin/initdb \
  -D ~/Library/Application\ Support/Postgres/var-18

卸载与清理 ​

bash
# 停止服务
brew services stop postgresql@18

# 卸载公式（不会删除数据目录）
brew uninstall postgresql@18

# 彻底清理数据与配置（危险！请先备份）
# rm -rf $(brew --prefix)/var/postgresql@18
# rm -f ~/Library/LaunchAgents/homebrew.mxcl.postgresql@18.plist

# 清理不再需要的旧版本
brew cleanup postgresql@16

实战示例 ​

在 Apple Silicon Mac 上安装 PostgreSQL 18、配置不冲突的端口、创建业务库与用户，并用 URI 连接串验证。

bash
# ---------- 步骤 1：安装与 PATH ----------
brew update
brew install postgresql@18
echo 'export PATH="/opt/homebrew/opt/postgresql@18/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
psql --version
text
psql (PostgreSQL) 18.0 (Homebrew)
bash
# ---------- 步骤 2：确认数据目录已初始化并启动 ----------
PGDATA=$(brew --prefix)/var/postgresql@18
test -f "$PGDATA/PG_VERSION" && echo "已初始化: $(cat $PGDATA/PG_VERSION)"
brew services start postgresql@18
sleep 2
pg_ctl -D "$PGDATA" status
text
已初始化: 18
pg_ctl: server is running (PID: 41207)
/opt/homebrew/opt/postgresql@18/bin/postgres "-D" "/opt/homebrew/var/postgresql@18"
bash
# ---------- 步骤 3：创建业务用户与数据库 ----------
psql -d postgres <<'SQL'
-- 创建专用业务用户，避免应用直连超级用户
CREATE ROLE app_rw LOGIN PASSWORD 'Str0ng_P@ssw0rd';
-- 创建业务库并指定属主
CREATE DATABASE demo OWNER app_rw ENCODING 'UTF8';
SQL
text
CREATE ROLE
CREATE DATABASE
bash
# ---------- 步骤 4：调整认证方式，从 trust 改为密码认证 ----------
# 本地开发可保留 trust；若机器多人共用应改为 scram-sha-256
# 修改 $(brew --prefix)/var/postgresql@18/pg_hba.conf：
# host    all    all    127.0.0.1/32    scram-sha-256
PGDATA=$(brew --prefix)/var/postgresql@18
sed -i '' 's|^host    all    all    127.0.0.1/32    trust|host    all    all    127.0.0.1/32    scram-sha-256|' \
  "$PGDATA/pg_hba.conf"
pg_ctl -D "$PGDATA" reload
text
server signaled
bash
# ---------- 步骤 5：使用连接串验证 ----------
psql "postgresql://app_rw:Str0ng_P%40ssw0rd@127.0.0.1:5432/demo" \
  -c "SELECT current_user, current_database(), version();"
text
 current_user | current_database |                    version
--------------+------------------+------------------------------------------------
 app_rw       | demo             | PostgreSQL 18.0 (Homebrew) on aarch64-apple-darwin
(1 row)

注意事项 ​

  • postgresql@18 是 keg-only 公式，不会自动链接到 /opt/homebrew/bin，不配置 PATH 会出现 psql: command not found
  • Homebrew 的超级用户是当前 macOS 用户名，执行 sudo -u postgres psql 会失败（系统中没有 postgres 用户）
  • Intel Mac 与 Apple Silicon 的安装前缀不同，写脚本时务必用 $(brew --prefix) 而非硬编码
  • brew services start 会写入 ~/Library/LaunchAgents，在公司管控的 Mac 上可能没有权限，此时改用 pg_ctl
  • macOS 睡眠唤醒后偶发连接失败，通常是 launchd 服务被挂起，brew services restart postgresql@18 可恢复
  • 不要用系统自带的 sudo 安装路径混装 PostgreSQL 与 Homebrew 版本，会导致动态库冲突
  • 常见错误 FATAL: role "postgres" does not exist：请使用当前系统用户名连接，或先 createuser -s postgres
  • 升级大版本（如 17 → 18）必须使用 pg_upgrade 或逻辑导出导入，不能直接切换二进制指向上旧数据目录

最佳实践 ​

  • 统一用 $(brew --prefix) 引用路径，保证 Intel / Apple Silicon 双平台脚本通用
  • 开发环境可通过 brew services run 临时启动，避免长期占用后台资源
  • 每个项目使用独立的数据库与角色，避免全项目共用超级用户
  • 使用 ~/.pgpass（权限 0600）或连接串 + 环境变量管理密码，不要把密码写进代码仓库
  • 将数据目录排除出 Time Machine 之外或单独备份，避免备份体积失控；生产数据不要依赖本机备份
  • 需要与生产环境一致性更高时，优先使用 Docker 方案而非 Homebrew
  • 定期 brew upgrade postgresql@18 更新小版本，但升级前先备份数据目录

下一节

继续学习：Windows 安装

参考链接 ​