TablePlus连接Docker版PostgreSQL提示root用户密码认证失败

该报错90%以上由以下两类核心原因导致：

1. 宿主机5432端口被已有服务占用：多数情况是本地提前安装了原生PostgreSQL服务默认监听5432端口，导致Docker容器端口映射失败，此时客户端实际连接的是宿主机本地的PostgreSQL实例，该实例不存在root用户，自然返回密码认证失败。
2. 旧容器残留数据卷冲突：POSTGRES_USER、POSTGRES_PASSWORD环境变量仅在PostgreSQL数据目录首次初始化时生效，如果之前创建过同名postgres12容器，残留的旧数据卷中已经存储了初始化完成的数据库文件，新启动容器时传入的密码参数会被直接忽略，新旧密码不匹配就会报认证错误。
   少数情况是客户端连接参数配置错误、容器启动后数据库未完成初始化就发起连接导致的偶发报错。

按以下顺序操作即可解决：

• 先执行docker ps检查postgres12容器运行状态，如果容器未处于Up状态，执行docker logs postgres12查看日志，确认是否存在端口绑定失败报错。如果是端口占用，要么停掉宿主机上占用5432端口的服务，要么修改端口映射参数为-p 5433:5432，后续客户端连接时对应填宿主机映射的端口即可。
• 清理旧容器与残留数据，重新初始化数据库实例，执行以下命令：

  # 强制删除旧的故障容器
  docker rm -f postgres12
  # 启动新容器，使用具名卷持久化数据，避免匿名卷残留冲突
  docker run --name postgres12 -p 5432:5432 -e POSTGRES_USER=root -e POSTGRES_PASSWORD=secret -v postgres12_data:/var/lib/postgresql/data -d postgres:12-alpine
  

• 容器启动后等待3-5秒待数据库完成初始化，先在命令行执行直连命令验证账号可用性：

  docker exec -it postgres12 psql -U root -W
  

  输入密码secret如果能正常进入psql交互界面，说明数据库侧账号密码配置完全正常，问题出在客户端配置：检查TablePlus连接参数，主机地址填127.0.0.1（不要填localhost，部分客户端下localhost会走Unix socket连接而非TCP，会连到宿主机本地数据库）、端口与宿主机映射端口一致、用户名密码填写正确，默认数据库可填postgres先测试连通性。

注意：不要在容器启动后立刻发起连接，PostgreSQL首次初始化需要数秒时间，初始化未完成时发起连接也可能抛出认证失败错误。

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