PostgreSQL 在 macOS 上安装

系统要求与安装方式选择

系统要求

macOS 版本	支持情况
macOS 14 (Sonoma)	完全支持
macOS 13 (Ventura)	完全支持
macOS 12 (Monterey)	完全支持
macOS 11 (Big Sur)	完全支持
macOS 10.15 (Catalina)	支持 PostgreSQL 15 及以下版本
macOS 10.14 (Mojave)	支持 PostgreSQL 14 及以下版本

硬件要求

组件	最低要求	推荐配置
内存	2 GB RAM	4 GB RAM 以上
存储空间	10 GB 可用磁盘空间	50 GB 以上可用磁盘空间
CPU	2 核处理器	4 核处理器以上
存储类型	SATA 硬盘	SSD 或 NVMe 固态硬盘

安装方式对比

安装方式	适用场景	优点	缺点
Homebrew 安装	开发环境、快速部署	简单易用、更新方便、自动依赖管理、社区活跃	版本可能滞后于官方最新版、配置灵活性较低
官方安装包	生产环境、需要精确版本控制	官方支持、版本完整、配置灵活、适合生产环境	手动管理、更新需要重新下载安装包
Docker 安装	容器化环境、隔离开发、多版本共存	环境隔离、部署快速、版本可控、便于迁移	性能开销较大、管理复杂度增加
编译安装	自定义编译选项、最新特性、性能优化	完全定制、最新版本、可优化编译选项	编译复杂、耗时较长、需要手动管理依赖

Homebrew 安装

安装 Homebrew

如果尚未安装 Homebrew，请先安装：

bash

# 安装 Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装完成后，配置环境变量（针对 Apple Silicon Mac）
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

# 针对 Intel Mac
echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/usr/local/bin/brew shellenv)"

安装 PostgreSQL

查看可用版本

bash

# 查看可用的 PostgreSQL 版本
brew search postgresql

# 查看特定版本的详细信息
brew info postgresql@16

安装特定版本

bash

# 安装最新稳定版
brew install postgresql

# 安装特定版本（推荐 LTS 版本，如 16）
brew install postgresql@16

# 链接特定版本到 PATH
brew link postgresql@16 --force

服务管理

bash

# 启动服务
brew services start postgresql@16

# 停止服务
brew services stop postgresql@16

# 重启服务
brew services restart postgresql@16

# 设置开机自启
brew services enable postgresql@16

# 禁用开机自启
brew services disable postgresql@16

# 查看服务状态
brew services list | grep postgresql

初始化与验证

bash

# 验证安装
psql --version

# 检查服务状态
pg_isready

# 连接到默认数据库
psql postgres

# 查看 PostgreSQL 版本
postgres=# SELECT version();

# 退出 PostgreSQL 命令行
postgres=# \q

默认配置路径

配置项	路径
数据目录	`/opt/homebrew/var/postgresql@16`（Apple Silicon）或 `/usr/local/var/postgresql@16`（Intel）
配置文件	`/opt/homebrew/var/postgresql@16/postgresql.conf` 或 `/usr/local/var/postgresql@16/postgresql.conf`
HBA 文件	`/opt/homebrew/var/postgresql@16/pg_hba.conf` 或 `/usr/local/var/postgresql@16/pg_hba.conf`
日志目录	`/opt/homebrew/var/postgresql@16/log` 或 `/usr/local/var/postgresql@16/log`

官方安装包安装

下载安装包

访问 PostgreSQL 官方下载页面
选择 PostgreSQL for macOS
点击 Download the installer
选择合适的版本（推荐 LTS 版本，如 16）
下载 .dmg 安装包

安装步骤

双击下载的 .dmg 文件，打开安装程序
双击 PostgreSQL xx.x Installer 图标
点击 Continue 开始安装
阅读并同意许可协议，点击 Continue → Agree
选择安装类型，点击 Install
输入 macOS 用户密码进行身份验证
安装完成后，点击 Close

安装后配置

服务管理

bash

# 启动服务
sudo /Library/PostgreSQL/16/bin/pg_ctl -D /Library/PostgreSQL/16/data start

# 停止服务
sudo /Library/PostgreSQL/16/bin/pg_ctl -D /Library/PostgreSQL/16/data stop

# 重启服务
sudo /Library/PostgreSQL/16/bin/pg_ctl -D /Library/PostgreSQL/16/data restart

# 设置开机自启
sudo launchctl load /Library/LaunchDaemons/com.edb.launchd.postgresql-16.plist

# 禁用开机自启
sudo launchctl unload /Library/LaunchDaemons/com.edb.launchd.postgresql-16.plist

环境变量配置

为方便使用命令行工具，将 PostgreSQL 二进制目录加入环境变量：

bash

# 编辑 ~/.zshrc 或 ~/.bash_profile
echo 'export PATH="/Library/PostgreSQL/16/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

验证安装

bash

# 验证安装
psql --version

# 连接到数据库
psql -U postgres

# 查看 PostgreSQL 版本
postgres=# SELECT version();

Docker 容器安装

安装 Docker Desktop

下载 Docker Desktop for Mac
安装并启动 Docker Desktop
确保 Docker 服务正常运行

运行 PostgreSQL 容器

bash

# 拉取 PostgreSQL 镜像
# 拉取最新版本
docker pull postgres

# 或拉取特定版本
docker pull postgres:16

# 创建数据卷（持久化存储）
docker volume create pgdata

# 运行容器
# 基础配置
docker run -d \
  --name postgres \
  -e POSTGRES_PASSWORD=your_secure_password \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_DB=postgres \
  -p 5432:5432 \
  -v pgdata:/var/lib/postgresql/data \
  postgres:16

# 生产环境推荐配置
docker run -d \
  --name postgres \
  --restart unless-stopped \
  -e POSTGRES_PASSWORD=your_secure_password \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_DB=postgres \
  -e PGDATA=/var/lib/postgresql/data/pgdata \
  -e POSTGRES_INITDB_ARGS="--encoding=UTF8 --lc-collate=C --lc-ctype=en_US.UTF-8" \
  -p 5432:5432 \
  -v pgdata:/var/lib/postgresql/data \
  --memory=4g \
  --cpus=2 \
  postgres:16

# 查看容器状态
docker ps

# 访问 PostgreSQL
docker exec -it postgres psql -U postgres

Docker 容器管理

bash

# 停止容器
docker stop postgres

# 启动容器
docker start postgres

# 重启容器
docker restart postgres

# 查看日志
docker logs postgres

# 查看容器详细信息
docker inspect postgres

# 删除容器
docker rm postgres

# 删除数据卷
docker volume rm pgdata

# 删除镜像
docker rmi postgres:16

编译安装

安装依赖

bash

# 安装编译依赖
brew install pkg-config openssl readline zlib libxml2 libxslt libcurl libicu

下载并编译源码

bash

# 下载源码包
wget https://ftp.postgresql.org/pub/source/v16.1/postgresql-16.1.tar.bz2

# 解压源码
tar -xjf postgresql-16.1.tar.bz2
cd postgresql-16.1

# 配置编译选项
./configure \
  --prefix=/usr/local/pgsql \
  --with-openssl \
  --with-readline \
  --with-zlib \
  --with-libxml \
  --with-libxslt \
  --with-libcurl \
  --with-icu \
  --with-perl \
  --with-python \
  --with-tcl \
  --enable-thread-safety

# 编译（使用多核加速）
make -j $(sysctl -n hw.ncpu)

# 安装
make install

# 安装扩展模块
make -C contrib install

初始化与配置

bash

# 创建 postgres 用户（如果不存在）
sudo dscl . -create /Users/postgres
udo dscl . -create /Users/postgres UserShell /bin/bash
sudo dscl . -create /Users/postgres RealName "PostgreSQL Server"
sudo dscl . -create /Users/postgres UniqueID "502"
sudo dscl . -create /Users/postgres PrimaryGroupID "staff"
sudo dscl . -create /Users/postgres NFSHomeDirectory /Users/postgres

# 创建必要的目录
mkdir -p /usr/local/pgsql/data
mkdir -p /usr/local/pgsql/log
chown -R postgres:staff /usr/local/pgsql

# 切换到 postgres 用户
sudo su - postgres

# 设置环境变量
export PATH=/usr/local/pgsql/bin:$PATH
export PGDATA=/usr/local/pgsql/data
export PGLOG=/usr/local/pgsql/log/postgresql.log

# 初始化数据库
initdb -D $PGDATA -E UTF8 --locale=en_US.UTF-8 -W

# 启动数据库
pg_ctl -D $PGDATA -l $PGLOG start

# 设置开机自启（可选）
# 创建 launchd 配置文件

初始数据库配置

修改超级用户密码

sql

-- 连接到数据库后执行
ALTER USER postgres WITH PASSWORD 'new_secure_password';

创建新数据库和用户

sql

-- 连接到 PostgreSQL
psql -U postgres

-- 创建新数据库
CREATE DATABASE myappdb;

-- 创建新用户
CREATE USER myappuser WITH PASSWORD 'app_user_password';

-- 授予用户对数据库的权限
GRANT ALL PRIVILEGES ON DATABASE myappdb TO myappuser;

-- 授予用户对 public schema 的权限
GRANT ALL ON SCHEMA public TO myappuser;

-- 授予用户创建表的权限
ALTER USER myappuser CREATEDB;

允许远程连接

默认情况下，PostgreSQL 只允许本地连接。如需远程访问：

修改 postgresql.conf：

bash

# 编辑配置文件
vi /opt/homebrew/var/postgresql@16/postgresql.conf

# 修改监听地址
listen_addresses = '*'      # 允许所有 IP 访问

修改 pg_hba.conf：

bash

# 编辑 HBA 文件
vi /opt/homebrew/var/postgresql@16/pg_hba.conf

# 添加远程访问规则
# TYPE  DATABASE        USER            ADDRESS                 METHOD
host    all             all             0.0.0.0/0               scram-sha-256
host    all             all             ::/0                    scram-sha-256

重启服务使配置生效：
bash
```
brew services restart postgresql@16
```

生产环境配置优化

内存参数优化

编辑 postgresql.conf 文件：

ini

# 共享缓冲区（建议设置为系统内存的 25%）
shared_buffers = 4GB

# 每个查询操作可使用的内存
work_mem = 16MB

# 维护操作使用的内存（如 VACUUM、CREATE INDEX）
maintenance_work_mem = 1GB

# 系统缓存建议值（建议设置为系统内存的 75%）
effective_cache_size = 12GB

# WAL 缓冲区大小
wal_buffers = 16MB

连接参数优化

ini

# 最大连接数（根据实际需求调整）
max_connections = 200

# 保留备用连接数
superuser_reserved_connections = 3

# TCP 连接超时时间
tcp_keepalives_idle = 60
tcp_keepalives_interval = 10
tcp_keepalives_count = 5

WAL 配置优化

ini

# WAL 级别（流复制需要 replica 或 logical）
wal_level = replica

# 最大 WAL 大小
max_wal_size = 8GB

# 最小 WAL 大小
min_wal_size = 4GB

# 检查点间隔时间
checkpoint_timeout = 15min

# 检查点完成目标（平滑 I/O）
checkpoint_completion_target = 0.9

# WAL 归档模式（生产环境建议启用）
archive_mode = on
archive_command = 'cp %p /path/to/archive/%f'

日志配置优化

ini

# 日志输出目标
log_destination = 'stderr'
logging_collector = on

# 日志目录
log_directory = 'log'

# 日志文件名格式
log_filename = 'postgresql-%Y-%m-%d_%H%M%S.log'

# 日志轮转策略
log_rotation_age = 1d
log_rotation_size = 0

# 记录执行时间超过 1 秒的语句
log_min_duration_statement = 1000

# 记录慢查询的详细信息
log_statement = 'mod'

# 记录检查点信息
log_checkpoints = on

# 记录连接和断开连接信息
log_connections = on
log_disconnections = on

常用命令

数据库操作

bash

# 列出所有数据库
psql -l

# 创建数据库
createdb -U postgres newdb

# 删除数据库
dropdb -U postgres olddb

# 连接到指定数据库
psql -d mydb -U myuser

# 执行 SQL 文件
psql -d mydb -U myuser -f script.sql

备份与恢复

bash

# 备份数据库（SQL 格式）
pgg_dump -U postgres -d mydb > mydb_backup.sql

# 备份数据库（自定义格式，压缩）
pgg_dump -U postgres -d mydb -F c -Z 5 -f mydb_backup.dump

# 备份所有数据库
pgg_dumpall -U postgres > all_databases.sql

# 恢复数据库（SQL 格式）
psql -U postgres -d mydb < mydb_backup.sql

# 恢复数据库（自定义格式）
pgg_restore -U postgres -d mydb mydb_backup.dump

服务管理

bash

# 查看服务状态
pg_ctl status -D /opt/homebrew/var/postgresql@16

# 手动启动服务
pg_ctl start -D /opt/homebrew/var/postgresql@16

# 手动停止服务
pg_ctl stop -D /opt/homebrew/var/postgresql@16 -m fast

# 手动重启服务
pg_ctl restart -D /opt/homebrew/var/postgresql@16 -m fast

常见问题与解决方案

端口被占用

症状：启动 PostgreSQL 时提示端口 5432 被占用

解决方案：

bash

# 查找占用端口的进程
lsof -i :5432

# 终止占用端口的进程
kill -9 <PID>

# 或修改 PostgreSQL 端口
# 在 postgresql.conf 中修改
port = 5433

无法连接到数据库

症状：

psql: error: connection to server at "localhost" (::1), port 5432 failed: Connection refused
FATAL: password authentication failed for user "postgres"

解决方案：

检查服务是否启动：
bash
```
brew services list | grep postgresql
```
检查密码是否正确：
- 重新设置 postgres 用户密码
- 使用正确的密码连接
检查 pg_hba.conf 配置：
- 确保允许从客户端 IP 地址连接
- 检查认证方法是否正确
检查防火墙设置：
- 确保 macOS 防火墙允许 PostgreSQL 服务通过

Homebrew 升级后 PostgreSQL 无法启动

症状：Homebrew 升级后 PostgreSQL 服务无法启动

解决方案：

bash

# 重新初始化数据库（注意：这会删除现有数据，谨慎操作）
brew postgresql-upgrade-database

# 重启服务
brew services restart postgresql@16

权限问题

症状：

FATAL: could not open directory "pg_tblspc": Permission denied
ERROR: permission denied for schema public

解决方案：

bash

# 修复数据目录权限
chown -R postgres:staff /opt/homebrew/var/postgresql@16
chmod 700 /opt/homebrew/var/postgresql@16

# 授予 schema 权限
psql -U postgres -c "GRANT ALL ON SCHEMA public TO myuser;"

macOS 升级后 PostgreSQL 无法启动

症状：macOS 系统升级后，PostgreSQL 服务无法启动

解决方案：

bash

# 检查日志文件
cat /opt/homebrew/var/postgresql@16/log/postgresql-*.log

# 常见原因及解决方法：
# 1. 依赖库更新：重新安装 PostgreSQL
brew reinstall postgresql@16

# 2. 数据目录权限：修复权限
chown -R postgres:staff /opt/homebrew/var/postgresql@16

# 3. 配置文件问题：检查并修复配置文件

卸载 PostgreSQL

卸载 Homebrew 安装的 PostgreSQL

bash

# 停止服务
brew services stop postgresql@16

# 卸载 PostgreSQL
brew uninstall postgresql@16

# 删除数据目录
rm -rf /opt/homebrew/var/postgresql@16

# 删除配置文件（如果有）
rm -rf ~/.postgresql

# 清理残留文件
brew cleanup

卸载官方安装包

打开 Finder，进入 Applications 目录
找到 PostgreSQL xx 目录，拖拽到 废纸篓
删除数据目录：
bash
```
sudo rm -rf /Library/PostgreSQL/16
```

删除启动项：

bash

sudo rm -f /Library/LaunchDaemons/com.edb.launchd.postgresql-16.plist

删除环境变量：

bash

# 编辑 ~/.zshrc 或 ~/.bash_profile，删除相关行

卸载 Docker 安装的 PostgreSQL

bash

# 停止并删除容器
docker stop postgres
docker rm postgres

# 删除数据卷
docker volume rm pgdata

# 删除镜像
docker rmi postgres:16

最佳实践

定期备份：建立完善的备份策略，包括全量备份和增量备份
监控日志：定期检查 PostgreSQL 日志，及时发现和解决问题
更新版本：定期更新 PostgreSQL 到最新稳定版本，修复安全漏洞
使用 SSD：将数据目录和 WAL 目录放在 SSD 上，提高性能
合理配置内存：根据系统内存调整 shared_buffers 等参数
限制连接数：根据服务器资源合理设置 max_connections
启用 WAL 归档：配置 WAL 归档，支持时间点恢复
使用连接池：对于高并发场景，使用连接池（如 PgBouncer）
定期 VACUUM：定期执行 VACUUM 操作，回收空间
监控性能：使用监控工具（如 pgAdmin、Prometheus + Grafana）监控数据库性能
使用专用用户：避免使用 postgres 超级用户进行日常操作
启用 SSL：在生产环境中启用 SSL 加密

总结

在 macOS 上安装 PostgreSQL 有多种方式，每种方式都有其适用场景：

开发环境：推荐使用 Homebrew 安装，简单易用，更新方便
生产环境：推荐使用官方安装包或编译安装，配置更灵活，性能更优
容器化环境：推荐使用 Docker 安装，隔离性好，部署快速
需要特定编译选项：推荐编译安装，可以完全定制

安装完成后，需要进行适当的配置和优化，包括服务管理、环境变量配置、初始数据库设置和生产环境优化。定期备份、监控日志、更新版本是保证数据库长期稳定运行的重要措施。

通过遵循本文中的最佳实践和配置建议，DBA 可以在 macOS 系统上快速、安全地部署和管理 PostgreSQL 数据库，满足各种业务需求。

PostgreSQL 在 macOS 上安装 ​

系统要求与安装方式选择 ​

系统要求 ​

硬件要求 ​

安装方式对比 ​

Homebrew 安装 ​

安装 Homebrew ​

安装 PostgreSQL ​

查看可用版本 ​

安装特定版本 ​

服务管理 ​

初始化与验证 ​

默认配置路径 ​

官方安装包安装 ​

下载安装包 ​

安装步骤 ​

安装后配置 ​

服务管理 ​

环境变量配置 ​

验证安装 ​

Docker 容器安装 ​

安装 Docker Desktop ​

运行 PostgreSQL 容器 ​

Docker 容器管理 ​

编译安装 ​

安装依赖 ​

下载并编译源码 ​

初始化与配置 ​

初始数据库配置 ​

修改超级用户密码 ​

创建新数据库和用户 ​

允许远程连接 ​

生产环境配置优化 ​

内存参数优化 ​

连接参数优化 ​

WAL 配置优化 ​

日志配置优化 ​

常用命令 ​

数据库操作 ​

备份与恢复 ​

服务管理 ​

常见问题与解决方案 ​

端口被占用 ​

无法连接到数据库 ​

Homebrew 升级后 PostgreSQL 无法启动 ​

权限问题 ​

macOS 升级后 PostgreSQL 无法启动 ​

卸载 PostgreSQL ​

卸载 Homebrew 安装的 PostgreSQL ​

卸载官方安装包 ​

卸载 Docker 安装的 PostgreSQL ​

最佳实践 ​

总结 ​

PostgreSQL 在 macOS 上安装

系统要求与安装方式选择

系统要求

硬件要求

安装方式对比

Homebrew 安装

安装 Homebrew

安装 PostgreSQL

查看可用版本

安装特定版本

服务管理

初始化与验证

默认配置路径

官方安装包安装

下载安装包

安装步骤

安装后配置

服务管理

环境变量配置

验证安装

Docker 容器安装

安装 Docker Desktop

运行 PostgreSQL 容器

Docker 容器管理

编译安装

安装依赖

下载并编译源码

初始化与配置

初始数据库配置

修改超级用户密码

创建新数据库和用户

允许远程连接

生产环境配置优化

内存参数优化

连接参数优化

WAL 配置优化

日志配置优化

常用命令

数据库操作

备份与恢复

服务管理

常见问题与解决方案

端口被占用

无法连接到数据库

Homebrew 升级后 PostgreSQL 无法启动

权限问题

macOS 升级后 PostgreSQL 无法启动

卸载 PostgreSQL

卸载 Homebrew 安装的 PostgreSQL

卸载官方安装包

卸载 Docker 安装的 PostgreSQL

最佳实践

总结