asyncq
Async background job processing for Rust. Like Sidekiq, but with a derive macro.
[]
= "0.1"
= "0.1"
= { = "1", = ["derive"] }
Why asyncq?
Every other Rust job queue makes you write boilerplate for every job type. asyncq uses a derive macro instead:
// asyncq — one attribute, done
// apalis — tower::Service boilerplate per job type
new
.layer
.source
.build_fn
Quick start
use ;
use RedisBackend;
use ;
// 1. Define your job
// 2. Implement the work
async
Shared state (database pool, config, etc.)
Pass your app state once at startup. Jobs access it via ctx.state::<T>() — the same pattern as axum's State<T>.
use Arc;
use PgPool;
let pool = new;
// Attach state to the queue
let queue = new.with_state;
// Access it inside any job
Scheduling
use Duration;
use Utc;
// Run immediately
queue.enqueue.await?;
// Run after a delay
queue.enqueue_in.await?;
// Run at a specific time
queue.enqueue_at.await?;
Error handling
Return Ok(()) to mark a job complete. Return Err to retry. Return JobError::discard to skip retries and send directly to the dead-letter queue.
use ;
Retry backoff is exponential: 30s × 2^attempt, capped at 1 hour.
Job attributes
Worker options
new
.
.
.
.concurrency // concurrent jobs (default: 10)
.queues // explicit priority order
.stuck_timeout // reset jobs stuck > 120s (default)
.run
.await;
Graceful shutdown
// Stop cleanly on Ctrl-C — current batch completes before exit
worker.run_graceful.await;
Dead-letter queue
// List dead jobs
let dead = queue.dead_jobs.await?;
// Retry one
queue.retry_dead.await?;
// Retry all
let requeued = queue.retry_all_dead.await?;
println!;
Queue stats
let stats = queue.stats.await?;
println!;
PostgreSQL backend (asyncq-postgres)
Use PostgreSQL as the job store — no Redis required. Supports the transactional outbox pattern.
[]
= "0.1"
use ;
use PostgresBackend;
let backend = new.await?;
backend.migrate.await?; // creates asyncq_jobs table — safe to call on every startup
let queue = new;
queue.enqueue.await?;
new..run.await;
Transactional outbox
Enqueue a job inside the same DB transaction as your business logic. The job is only visible to workers after tx.commit().
use Utc;
let mut tx = pool.begin.await?;
query.execute.await?;
backend.enqueue_in_tx.await?;
tx.commit.await?; // job becomes visible here — rolls back if this fails
Admin UI (asyncq-axum)
Mount the admin router to get REST endpoints and Prometheus metrics:
[]
= "0.1"
use admin;
use Router;
let app = new
.nest
/* ... your routes ... */;
| Method | Path | Description |
|---|---|---|
| GET | /admin/queues/:name |
Stats (pending, running, dead) |
| GET | /admin/queues/:name/dlq |
List dead-letter jobs (paginated) |
| POST | /admin/queues/:name/dlq/retry-all |
Requeue all dead jobs |
| DELETE | /admin/queues/:name/dlq/:id |
Retry one dead job |
| GET | /admin/metrics |
Prometheus text format |
Backends
| Crate | Backend | Status |
|---|---|---|
asyncq-redis |
Redis | ✅ stable |
asyncq-postgres |
PostgreSQL (transactional outbox) | ✅ stable |
asyncq-axum |
Admin router + Prometheus | ✅ stable |
Testing without Redis
Use InMemoryBackend in tests — no external infrastructure required:
use ;
async
with_immediate_retries() makes retried jobs immediately claimable, so you can test retry cycles without sleeping.
Running examples
# Start Redis
# Basic example
# With state (shared DB pool pattern)
License
MIT OR Apache-2.0