macOS连接PostgreSQL报port参数值5432export无效问题排查

基础环境 #

• 设备：较新款MacBook
• 系统：macOS Big Sur
• 开发环境：通过rails.new搭建本地开发环境，所有日常服务运行在Docker中，Ruby/Rails开发工作也在对应Docker上下文内开展

故障表现 #

连接本地正常运行的PostgreSQL服务时持续报错：

• 执行rails db:migrate运行数据库迁移时触发连接错误
• 终端直接调用psql命令连接时触发相同错误
• 甚至执行rails new新建空白项目时也会出现同类报错

对应报错信息：
执行数据库迁移的输出：

rails db:migrate
rails aborted!
ActiveRecord::ConnectionNotEstablished: invalid integer value "5432export" for connection option "port"

Caused by:
PG::ConnectionBad: invalid integer value "5432export" for connection option "port"

直接运行psql的输出：

$ psql
psql: error: invalid integer value "5432export" for connection option "port

由于rails new生成的全新项目文件中检索不到"5432export"字符串，且切换不同版本的Ruby、Rails后问题依然存在，最初判断故障点在plist配置文件或PostgreSQL程序自身的配置中。

初步排查操作 #

• 确认psql可执行文件路径：

  $ which psql
  /usr/local/bin/psql
  

• 核对Homebrew安装的PostgreSQL文件目录，对应路径为/usr/local/Cellar/postgresql/14.3/，目录下包含所有二进制可执行文件、plist配置文件、依赖库、文档等相关内容。
• 检查Homebrew服务状态，先后切换两个已安装的PostgreSQL版本验证故障是否随版本变化：
  初始服务状态：

  $ brew services
  Name          Status  User         File
  postgresql    none
  postgresql@13 started username ~/Library/LaunchAgents/homebrew.mxcl.postgresql@13.plist
  

  切换版本操作及结果：

  $ brew services stop postgresql@13
  Stopping `postgresql@13`... (might take a while)
  ==> Successfully stopped `postgresql@13` (label: homebrew.mxcl.postgresql@13)
  $ brew services start postgresql
  ==> Successfully started `postgresql` (label: homebrew.mxcl.postgresql)
  $ psql
  psql: error: invalid integer value "5432export" for connection option "port"
  

  切换版本后故障完全一致，排除特定版本PostgreSQL配置损坏的可能。
• 尝试通过find命令在PostgreSQL的bin目录下全局检索"5432export"字符串，未找到任何匹配项。

排查进展更新 #

手动指定端口参数执行psql连接时，不再提示端口值非法，转而报角色不存在错误：

$ psql -p 5432
psql: error: connection to server at "127.0.0.1", port 5432 failed: FATAL:  role "postgres" does not exist

追加指定用户参数后，依然报相同的角色不存在错误：

$ psql -p 5432 -U postgres
psql: error: connection to server at "127.0.0.1", port 5432 failed: FATAL:  role "postgres" does not exist

注：命令行传入的连接参数优先级高于环境变量和默认配置，因此手动指定-p参数时会覆盖默认读取的端口值，直接跳过端口校验环节。

根因与解决方法 #

故障并非PostgreSQL程序或项目配置导致，根源是PG相关环境变量配置错误。执行环境变量检索命令即可确认错误配置：

$ env | grep PG
PGHOST=127.0.0.1
PGPORT=5432export
PGUSER=postgres

其中PGPORT被误设置为5432export，psql和ActiveRecord连接数据库时会优先读取该环境变量作为端口值，因此触发"invalid integer value"报错。

修复步骤：

1. 根据自身使用的shell，找到对应的shell配置文件（如zsh对应~/.zshrc，bash对应~/.bashrc/~/.bash_profile）
2. 在配置文件中搜索错误的PGPORT配置行，将值从5432export修正为正确的5432
3. 保存文件后执行source命令重载shell配置，重新连接数据库即可恢复正常，后续再单独处理postgres角色不存在的问题即可。

内容的提问来源于stack exchange，提问作者Josh_Thompson