psql 连接 PostgreSQL 与 SSL 配置

正确使用连接 URI、环境变量、pgpass、超时和 TLS 验证连接 PostgreSQL

明确连接五要素

psql -X \
  --host=db.example.com \
  --port=5432 \
  --username=app_reader \
  --dbname=commerce

目标由 host、port、database、user 和 TLS 参数共同决定。不要只看数据库名；同名 database 可以存在于多个实例。

连接 URI 等价写法：

psql -X "postgresql://app_reader@db.example.com:5432/commerce?sslmode=verify-full"

不要把密码写入命令行 URI、源代码或日志。交互使用提示，自动化使用 secret manager、短期凭据、.pgpass 或 libpq service file。

pgpass

Unix 默认文件是 ~/.pgpass，权限必须限制为 0600：

hostname:5432:database:username:password

chmod 600 ~/.pgpass

Windows 默认位置是 %APPDATA%\postgresql\pgpass.conf。通配符会扩大凭据适用范围，应尽量写具体 host、database 和 user。

SSL 模式

`sslmode`	行为	使用建议
`disable`	不使用 TLS	仅受控本机/隔离测试
`require`	要求加密，但不完整验证身份	比明文好，不足以抵抗错误端点
`verify-ca`	验证证书链	仍不验证主机名
`verify-full`	验证证书链和主机名	远程生产连接的推荐目标

verify-full 要求 URI 中的 host 与证书身份匹配，并正确配置根证书。云平台可能有自己的 CA 轮换流程，不能永久固定一份过期证书。

连接后立即确认

\conninfo
SELECT
  current_database(), current_user, session_user,
  inet_server_addr(), inet_server_port(),
  current_setting('server_version') AS server_version,
  current_setting('TimeZone') AS timezone;

脚本建议使用：

psql -X --set ON_ERROR_STOP=on --file migration.sql "$DATABASE_URL"

-X 避免用户 .psqlrc 改变自动化行为；ON_ERROR_STOP 让脚本在 SQL 错误时退出。psql 退出码语义见 PostgreSQL 18 psql 文档。

连接超时与查询超时不同

连接参数控制建立会话要等多久；statement_timeout 控制 SQL 执行；lock_timeout 只控制等待锁。应用层还要设置请求截止时间，并确保超时后取消或释放数据库连接。

连接失败时记录完整错误和 SQLSTATE，再查看错误速查，不要通过关闭 TLS 或扩大权限来试错。

明确连接五要素

pgpass

SSL 模式

连接后立即确认

On this page