Configuration

Backend Configuration

Configure your task backend in Django settings using the TASKS dictionary.

Database Backend

INSTALLED_APPS = [
    # ...
    "django_vtasks",
    "django_vtasks.db",  # Required for Database backend
]

TASKS = {
    "default": {
        "BACKEND": "django_vtasks.backends.db.DatabaseTaskBackend",
    }
}

Database Compatibility

The Database backend relies on SELECT ... FOR UPDATE SKIP LOCKED for efficient parallel processing. SQLite and older MySQL versions don't support this, limiting them to one worker at a time.

Valkey Backend

INSTALLED_APPS = [
    # ...
    "django_vtasks",
]

TASKS = {
    "default": {
        "BACKEND": "django_vtasks.backends.valkey.ValkeyTaskBackend",
        "OPTIONS": {
            "BROKER_URL": "valkey://localhost:6379/0",
            # Optional: Timeout for blocking operations (default: 1.0)
            "BLOCKING_TIMEOUT": 1.0,
        }
    }
}

BLOCKING_TIMEOUT is the maximum wait time when queues are idle. Tasks that arrive are processed immediately regardless of this value.

• Production: 1.0 second (default) - only 1 Redis request per second per worker when idle
• Testing: Use 0.1 seconds for faster test execution

Shared Cache Connection

If you use a compatible cache backend like django-vcache, share connections to minimize resource usage:

CACHES = {
    "default": {
        "BACKEND": "django_vcache.backend.ValkeyCache",
        "LOCATION": "valkey://localhost:6379/1",
    },
}

TASKS = {
    "default": {
        "BACKEND": "django_vtasks.backends.valkey.ValkeyTaskBackend",
        "OPTIONS": {
            "cache_alias": "default",
        }
    }
}

Shared Connection Pool

For applications using valkey-py directly, share an existing connection pool:

import valkey.asyncio as valkey

MY_APP_VALKEY_POOL = valkey.ConnectionPool.from_url("valkey://localhost:6379/0")

TASKS = {
    "default": {
        "BACKEND": "django_vtasks.backends.valkey.ValkeyTaskBackend",
        "OPTIONS": {
            "CONNECTION_POOL": MY_APP_VALKEY_POOL,
            # Still required for synchronous operations like task.enqueue()
            "BROKER_URL": "valkey://localhost:6379/0",
        }
    }
}

Settings Reference

Setting	Default	Description
VTASKS_QUEUES	["default"]	Queue names the worker should process
VTASKS_CONCURRENCY	20	Maximum concurrent tasks per worker
VTASKS_BATCH_QUEUES	{}	Batch queue configuration (see Guide)
VTASKS_RUN_SCHEDULER	True	Whether to run the scheduler when requested
VTASKS_SCHEDULE	{}	Periodic task schedules
VTASKS_COMPRESS_THRESHOLD	1024	Bytes threshold for Zstandard compression
VTASKS_DLQ_CAP	1000	Maximum failed tasks in Dead Letter Queue
VTASKS_VALKEY_PREFIX	"vt"	Prefix for Valkey keys (namespace isolation)
VTASKS_METRICS_PORT	None	Port for Prometheus metrics (standalone workers)
VTASKS_HEALTH_CHECK_FILE	None	Path to file touched for liveness probes
VTASKS_WORKER_ID	None	Custom worker ID (defaults to hostname:pid)
VTASKS_BACKEND	"default"	The alias in TASKS to use for the worker

Worker Command Arguments

Most arguments can also be set via environment variables:

Argument	Environment Variable	Django Setting
--concurrency	VTASKS_CONCURRENCY	VTASKS_CONCURRENCY
--backend	VTASKS_BACKEND	VTASKS_BACKEND
--id	VTASKS_WORKER_ID	VTASKS_WORKER_ID
--health-check-file	VTASKS_HEALTH_CHECK_FILE	VTASKS_HEALTH_CHECK_FILE
--metrics-port	VTASKS_METRICS_PORT	VTASKS_METRICS_PORT

Batch Queue Configuration

Configure batch queues in VTASKS_BATCH_QUEUES:

VTASKS_BATCH_QUEUES = {
    "batch_queue": {
        "count": 100,    # Max number of tasks to batch together
        "timeout": 5.0,  # Max seconds to wait for tasks
    }
}

Periodic Task Configuration

Define scheduled tasks in VTASKS_SCHEDULE:

from django_vtasks.scheduler import crontab

VTASKS_SCHEDULE = {
    "daily_report": {
        "task": "myapp.tasks.generate_report",
        "schedule": crontab(hour=5, minute=0),
    },
    "hourly_cleanup": {
        "task": "myapp.tasks.cleanup",
        "schedule": 3600,  # Every hour (in seconds)
    },
}