本地Django项目连接PostgreSQL容器报错：角色‘demo’不存在求助

问题场景 #

本地Django项目连接PostgreSQL容器时，报错：

django.db.utils.OperationalError: connection failed: :1), port 5432 failed: FATAL: role "demo" does not exist

相关配置文件如下：

.env文件 #

POSTGRES_USER=demo
POSTGRES_PASSWORD=demo
POSTGRES_NAME=demo

docker-compose.yml文件 #

volumes:
  postgres_data:

services:
  db:
    image: postgres:15
    volumes:
      - postgres_data:/var/lib/postgresql/data/
    env_file:
      - .env
    ports:
      - "5432:5432"

Django settings.py数据库配置 #

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.postgresql",
        "NAME": env('POSTGRES_NAME'),
        "USER": env('POSTGRES_USER'),
        "PASSWORD": env('POSTGRES_PASSWORD'),
        "HOST": "localhost",  # set in docker-compose.yml
        "PORT": 5432,  # default postgres port
    }
}

排查与解决方法 #

1. 清理旧数据卷（最常见原因） #

PostgreSQL镜像的核心特性：仅在第一次启动容器且数据卷为空时，才会读取POSTGRES_USER等环境变量创建初始用户和数据库。如果之前启动过容器，postgres_data卷已保留旧数据库数据，后续启动不会重新创建用户。

操作步骤：

• 停止并删除容器：docker-compose down
• 删除关联数据卷：docker-compose down -v（此命令会直接删除docker-compose中定义的所有卷）
• 重新启动数据库容器：docker-compose up -d db

2. 验证.env文件是否正确加载 #

检查docker-compose.yml中env_file路径是否正确（确保.env和docker-compose.yml在同一目录），也可进入容器确认环境变量：

• 进入容器：docker exec -it <容器ID/名称> bash
• 查看变量：echo $POSTGRES_USER，若输出demo则正常，否则检查.env格式（无多余空格、变量名无拼写错误）。

3. 手动确认数据库用户是否存在 #

进入容器后连接PostgreSQL，直接检查用户列表：

• 执行psql -U postgres（使用默认超级用户登录）
• 执行查询语句：SELECT usename FROM pg_user;，若列表中无demo，说明初始化未生效，按步骤1清理数据卷重新初始化。

4. 补充：HOST配置说明 #

当前错误与HOST无关，但后续若遇连接超时需注意：如果Django也部署在docker-compose中，HOST需设为服务名db；本地Django连接容器时，localhost是正确配置（因为端口已映射到本地）。

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