awa

Postgres-native background job queue. Transactional enqueue, heartbeat crash recovery, priority aging, retries with backoff, cron, callbacks, unique jobs, dead-letter queue, and a vacuum-aware storage engine designed to keep dead-tuple pressure bounded under sustained load.

This crate is the user-facing facade. It re-exports the worker (awa-worker) and model (awa-model) crates and is what most Rust applications depend on directly.

[dependencies]
awa = "0.6"

Quick start

use awa::{Client, JobArgs, JobContext, JobResult, QueueConfig};
use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize, JobArgs)]
struct SendEmail {
    to: String,
    subject: String,
}

async fn send_email(ctx: JobContext<SendEmail>) -> JobResult {
    println!("sending to {}: {}", ctx.args.to, ctx.args.subject);
    Ok(())
}

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let pool = sqlx::PgPool::connect(&std::env::var("DATABASE_URL")?).await?;
    let client = Client::builder(pool.clone())
        .queue("email", QueueConfig::default())
        .register_handler::<SendEmail, _, _>(send_email)
        .build()
        .await?;

    client.enqueue(SendEmail {
        to: "ada@example.com".into(),
        subject: "hello".into(),
    }).await?;

    client.start().await?;
    Ok(())
}

What you get

Transactional enqueue — enqueueing a job is a normal INSERT you can commit alongside your application's writes.
Vacuum-aware storage — append-only ready/terminal partitions plus rotating lease and receipt rings keep the hot queue tables' dead-tuple footprint bounded under sustained load. See ADR-019 and ADR-023.
Crash-safe execution — heartbeat-based lease tracking; jobs whose workers vanish are rescued automatically.
Per-queue policy — priorities, priority aging, weighted concurrency, rate limits, deadlines, retry/backoff, cron, dead-letter queue.
Unique jobs — content-keyed deduplication windowed across pending / running / completed.
Callbacks and external waits — wait for an external event without burning a worker slot.
First-class Python bindings — same engine, same SQL, same defaults; see awa-pg on PyPI.

Partitioned FIFO and ordering keys

Queues default to strict FIFO per (queue, priority). Operators can raise awa.queue_meta.enqueue_shards on a contended queue to trade strict FIFO for throughput; the contract then becomes partitioned FIFO — strict order within each shard, no ordering promised across shards. Producers can pin related jobs to the same shard with InsertOpts::ordering_key:

let opts = InsertOpts {
    queue: "customer-updates".into(),
    ordering_key: Some(format!("customer-{customer_id}").into_bytes()),
    ..Default::default()
};
client.insert_with(UpdateCustomer { ... }, opts).await?;

Jobs sharing an ordering_key always pick the same shard, so the shard's strict FIFO carries over to per-key FIFO. At enqueue_shards = 1 the key is ignored. See ADR-025 for the full contract.

Documentation

License

Dual-licensed under MIT or Apache-2.0, at your option.

awa 0.6.0-beta.1

awa

Quick start

What you get

Partitioned FIFO and ordering keys

Documentation

License