Pre-release

This release is a pre-release and may not be stable for production use.

awa-cli

Command-line interface for the Awa Postgres-native job queue. Run migrations, inspect and manage jobs, walk the storage transition, drive the Dead Letter Queue, list cron schedules, and serve the web admin UI.

Install

The CLI is shipped as both a Rust binary and a Python wheel. Either distribution gives you the same awa executable, including the embedded React admin dashboard for awa serve.

# Python (no Rust toolchain needed)
pip install awa-cli

# Rust
cargo install awa-cli

If you're already using the awa-pg Python SDK, install both with one command:

pip install 'awa-pg[ui]'

That pulls in awa-cli as a dependency so python -m awa serve works end-to-end alongside the worker SDK.

Quick start

# Run migrations
awa --database-url $DATABASE_URL migrate

# Inspect
awa --database-url $DATABASE_URL queue stats
awa --database-url $DATABASE_URL job list --state failed
awa --database-url $DATABASE_URL job dump 12345
awa --database-url $DATABASE_URL job dump-run 12345

# Admin
awa --database-url $DATABASE_URL job retry 12345
awa --database-url $DATABASE_URL queue pause email
awa --database-url $DATABASE_URL queue drain email

# Web UI
awa --database-url $DATABASE_URL serve
# → http://127.0.0.1:3000

DATABASE_URL may be passed as the --database-url flag or read from the environment.

Commands

Command Description
migrate Apply migrations, or extract / print SQL with --sql / --extract-to
job list List jobs with --state / --kind / --queue filters
job dump <id> Pretty-print one job and its full lifecycle metadata
job dump-run <id> [--attempt N] Pretty-print one attempt run
job retry <id> Retry a failed or cancelled job
job cancel <id> Cancel a job
job retry-failed (--kind K | --queue Q) Retry every failed job matching exactly one filter
job discard --kind K Delete every failed job of a given kind
queue stats Per-queue depth, lag, and throughput
queue pause / resume / drain <queue> Queue admin
cron list / remove List or remove cron schedules
dlq depth [--queue Q] Total DLQ rows, optionally split by queue
dlq list List DLQ entries with --kind / --queue / --tag / --before-* filters
dlq retry <id> Retry a single DLQ row
dlq retry-bulk Retry every DLQ row matching the filter (--all required if no filter is given)
dlq move Move existing failed terminal rows into the DLQ
dlq purge Delete DLQ rows matching the filter (--all required if no filter is given)
storage status Current storage-transition state
storage prepare --engine E Prepare a future storage engine without changing routing
storage prepare-queue-storage-schema Materialize the queue-storage schema (tables, indexes, functions)
storage enter-mixed-transition Begin routing new writes to the prepared engine
storage finalize Finalize the transition once drain and capability gates pass
storage abort Abort a prepared or mixed-transition rollout
serve Start the embedded web admin UI

Run awa <command> --help for the flags on any subcommand.

Storage transition

For an existing 0.5.x cluster moving to the queue-storage engine, the typical sequence is:

awa --database-url $DATABASE_URL storage prepare-queue-storage-schema
awa --database-url $DATABASE_URL storage prepare --engine queue_storage
# ... roll out a binary that supports queue storage to all workers ...
awa --database-url $DATABASE_URL storage enter-mixed-transition
# ... drain the canonical engine ...
awa --database-url $DATABASE_URL storage finalize

See docs/upgrade-0.5-to-0.6.md for the full pre-flight checklist, gate semantics, and rollback notes. Fresh installs auto-finalize on first migrate and do not need this sequence.

Dead Letter Queue

dlq retry-bulk and dlq purge require an explicit filter (--kind, --queue, or --tag) or --all. This is intentional — a bare bulk retry / purge with no filter would touch every DLQ row, which is almost never what you want. See docs/dead-letter-queue.md.

Web UI

awa serve starts an embedded admin UI (awa-ui) bound to 127.0.0.1:3000 by default. The UI is read-only when the database reports transaction_read_only = on (e.g. on a replica) or when --read-only is passed explicitly. Mutation endpoints return 503 in that mode.

License

MIT OR Apache-2.0

Project links

Data verified by PyPI on
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.6.5)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for hardbyte from gravatar.com hardbyte

Credits

Author: Brian Thorne

GitHub Statistics

Data verified by PyPI on 
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

Apache Software License, MIT License (MIT OR Apache-2.0)

Requires

Python >=3.10

Tags

job-queue postgres background-jobs cli

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

awa_cli-0.6.0rc4-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (5.6 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ x86-64

awa_cli-0.6.0rc4-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (5.4 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ ARM64

awa_cli-0.6.0rc4-py3-none-macosx_11_0_arm64.whl (5.2 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

awa_cli-0.6.0rc4-py3-none-macosx_10_12_x86_64.whl (5.4 MB view details)

Uploaded Python 3macOS 10.12+ x86-64

File details

Details for the file awa_cli-0.6.0rc4-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for awa_cli-0.6.0rc4-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 62d6eed40e02361fd5248e573e4f5305c57a902de0786ad233997c9987ffdfaa
MD5 62687443f8b178c01af9610ac7bd1400
BLAKE2b-256 ec09067f5ee67a55096b520483146e0305c1a54fe9f489794a13de098dbc4e82

See more details on using hashes here.

Provenance

The following attestation bundles were made for awa_cli-0.6.0rc4-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on hardbyte/awa

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file awa_cli-0.6.0rc4-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for awa_cli-0.6.0rc4-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 a1bff9649fcf1bdab6ddbcf79aae406889e3ca34c6c6c1e9cc9443cb88dbe503
MD5 724da91c5af9bc638bdfaf8fca57d021
BLAKE2b-256 7f03d80175e9b9acd56e5cc8d8b7742048407a6921a4228be119139a75ef22e2

See more details on using hashes here.

Provenance

The following attestation bundles were made for awa_cli-0.6.0rc4-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: release.yml on hardbyte/awa

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file awa_cli-0.6.0rc4-py3-none-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for awa_cli-0.6.0rc4-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 5b5b68c1c9ceb74f4bcb5f6f90ce33567306ff2ea8b1978d57b8b4ca1911d3a1
MD5 c369352e67445dd2a5f9c932d0293b90
BLAKE2b-256 bef039f0732145aec1c7eee80fa6880d4205cdbf2e8efdaee45cc28a5b5bd8bc

See more details on using hashes here.

Provenance

The following attestation bundles were made for awa_cli-0.6.0rc4-py3-none-macosx_11_0_arm64.whl:

Publisher: release.yml on hardbyte/awa

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file awa_cli-0.6.0rc4-py3-none-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for awa_cli-0.6.0rc4-py3-none-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 73ac5b40dfe635208f3cd795341b7b9f488e44ef4554d23c647ba843bd3c14d9
MD5 4801883a66ffcabf725f51e552cf7630
BLAKE2b-256 68a32d38d12c3599014c758a439ef72166b56c0ef882e81b393338c0ec572a52

See more details on using hashes here.

Provenance

The following attestation bundles were made for awa_cli-0.6.0rc4-py3-none-macosx_10_12_x86_64.whl:

Publisher: release.yml on hardbyte/awa

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page