Skip to content

API Reference

Most of django-celeryx is used through the Django admin rather than imported. These are the pieces you may want to call directly.

Settings

django_celeryx.settings.CeleryXSettings dataclass

Settings for django-celeryx.

All settings are configured via the CELERYX dict in Django settings::

CELERYX = {
    "CELERY_APP": "myproject.celery.app",
    "DATABASE": "celeryx",  # or any Django DATABASES alias
    ...
}

django_celeryx.settings.get_db_alias()

Get the database alias for celeryx models.

If DATABASE is not configured, auto-creates a dedicated 'celeryx' SQLite file database alongside the default database.

Task control

django_celeryx.control.tasks

Task control actions: revoke, terminate, abort, apply, rate-limit, timeout.

revoke_task(task_id, *, terminate=False, signal='SIGTERM')

Revoke a task, optionally terminating it.

abort_task(task_id)

Abort an abortable task.

apply_task(name, args=None, kwargs=None)

Send a task by name. Returns task ID.

set_rate_limit(task_name, rate, *, destination=None)

Set rate limit for a task type.

set_time_limit(task_name, *, soft=None, hard=None, destination=None)

Set time limit for a task type.

Worker control

django_celeryx.control.workers

Worker control actions: shutdown, restart pool, grow/shrink, autoscale, consumers.

reply_error(replies)

Return the first error a worker reported, or None if all replies are ok.

Control commands are broadcasts. Without reply=True a command that the worker rejects (shrinking a busy pool, for example) looks like a success.

shutdown_worker(hostname)

Shutdown a worker.

pool_restart(hostname)

Restart a worker's pool.

pool_grow(hostname, n=1)

Grow a worker's pool by n processes.

pool_shrink(hostname, n=1)

Shrink a worker's pool by n processes.

autoscale(hostname, max_concurrency, min_concurrency)

Set autoscale limits for a worker.

add_consumer(hostname, queue)

Add a queue consumer to a worker.

cancel_consumer(hostname, queue)

Cancel a queue consumer from a worker.

Event listener

django_celeryx.state.events.start_event_listener()

Start the event listener thread (idempotent).

django_celeryx.state.events.stop_event_listener(timeout=5.0)

Stop the event listener thread and wait for it to finish.

Persistence

django_celeryx.state.persistence.cleanup_old_tasks()

Delete tasks older than MAX_TASK_AGE and enforce MAX_TASK_COUNT. Returns count deleted.

django_celeryx.state.persistence.ensure_tables()

Migrate the auto-configured SQLite database on startup.

This only runs for the dedicated celeryx.sqlite3 database that the package creates for you. When CELERYX["DATABASE"] names one of your own aliases, migrating is your job::

python manage.py migrate django_celeryx --database=<alias>

Migrating a shared database from AppConfig.ready() would run once per worker process on every boot, which races and can deadlock on backends that take DDL locks.

Metrics

django_celeryx.metrics.metrics_view(request)

Django view that serves Prometheus metrics in text format.