执行Alembic命令遇socket.gaierror错误，请求排查数据库连接问题

错误本质 #

这个错误是DNS解析失败，Python无法找到你配置的POSTGRES_HOST对应的IP地址，核心问题是PostgreSQL主机名的配置和你的运行环境不匹配。

排查与解决方案 #

先确认基础信息 #

1. 运行docker ps确认PostgreSQL容器处于运行状态
2. 检查你的docker-compose.yml（如果用了），确认PostgreSQL服务的网络配置和端口映射

分场景解决 #

场景1：在宿主机本地执行Alembic命令

• 若PostgreSQL容器已映射端口到宿主机（docker-compose.yml中有ports: - "5432:5432"）：
  1. 修改.env中的POSTGRES_HOST为localhost
  2. 进入PostgreSQL容器，修改postgresql.conf中的listen_addresses = '*'（默认可能仅允许localhost连接，需开放外部访问），然后重启容器
• 若用Linux原生Docker Engine（非Docker Desktop）：
  host.docker.internal这个别名不生效，直接用宿主机的局域网IP或localhost（需端口映射）

场景2：在Docker容器内执行Alembic命令（推荐）

将Alembic命令放到Docker容器中执行，利用Docker内部DNS直接解析服务名：

1. 在docker-compose.yml中确保应用服务和PostgreSQL在同一网络：

   services:
     postgres:
       image: postgres:15
       environment:
         POSTGRES_USER: postgres
         POSTGRES_PASSWORD: postgres
         POSTGRES_DB: postgres
       networks:
         - app-network
     app:
       build: .
       environment:
         POSTGRES_HOST: postgres  # 直接用PostgreSQL服务名作为主机名
         POSTGRES_PORT: 5432
         # 其他环境变量...
       networks:
         - app-network
       depends_on:
         - postgres
   networks:
     app-network:
       driver: bridge
   

2. 执行命令：

   docker-compose run app alembic upgrade head
   

额外排查点 #

• 验证环境变量加载：在settings.py中添加print(settings.POSTGRES_HOST)，确认读取到的主机名正确
• 测试连通性：用ping <POSTGRES_HOST>或telnet <POSTGRES_HOST> 5432检查宿主机/容器能否访问PostgreSQL
• 检查Alembic的env.py：确保正确实例化Settings类，比如：

  from your_project.settings import Settings
  settings = Settings()  # 必须实例化才能读取环境变量
  

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