Django+PostgreSQL使用pg_service.conf遇“服务定义未找到”错误

问题描述 #

在Django应用中配置使用pg_service.conf管理PostgreSQL连接时，出现服务定义未找到的错误，但使用常规连接字符串可正常连接数据库。

当前配置 #

Django settings.py 数据库配置 #

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'OPTIONS': {
            'service': 'my_service'
        }
    }
}

pg_service.conf 配置（路径：/etc/postgresql-common/pg_service.conf） #

[my_service]
host=localhost
port=5432
user=my_user
password=my_password
dbname=my_database

错误日志 #

psycopg2.OperationalError: service file "/etc/postgresql-common/pg_service.conf" not found 
The above exception was the direct cause of the following exception:
django.db.utils.OperationalError: definition of service "my_service" not found

已执行的排查步骤 #

• 确认pg_service.conf文件存在于指定路径，权限为postgres用户所有（0640）
• 核对Django配置中的服务名与pg_service.conf中的定义完全一致
• 修改配置后重启Django应用
• 验证常规连接字符串可正常连接数据库
• 重启PostgreSQL服务

额外排查方向及解决方案 #

1. 强制指定服务文件路径 #

psycopg2可能未默认识别/etc/postgresql-common/pg_service.conf，需通过环境变量明确指定：

• 临时生效：

  export PGSERVICEFILE=/etc/postgresql-common/pg_service.conf
  

• 持久生效（如部署为systemd服务）：在服务配置文件中添加Environment="PGSERVICEFILE=/etc/postgresql-common/pg_service.conf"

2. 检查Django运行用户的文件权限 #

如果Django以非postgres用户运行（如www-data、自定义django用户），需确保：

• 运行用户对/etc/postgresql-common目录有执行权限（允许进入目录）
• 对pg_service.conf文件有读取权限
  执行以下命令调整权限：

chmod o+x /etc/postgresql-common/
chmod o+r /etc/postgresql-common/pg_service.conf

或者将运行用户加入postgres用户组：

usermod -aG postgres [你的Django运行用户名]

3. 检查pg_service.conf语法格式 #

确保文件无语法错误：

• 所有配置项为key=value格式，无多余空格
• 服务块[my_service]独占一行，前后无空格
• 注释需以#开头

4. 更新psycopg2版本 #

旧版psycopg2可能存在服务文件支持缺陷，更新至最新版：

pip install --upgrade psycopg2-binary

5. 排查冲突的服务文件 #

系统中可能存在其他优先级更高的pg_service.conf文件：

• 用户主目录下的.pg_service.conf
• 环境变量PGSERVICE指定的其他文件
  这些文件可能覆盖系统级配置，需删除或修改冲突的服务定义。

预期结果 #

• 通过my_service服务名正常建立PostgreSQL连接
• 不再抛出"服务定义未找到"错误

内容的提问来源于stack exchange，提问作者M H R