Django连接PostgreSQL报未设置UTC错误 已有方案无效如何解决

1. 先核对基础配置项 #

绝大多数这类报错都是基础配置写错导致的，先对照检查settings.py里的两类配置：

• 确认USE_TZ = True，不要误关Django的时区支持开关；TIME_ZONE参数为应用层展示所用时区，可以按需设置为本地时区（比如Asia/Shanghai），这个参数不会影响数据库连接的时区设置，不需要强制改成UTC。
• 检查DATABASES配置块的OPTIONS字段，不要手动添加timezone相关的自定义参数，Django在USE_TZ=True时会自动给PostgreSQL连接设置UTC时区，手动传入其他时区参数会直接触发校验报错。
  正确配置参考：

  USE_TZ = True
  TIME_ZONE = "Asia/Shanghai"
  
  DATABASES = {
      "default": {
          "ENGINE": "django.db.backends.postgresql",
          "NAME": "your_db_name",
          "USER": "your_db_user",
          "PASSWORD": "your_db_password",
          "HOST": "127.0.0.1",
          "PORT": "5432",
          # 无特殊需求不要在此处追加自定义timezone配置
      }
  }
  

2. 排查PostgreSQL账号级时区配置 #

常规方案很少提服务端配置的影响：如果Django使用的数据库账号单独设置了非UTC的默认时区，会覆盖Django的连接初始化设置。

• 用超级账号连入PostgreSQL命令行，执行以下语句给Django所用账号单独设置连接默认时区，不需要修改全局时区配置影响其他业务：

  ALTER ROLE your_django_user SET timezone TO 'UTC';
  

• 执行完成后，彻底杀掉所有现存Django进程、清空数据库连接缓存后重启服务，不要依赖开发服务器的热重载，热重载不会重置已经建立的旧连接。

3. 排查第三方组件的兼容问题 #

如果改完基础配置还是报错，基本都是第三方组件干扰了连接初始化逻辑：

• 先排查数据库连接池类依赖：比如django-postgrespool、django-db-connection-pool这类插件的旧版本，不会继承Django默认的时区设置逻辑，新建连接时会跳过UTC时区设置步骤直接触发报错。可以临时注释掉连接池配置，切回Django原生PostgreSQL后端测试，如果切回后报错消失，升级连接池插件到适配当前Django版本的最新版即可。
• 排查自定义逻辑：检查项目中有没有通过信号、中间件、自定义数据库后端手动修改连接时区的代码，比如手动执行SET TIME ZONE 'XXX'的SQL语句，这类代码会直接篡改连接时区触发校验。
• 排查驱动版本兼容问题：如果用的是psycopg3（版本号>=3.0），Django 4.2以下的版本对psycopg3的时区校验存在已知兼容bug，要么把psycopg降级到2.9.x稳定版，要么把Django升级到4.2以上LTS版本即可解决。

4. 兜底强制修复方案 #

以上排查都做完仍未解决的，可以通过Django内置的连接创建信号，在每个新连接建立时强制设置UTC时区，从根源上绕过校验问题：
在项目任意已注册App的apps.py的ready()方法中添加以下代码：

from django.db.backends.signals import connection_created

def force_utc_connection(sender, connection, **kwargs):
    if connection.vendor == "postgresql":
        with connection.cursor() as cur:
            cur.execute("SET TIME ZONE 'UTC';")

connection_created.connect(force_utc_connection)

添加完成后彻底重启服务即可生效。

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