tenant-schemas-celery

4.0.3 verified Mon Apr 27 auth: no python

Celery integration for django-tenant-schemas and django-tenants. Automatically sets the schema on Celery task invocations so that tasks run in the correct tenant context. Current version is 4.0.3, supporting Python >=3.9. Release cadence is irregular, with major versions aligned with Django or Celery breaking changes.

pip install tenant-schemas-celery

Common errors

error ImportError: cannot import name 'CeleryApp' from 'tenant_schemas_celery' ↓

cause CeleryApp is in the `app` submodule, not the package root.

fix

Use from tenant_schemas_celery.app import CeleryApp.

error AttributeError: 'CeleryApp' object has no attribute 'Task' ↓

cause In versions <3.0.0, the Task class was not exposed. Users might have used `app.Task` incorrectly.

fix

Upgrade to 3.0.0+ or use from tenant_schemas_celery.task import TenantTask explicitly.

error RuntimeError: No schema name set in task headers. Task will run in public schema. ↓

cause Tasks were sent without a tenant schema header, possibly from outside a tenant context or using send_task without passing headers.

fix

Always call tasks within a tenant context (e.g., using connection.set_tenant()) or pass headers manually via apply_async(headers={'X-Django-Schema': 'your_schema'}).

error TypeError: CeleryApp() got an unexpected keyword argument 'task_cls' ↓

cause In versions <3.0.0, `task_cls` was not a parameter for CeleryApp.

fix

Upgrade to 3.0.0+ to pass task_cls, or set the Task class after instantiation: app.Task = MyCustomTask.

Warnings

breaking Version 4.0.0 dropped support for django-tenant-schemas (legacy) and Python <3.9. If you need the old package, pin to <4.0.0. ↓

fix Upgrade to 4.0.0+ and use django-tenants instead of django-tenant-schemas.

breaking Version 3.0.0 introduced a custom task class via CeleryApp overriding the default Task class. If you have custom task base classes, they may not be applied unless you set the Task class explicitly. ↓

fix Use app.Task to inherit tenant schema support in custom tasks, or set app.Task = YourCustomTask in CeleryApp.

deprecated Using `from tenant_schemas_celery import CeleryApp` is deprecated and will be removed. Import from the `app` submodule instead. ↓

fix Replace with `from tenant_schemas_celery.app import CeleryApp`.

gotcha If you use `app.send_task()`, the tenant schema is set correctly. However, tasks called via `.delay()` or `.apply_async()` from outside a tenant context (e.g., in a management command) will fail if no active schema is set. ↓

fix Ensure tasks are called from within a tenant context (e.g., inside a view or with `tenant_context()`) or manually set the schema.

gotcha When using Celery Beat with django-celery-beat, the scheduler must be configured to use the tenant-schemas-celery scheduler to run tasks in the correct tenant context. ↓

fix Set `CELERY_BEAT_SCHEDULER = 'tenant_schemas_celery.schedulers.TenantAwareScheduler'` in Django settings.

Imports

CeleryApp

wrong

from tenant_schemas_celery import CeleryApp

correct

from tenant_schemas_celery.app import CeleryApp

CeleryApp is in the app submodule, not directly in the package root.

Quickstart

Create a Celery app instance that automatically manages tenant schema context. Replace 'your_project' with your Django project name.

import os
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'your_project.settings')

from tenant_schemas_celery.app import CeleryApp

app = CeleryApp('your_project')
app.config_from_object('django.conf:settings', namespace='CELERY')
app.autodiscover_tasks()