asyncq
Type-safe background jobs for Rust. Define once with #[derive(Job)], run anywhere.
[]
= "0.1"
= "0.1" # Redis backend (recommended for production)
# asyncq-postgres = "0.1" # PostgreSQL backend — no Redis needed
= { = "1", = ["derive"] }
= { = "1", = ["full"] }
Note:
#[derive(Job)]comes fromasyncqdirectly — you do not need to addasyncq-deriveas a separate dependency.
Why asyncq?
Most Rust job queues copy the Tower/Service pattern — you write boilerplate for every job type. asyncq takes a different approach: derive macros with compile-time validation.
// asyncq — define your job, implement perform, done
Compare to apalis (Tower-based):
// apalis — define job, define service, define layer, wire builder
async
new
.layer
.layer
.source
.build_fn
asyncq moves configuration to the type level — retries, timeouts, and queue names are part of the job definition, not runtime wiring. Typos become compile errors.
Quick start
use ;
use RedisBackend;
use ;
async
Features
State injection
Pass app state once at startup. Access via ctx.state::<T>() — same pattern as axum.
let pool = new;
let queue = new.with_state;
Scheduling
queue.enqueue.await?; // now
queue.enqueue_in.await?; // 1 hour
queue.enqueue_at.await?; // tomorrow
Cron scheduling
Run jobs on a recurring schedule:
use Scheduler;
;
let scheduler = new
. // every day at 9am
.; // every Sunday at midnight
// Run alongside your worker
select!
Cron format: second minute hour day-of-month month day-of-week
Error handling
Backoff is exponential: 30s × 2^attempt, capped at 1 hour.
Job attributes
Worker options
new
.
.
.concurrency // concurrent jobs
.queues // priority order
.stuck_timeout // requeue stuck jobs
.run
.await;
Graceful shutdown
worker.run_graceful.await;
Dead-letter queue
let dead = queue.dead_jobs.await?;
queue.retry_dead.await?; // retry one
queue.retry_all_dead.await?; // retry all
Queue stats
let stats = queue.stats.await?;
println!;
Architecture
asyncq itself defines the job model (Job, Perform, Worker, Queue<B>)
and is generic over a storage Backend. A backend crate (Redis or Postgres)
implements that trait to give you durable storage; an integration crate
(axum or actix-web) mounts an admin API on top of the same Queue<B> your
worker uses. Enqueue and worker processes both talk to the same backend, so
they can be the same binary or split across services.
flowchart LR
subgraph App["Your application"]
Producer["Producer<br/>queue.enqueue(job)"]
WorkerNode["Worker<br/>register + run()"]
end
subgraph Core["asyncq (core)"]
QueueT["Queue<B><br/>generic over Backend"]
JobTrait["Job / Perform / JobContext"]
end
subgraph Store["Storage backend (pick one)"]
Redis["asyncq-redis<br/>ZSET + LIST"]
Postgres["asyncq-postgres<br/>SKIP LOCKED"]
end
subgraph Admin["Framework integration (optional)"]
Axum["asyncq-axum<br/>admin_with_queues()"]
Actix["asyncq-actix<br/>admin_with_queues()"]
end
Producer -->|enqueue / enqueue_in / enqueue_at| QueueT
QueueT -->|claim / ack / nack| Redis
QueueT -->|claim / ack / nack| Postgres
Redis -->|pending jobs| WorkerNode
Postgres -->|pending jobs| WorkerNode
WorkerNode -->|perform| JobTrait
QueueT -. stats / dlq / retry .-> Axum
QueueT -. stats / dlq / retry .-> Actix
Enqueue writes a job record into the backend; the worker polls (or blocks on)
the same backend to claim jobs, executes Perform::perform, and acks or
retries/dead-letters on failure. The admin crates read and mutate that same
Queue<B> over HTTP — they don't add a second source of truth.
Backends and integrations
| Crate | Use case |
|---|---|
asyncq-redis |
Production Redis backend — fast, battle-tested |
asyncq-postgres |
PostgreSQL — no Redis needed, transactional outbox |
asyncq-axum |
Axum admin API + live Prometheus metrics |
asyncq-actix |
Actix-web admin API + live Prometheus metrics |
PostgreSQL + transactional outbox
Enqueue jobs in the same transaction as your business logic — if the transaction rolls back, so does the job.
use PostgresBackend;
let backend = new.await?;
backend.migrate.await?; // creates asyncq_jobs table
let mut tx = pool.begin.await?;
query.execute.await?;
backend.enqueue_in_tx.await?;
tx.commit.await?; // job visible only after commit
Admin API (asyncq-axum / asyncq-actix)
Mount admin endpoints to inspect and manage your queues in production.
Axum:
use admin_with_queues;
use Router;
let app = new
.nest;
Actix-web:
use admin_with_queues;
use ;
new
.service;
| Endpoint | Description |
|---|---|
GET /queues/:name |
Queue stats (pending, running, dead) |
GET /queues/:name/dlq |
Dead jobs (paginated: ?limit=50&offset=0) |
POST /queues/:name/dlq/retry-all |
Requeue all dead jobs |
DELETE /queues/:name/dlq/:id |
Retry one dead job by ID |
GET /metrics |
Live Prometheus gauges per queue |
Prometheus output (with admin_with_queues):
asyncq_jobs_pending{queue="emails"} 3
asyncq_jobs_running{queue="emails"} 1
asyncq_jobs_dead{queue="emails"} 0
asyncq_jobs_completed{queue="emails"} 142
Testing
Use InMemoryBackend — no Redis required:
async
run_once() processes all pending jobs and returns — no Ctrl-C needed.
Feature flags
asyncq ships with the scheduler feature enabled by default. To opt out of the cron dependency (e.g., serverless environments where you never use Scheduler):
= { = "0.1", = false }
Roadmap
- Cron scheduling —
Scheduler::register::<Job>("0 0 9 * * *") - Actix-web integration —
asyncq-actixadmin API + Prometheus metrics - Live Prometheus metrics —
admin_with_queuesexposes per-queue gauges - Unique jobs — deduplicate by payload hash
- Middleware — before/after hooks
- Rate limiting — per-queue throttling
- Job chains —
JobA.then(JobB).then(JobC)
Changelog
0.1.6
- Add
asyncq-actix— actix-web admin API with the same endpoints asasyncq-axum - Add
admin_with_queuesto both axum and actix integrations — live Prometheus gauges per queue - Make
crondependency optional viaschedulerfeature (default on, zero breakage) - Improve keywords across all crates for better crates.io discovery
- Fix
asyncq-postgresdescription to highlight "no Redis needed"
0.1.5
- Admin REST API via
asyncq-axum— stats, DLQ, retry, metrics endpoints - PostgreSQL backend with
SELECT FOR UPDATE SKIP LOCKED enqueue_in_tx— transactional outbox for PostgreSQL
0.1.4
- Cron scheduling via
Scheduler—register::<Job>("0 0 9 * * *") enqueue_in,enqueue_at— delayed and scheduled jobs- Redis ZSET-based delayed job promotion
0.1.0
- Initial release:
#[derive(Job)]API, Redis backend,InMemoryBackendfor tests Worker::run_oncefor infrastructure-free testing- State injection via
Queue::with_state+ctx.state::<T>() - DLQ with
retry_dead/retry_all_dead
License
MIT OR Apache-2.0