# AWA > Postgres-native background jobs for Rust and Python, with durable job state and transactional enqueue. These links are curated for agents. Each target is the Markdown representation of the corresponding documentation page. ## Home - [Home](index.md): AWA is a Postgres-native job queue for Rust and Python. Enqueue work in the same transaction as your application data, then run durable workers with retries, scheduling, progress, callbacks, and crash recovery. ## Start - [Choose a client](start/index.md): All AWA clients use the same PostgreSQL schema and job model. Choose by where the code runs, not by a separate server protocol. - [Rust](getting-started-rust/index.md): This guide takes you from cargo add to a job reaching completed. - [Python](getting-started-python/index.md): This guide takes you from uv init to a job reaching completed. - [CLI](start/cli/index.md): The awa command runs migrations, inspects and administers queues, and can host the optional web dashboard. ## Concepts - [How AWA works](concepts/index.md): AWA is a library and schema, not a separate broker service. Producers, workers, and operational tools coordinate through PostgreSQL. - [Job lifecycle](concepts/job-lifecycle/index.md): A job moves through durable states in PostgreSQL. The handler returns the next outcome; AWA validates that the current worker still owns the claim before applying it. - [Transactional enqueue](concepts/transactional-enqueue/index.md): The central reason to keep AWA in PostgreSQL is atomic handoff. An application write and the job that follows it can commit together. - [Architecture](architecture/index.md): Awa (Māori: river) is a Postgres-native background job queue for Rust and Python. Postgres is the sole infrastructure dependency: there is no Redis, RabbitMQ, sidecar scheduler, or separate lease store. Producers enqueue inside ordinary. - [Queue storage](queue-storage-substrate/index.md): Queue storage is Awa's PostgreSQL layout for runnable work, in-flight attempts, deferred work, terminal history, and the small control tables that coordinate workers. It is an implementation boundary, not an application API: producers and. ## Guides - [Guide index](guides/index.md): Use these guides once a quickstart is running. - [Bridge adapters](bridge-adapters/index.md): Insert Awa jobs within existing transactions from non-sqlx Postgres libraries. - [Lifecycle hooks](lifecycle-hooks/index.md): Lifecycle hooks let application code react to the points in a job's life — when it starts, finishes, retries, parks on an external callback, and so on — without putting that logic inside the job handler itself. Typical uses are metrics. - [HTTP callbacks](http-callbacks/index.md): Awa has two callback-related surfaces. - [Callback receivers](callback-receivers/index.md): Awa supports three ways to host the HTTP callback ingress surface. - [Dead-letter queue](dead-letter-queue/index.md): The Dead Letter Queue (DLQ) holds jobs that have exhausted all of their retry attempts. It is the recovery surface for terminal failures: an operator can inspect what failed, decide whether the underlying problem has been fixed, and either. ## Operations - [Operations index](operations/index.md): AWA keeps its control plane in PostgreSQL, so safe operation begins with database privileges, migrations, compatibility, and observability. - [Configuration](configuration/index.md): AWA has three configuration surfaces: the Rust runtime (ClientBuilder + QueueConfig), the Python runtime (client.start()), and the CLI (awa serve, awa job, etc). This guide explains how they work rather than listing every option — use. - [Deployment](deployment/index.md): This guide covers how to deploy Awa workers and the web UI with Docker or Kubernetes. - [Managed Postgres](deploying-on-managed-postgres/index.md): This page collects the operational gotchas and sizing data we learned running awa workers against Google Cloud SQL and AlloyDB in staging. Most of it applies to any managed Postgres (Amazon RDS / Aurora, Azure Database for PostgreSQL. - [Migration overview](migrations/index.md): This guide explains how to install and upgrade the Awa schema, integrate an external migration runner, and plan rollback. Release-specific prerequisites and transition procedures live in the relevant upgrade guide. - [Upgrade 0.5 to 0.6](upgrade-0.5-to-0.6/index.md): This is the operator-facing source of truth for moving an existing 0.5.x cluster to 0.6 (queue-storage-by-default). It defines the pre-flight, rollout phases, rollback boundary, and health checks; Migrations covers the general migration. - [Upgrade 0.6 to 0.7](upgrade-0.6-to-0.7/index.md): The 0.6 → 0.7 upgrade is short: the storage step is "be finalized." Everything else in 0.7 is additive. - [Observability](grafana/index.md): Two dashboards are provided. - [Troubleshooting](troubleshooting/index.md): This guide covers the operational issues that come up most often in practice: stuck running jobs, leader-election delays, and heartbeat timeouts. ## Security - [Security overview](security/index.md): Awa's security boundary has two parts: PostgreSQL privileges determine who can read or mutate queue state, while network placement and callback authentication determine which HTTP surfaces are reachable. Production deployments should. - [Database roles](security/database-roles/index.md): AWA can run with one database user, but production deployments should separate schema management from runtime execution. - [Deployable surfaces](security/deployable-surfaces/index.md): Awa ships one binary, but its runtime surfaces have different trust boundaries. Production deployments should not expose them all on one listener. - [Callback security](security/callback-security/index.md): The callback receiver exposes state-changing endpoints for externally executed attempts. ## Reference - [Reference index](reference/index.md): These pages map AWA's public surfaces without duplicating the versioned reference generated from source. - [CLI commands](reference/cli/index.md): The CLI is the migration and operations surface for AWA. The command itself is the exact reference for the installed version. - [Rust crates](reference/rust/index.md): The workspace separates storage and runtime concerns so producers do not need to carry a worker runtime. - [Python API](reference/python/index.md): Install awa-pg for the Python clients and worker runtime. - [Stability policy](stability/index.md): Awa is consumed through several distinct surfaces. This document states, per surface, what is covered by a compatibility promise, what is explicitly internal, and what each release type may change. Anything not listed here is internal and. - [Architecture decisions](adr/index.md): Each file in this directory captures a single architectural decision — its context, the decision itself, the alternatives considered, and the consequences. ADRs are written when a decision has a non-obvious rationale, trades off across. ## Contributing - [Contributing index](contributing/index.md): AWA's runtime behavior is backed by code tests, PostgreSQL integration tests, compatibility matrices, benchmarks, and TLA+ models. Changes should update the evidence at the same boundary they change. - [Development](development/index.md): This page is a short orientation for contributors building Awa locally. Release procedure, migration-author checklists, and CI policy are maintained in the repository's contributor files and workflow definitions because they change with. - [Benchmarking](benchmarking/index.md): This document captures the benchmark harnesses used in the repo and a few reference results from named development and comparison environments. ## Optional - [GitHub repository](https://github.com/hardbyte/awa): Source code, issues, releases, and repository-only contributor material.