FastAPI连接PostgreSQL配置DATABASE_URL遇postgres角色不存在报错

错误根因 #

当前报错FATAL: role "postgres" does not exist说明你本地PostgreSQL数据库中没有名为postgres的默认角色，而你的配置里将postgres设为了用户名的默认值，连接时用了这个不存在的角色导致鉴权失败。

排查步骤 #

• 第一步：确认本地PostgreSQL的有效角色
  打开终端执行PostgreSQL角色查询命令：

psql -U your_default_admin_user -c "\du"

如果你不知道默认管理员用户名，可以直接通过系统用户登录（PostgreSQL默认适配系统同名用户），Mac/Linux执行：

sudo -u postgres psql -c "\du"

Windows系统打开PostgreSQL自带的SQL Shell，直接登录后执行\du即可查看所有已存在的角色列表，确认你实际可用的用户名。

• 第二步：检查环境变量配置是否生效
  你当前代码是优先读取环境变量中的myusername值，如果没有配置该环境变量才会用默认值postgres，可以在代码中临时加一行打印验证实际生效的用户名：

print("实际使用的数据库用户名：", db_username)

如果打印结果是postgres，说明你没有配置myusername的环境变量，走了默认值逻辑。

• 第三步：确认角色的登录权限和数据库访问权限
  查到可用用户名后，确认该角色有LOGIN权限，以及对你要连接的fastapi数据库有访问权限，执行SQL查询：

-- 查看角色权限
SELECT rolname, rolcanlogin FROM pg_roles WHERE rolname = '你的实际用户名';
-- 查看数据库权限
\l fastapi

解决方法 #

本地开发环境解决方案 #

两种选择二选一即可：

1. 新增postgres角色
   如果想继续用默认的postgres用户名，直接在PostgreSQL中创建该角色即可，执行SQL：

CREATE ROLE postgres WITH LOGIN PASSWORD '你设置的密码' CREATEDB;
-- 给角色分配fastapi数据库的所有权限
GRANT ALL PRIVILEGES ON DATABASE fastapi TO postgres;

2. 替换默认用户名为你本地实际存在的角色
   将代码中用户名的默认值改为你上一步查到的本地有效用户名：

# 把第二个参数'postgres'改成你实际的用户名
db_username = urllib.parse.quote_plus(str(os.environ.get('myusername', '你本地实际的用户名')))
# 同步修改密码的默认值为该用户对应的数据库密码
db_password = urllib.parse.quote_plus(str(os.environ.get('mypassword123', '你实际的密码')))

Heroku部署适配方案 #

后续部署到Heroku时不需要手动拼接DATABASE_URL，直接读取Heroku自动注入的DATABASE_URL环境变量即可，调整代码兼容两种场景：

import os
import urllib.parse

# 优先读取Heroku的DATABASE_URL环境变量
DATABASE_URL = os.environ.get('DATABASE_URL')
if not DATABASE_URL:
    # 本地开发时走自定义拼接逻辑
    host_server = os.environ.get('host_server', 'localhost')
    db_server_port = urllib.parse.quote_plus(str(os.environ.get('db_server_port', '5432')))
    database_name = os.environ.get('nameofmydatabase', 'fastapi')
    db_username = urllib.parse.quote_plus(str(os.environ.get('myusername', '你本地的有效用户名')))
    db_password = urllib.parse.quote_plus(str(os.environ.get('mypassword123', '你本地的对应密码')))
    ssl_mode = urllib.parse.quote_plus(str(os.environ.get('ssl_mode','prefer')))
    DATABASE_URL = 'postgresql://{}:{}@{}:{}/{}?sslmode={}'.format(db_username, db_password, host_server, db_server_port, database_name, ssl_mode)
# Heroku的DATABASE_URL默认前缀是postgres://，sqlalchemy 1.4+需要改为postgresql://
if DATABASE_URL.startswith("postgres://"):
    DATABASE_URL = DATABASE_URL.replace("postgres://", "postgresql://", 1)

这样本地开发和Heroku部署可以无缝切换，不需要额外修改配置。

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