使用URI连接PostgreSQL失败，CLI参数却正常，原因何在？

核心原因 #

psql对连接URI和CLI参数的解析逻辑存在差异：

• 当使用CLI参数-h localhost时，psql会强制走TCP/IP协议连接指定端口，刚好匹配Docker映射的宿主机127.0.0.1:5432端口，因此能正常连通。
• 当使用完整URI postgresql://postgres@localhost:5432/postgres时，psql默认对localhost优先尝试Unix域套接字连接，直接忽略端口参数。但你的PostgreSQL运行在容器中，宿主机本地没有PostgreSQL实例，自然不存在/tmp/.s.PGSQL.5432这个套接字文件，所以抛出连接错误。
• 去掉URI里的数据库名后，psql的解析逻辑自动切换为TCP/IP连接，因此能正常运行。

修复方案 #

有三种简单可行的修复方式：

1. URI中用127.0.0.1替代localhost
   显式指定IP地址会强制psql使用TCP/IP连接，避免套接字尝试：

   DB_ADDRESS="postgresql://postgres@127.0.0.1:5432/postgres"
   

2. URI末尾添加TCP强制参数
   通过查询参数明确指定使用TCP连接：

   DB_ADDRESS="postgresql://postgres@localhost:5432/postgres?host=localhost"
   

3. 调整psql默认行为（不推荐）
   可以在~/.psqlrc或环境变量PGOPTIONS中配置强制TCP，但这种方式灵活性差，不如前两种直接高效。

验证方法 #

用psql -v参数查看连接细节，确认逻辑差异：

• 带数据库名的URI连接：psql -v postgresql://postgres@localhost:5432/postgres，会看到日志显示尝试连接Unix套接字。
• CLI参数连接：psql -v -U postgres -h localhost -d postgres，会看到日志显示尝试TCP连接127.0.0.1:5432。

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