Django 5.0+ 中 PostgreSQL 数据库后端配置的正确写法-Python教程-PHP中文网

Django 5.0+ 中 PostgreSQL 数据库后端配置的正确写法

Django 5.0 及以上版本已移除 django.db.backends.postgresql 别名，必须使用标准后端路径 django.db.backends.postgresql_psycopg2，否则会触发 ModuleNotFoundError 或 ImproperlyConfigured 异常。

django 5.0 及以上版本已移除 `django.db.backends.postgresql` 别名，必须使用标准后端路径 `django.db.backends.postgresql_psycopg2`，否则会触发 `modulenotfounderror` 或 `improperlyconfigured` 异常。

在 Django 5.0 版本中（包括你当前使用的 5.0.4），官方正式废弃了旧版别名 django.db.backends.postgresql。该字符串曾作为 postgresql_psycopg2 的兼容别名存在，但在 Django 5.0 中已被完全移除。因此，即使 PostgreSQL 服务正常运行、psycopg2 已正确安装，只要 settings.py 中的 DATABASES['default']['ENGINE'] 仍设为 'django.db.backends.postgresql'，就会报错：

django.core.exceptions.ImproperlyConfigured: 
'django.db.backends.postgresql' isn't an available database backend...

✅ 正确配置方式如下（settings.py）：

Django

避免常见的 Django 错误——QuerySet 评估、N+1 查询、迁移冲突和 ORM 陷阱。

下载

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql_psycopg2',  # ✅ 唯一有效值
        'NAME': 'your_db_name',
        'USER': 'your_db_user',
        'PASSWORD': 'your_password',
        'HOST': 'localhost',
        'PORT': '5432',
    }
}

⚠️ 注意事项：

不要尝试降级 Django 或修改源码来“恢复”别名——这是有意为之的向后不兼容变更，旨在统一命名并明确依赖 psycopg2；
确保已安装 psycopg2-binary（开发环境推荐）或 psycopg2（生产环境建议从源码编译）：
```
pip install psycopg2-binary
```
Ubuntu 24.04 默认 Python 版本为 3.12，需确认 psycopg2-binary 兼容性（截至 Django 5.0.4，psycopg2-binary>=2.9.7 支持 Python 3.12）；
若使用 django-environ 或环境变量动态配置，也请同步更新 ENGINE 的值，避免硬编码遗留问题。

? 小贴士：Django 官方文档已同步更新，所有 PostgreSQL 示例均使用 postgresql_psycopg2 —— 这是当前唯一受支持的 PostgreSQL 后端标识符，无其他变体。务必检查项目中所有配置入口（如多数据库、测试配置、CI 脚本等），确保全面替换。