使用cookiecutter-django搭建项目时Celery查询引发ProgrammingError

我之前帮朋友排查过一模一样的场景——用cookiecutter-django搭的项目，视图里查Job模型完全正常，放到Celery任务里就报ProgrammingError，PostgreSQL容器也跟着报错。大概率是Celery worker的环境初始化或数据库连接状态和主Django进程不一致导致的，给你整理了几个必查的解决步骤：

1. 确认Celery正确加载了Django环境 #

Cookiecutter-django虽然默认配置了Celery，但有时候worker启动时没正确加载Django的settings，导致数据库连接配置不对。

• 打开你的Celery配置文件（一般是config/celery.py），确认开头有这段初始化代码：

  import os
  from celery import Celery
  
  # 替换成你实际使用的settings文件，比如production或development
  os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'config.settings.production')
  app = Celery('config')
  # 从Django settings加载Celery配置，前缀是CELERY_
  app.config_from_object('django.conf:settings', namespace='CELERY')
  # 自动发现所有app里的tasks.py
  app.autodiscover_tasks()
  

• 启动worker时，一定要在项目根目录执行正确的命令，别用跳过环境加载的自定义脚本：

  celery -A config worker -l info
  

2. 确保数据库迁移在Celery worker启动前完成 #

视图能正常查询，说明主Django进程能访问到最新的表结构，但如果Celery worker是在迁移前启动的，它的数据库连接会缓存旧的表结构，自然找不到Job模型的字段。

• 先停掉所有Celery worker进程：

  pkill -f celery
  

• 重新运行数据库迁移，确保表结构是最新的：

  python manage.py migrate
  

• 最后重启Celery worker：

  celery -A config worker -l info
  

3. 检查PostgreSQL的连接权限与网络配置 #

有时候Celery worker用的数据库用户权限和主Django进程不一样，或者Docker容器网络配置有问题，导致worker无法正确访问PostgreSQL。

• 打开settings.py检查DATABASES配置，注意Docker环境下数据库主机应该是容器名（比如db），而不是localhost，并且用户名、密码和主进程完全一致：

  DATABASES = {
      'default': {
          'ENGINE': 'django.db.backends.postgresql',
          'NAME': os.environ.get('POSTGRES_DB'),
          'USER': os.environ.get('POSTGRES_USER'),
          'PASSWORD': os.environ.get('POSTGRES_PASSWORD'),
          'HOST': 'db',  # 这里是Docker容器名，不是localhost
          'PORT': '5432',
      }
  }
  

• 进入PostgreSQL容器，检查数据库用户是否有Job表的访问权限：

  docker exec -it <你的postgres容器名> psql -U <数据库用户名> <数据库名>
  # 执行这条命令查看表权限，假设你的Job模型对应的表是job_job
  \dp job_job;
  

  如果权限不足，执行SQL授权：

  GRANT ALL PRIVILEGES ON TABLE job_job TO <数据库用户名>;
  

4. 修复Celery的数据库连接泄漏问题 #

长时间运行的Celery worker可能持有过期的数据库连接，导致查询出错。可以通过配置连接池或手动刷新连接解决：

• 在config/celery.py里添加连接池和worker重启配置：

  # 限制broker连接池大小，根据你的并发量调整
  app.conf.broker_pool_limit = 10
  # 每个worker处理1000个任务后自动重启，避免连接泄漏
  app.conf.worker_max_tasks_per_child = 1000
  

• 或者在任务里手动刷新数据库连接：

  from django.db import connection
  from myapp.models import Job
  from celery import shared_task
  
  @shared_task
  def my_job_task():
      # 关闭旧连接，下次查询会自动重建新连接
      connection.close()
      # 现在执行查询就正常了
      jobs = Job.objects.all()
      # 你的业务逻辑...
  

5. 根据具体报错信息精准排查 #

如果上面的方法都没用，把具体的ProgrammingError报错内容贴出来会更高效。比如如果报错是relation "job_job" does not exist，那基本就是Celery worker没加载到最新的表结构，重启worker+重新迁移就能解决；如果是permission denied for table job_job，那就是权限问题，按步骤3处理就行。

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