Configuration
Queue profiles
Rich defaults live on taskq.queues and are stamped onto each job at enqueue:
max_attempts, lease seconds, retry backoff- default priority
- retention windows
- optional depth limit
Changing a queue profile affects future enqueues only.
The queue profile also carries the per-queue flow-control fields — in-flight
cap (max_running), rate limits (claim_rate_per_minute / claim_burst),
slow-start ramp_seconds, the circuit-breaker and priority-aging settings, and
key-space fairness via flow_limits. Unlike the fields above, these gate the
claim path rather than stamp jobs, and every one is off by default. Set them
with the operator verbs documented in Flow control.
WorkerSettings (TASKQ_*)
| Knob | Default | Notes |
|---|---|---|
dsn or http_base_url | — | Exactly one transport |
registry | required | module:attr exporting TaskRegistry |
queues | required | One or more queue names |
environment | required | Must match expected_environment when set |
worker_id | auto | Optional; CLI generates a default |
concurrency | 1 | Max in-flight handlers |
sync_workers | concurrency | Thread slots available to ctx.run_sync(...) |
batch | 1 | Claim batch size (≤ concurrency) |
poll_interval | 5 | Seconds |
listen | true | DSN only; HTTP workers must disable |
presence_interval | 60 | Seconds |
soft_stop_timeout | none | Wait forever if unset |
allow_production | false | Required when environment=production |
expected_environment | — | Optional hard check against the declared environment |
expected_installation_id | required for direct-SQL production | Static database identity pin |
http_bearer_token / header pair | — | Exactly one credential source for HTTP |
http_claim_wait_seconds | 25 | Long-poll; multi-queue HTTP requires 0 |
pool_size | concurrency+2 | DSN workers only |
CLI flags mirror these fields (taskq worker run --help). Operator connections
use secret-free named contexts; see the CLI reference.
Supervised host wrappers may instead use --dsn-env TASKQ_DSN; this passes only
the environment-variable name in process arguments and leaves the credential
in the supervisor's secret environment.
Scheduler settings (TASKQ_*)
| Knob | Default | Notes |
|---|---|---|
dsn | required | Scheduler runtime credential; keep it out of CLI history |
expected_environment / TASKQ_EXPECTED_ENV | required | Static expected target environment |
expected_installation_id | required in production | Static UUID pin from deployment configuration |
allow_production | false | Must be explicitly true for production |
worker_id | generated | Scheduler process identity used in durable decisions |
poll_interval | 5 | Seconds between continuous cycles |
jitter | 0.1 | Bounded poll jitter, from 0 to 0.5 |
backoff_cap | 30 | Maximum error backoff in seconds |
claim_limit | 10 | Schedules claimed per batch |
lease_seconds | 60 | Schedule-claim lease, from 5 to 300 seconds |
error_retry_seconds | 30 | Retry delay for scheduler evaluation errors |
pool_size | 2 | Scheduler database pool size |
The runtime never fills expected target values by reading the database. In
production it requires both TASKQ_EXPECTED_INSTALLATION_ID and
TASKQ_ALLOW_PRODUCTION=true.
See Standalone Scheduler for target binding, manifests, activation, monitoring, and rollback.