Mac端Jupyter连接PostgreSQL报主机名解析失败、连接被拒错误

两个报错属于递进的网络链路故障，和Python代码、psycopg2依赖、Jupyter运行环境无直接关联：

• 第一个could not translate host name报错：本地Mac的DNS服务无法将db.production.info域名映射到对应服务器IP，属于域名解析层故障
• 第二个替换IP后出现的Connection refused报错：说明本地已经能路由到目标IP，但目标地址的对应端口没有提供可访问的数据库服务，属于连通性/服务配置层故障

1. 优先修复域名解析问题（不建议长期硬写IP） #

先打开Mac终端执行解析测试，不要直接改代码凑数：

nslookup db.production.info

如果命令执行后没有返回对应的服务器IP，按顺序排查：

• 确认当前接入的网络符合数据库访问要求：绝大多数生产数据库仅对内网、专线VPN开放，公网环境下无法解析内网专属域名
• 若需要VPN接入，检查VPN连接状态，确认没有开分流规则导致数据库域名走了公网DNS解析
• 临时修复可以将正确的IP-域名映射写入本地/etc/hosts文件，添加格式为192.XXX.XX.XX db.production.info，保存后即可正常解析域名。

2. 解决连接被拒绝问题 #

解析正常后如果仍报连接拒绝，按以下顺序排查：

• 首先核对端口配置：PostgreSQL默认服务端口为5432，生产环境通常会修改为自定义端口。如果你的连接串没有显式指定端口，SQLAlchemy会默认请求5432端口，和服务端实际端口不匹配时会直接被拒绝。带端口的正确连接串格式如下：

import sqlalchemy as db
connection_string = f"postgresql://{db_cred['username']}:{db_cred['password']}@{db_cred['host']}:{db_cred['port']}/{db_cred['database']}"
engine = db.create_engine(connection_string)
conn = engine.connect()

• 跳过代码直接在终端测试端口连通性，排除代码逻辑干扰：

# 将IP、端口替换为实际的数据库地址和端口
nc -zv 192.XXX.XX.XX XXXX

• 如果返回Connection refused：逐一排查三个可能：①目标服务器上的PostgreSQL服务未启动；②服务器防火墙、安全组没有放开你当前出口IP的访问权限；③PostgreSQL配置文件postgresql.conf中未设置listen_addresses = '*'，默认仅监听本地回环地址，拒绝所有外部连接请求
• 如果返回请求超时：说明网络链路不通，优先确认VPN/专线连接状态，再联系网络管理员确认路由规则
• 核对数据库访问控制配置：PostgreSQL的pg_hba.conf文件中需要添加客户端所在IP段的连接准入规则，否则即使端口连通，服务端也会主动拒绝连接。

• 不要尝试用公网IP直接连接仅对内网开放的生产数据库，请求会被防火墙直接拦截
• 本地如果运行了Clash、Surge等网络代理工具，先临时关闭代理测试，或者添加数据库域名、IP段的直连规则，避免代理转发内网请求导致连通失败
• 注意区分数据库服务的实际IP和Docker容器内部IP，172.17/18网段的容器内部IP仅能在宿主机上访问，外部机器直接连接必然失败。

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