soniq 0.0.1__tar.gz

soniq-0.0.1/CHANGELOG.md

@@ -0,0 +1,172 @@
+# Changelog
+
+All notable changes to ElephantQ will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Breaking Changes
+- `StorageBackend` protocol gained a required `reschedule_job(job_id, *, delay_seconds, attempts, reason=None)` method, used by the new `Snooze` return type. All in-tree backends (Postgres, SQLite, Memory) implement it. Any third-party backend must add an implementation; otherwise `isinstance(backend, StorageBackend)` checks fail and handlers that return `Snooze` will raise `AttributeError`.
+- Advisory-lock leader election (see below) requires Postgres in session-pooling mode. **Transaction-pooling PgBouncer deployments must either switch to session-pooling or disable the feature** - `pg_try_advisory_lock` releases between statements under transaction-pooling, making the lock unsafe. Single-writer deployments (SQLite, Memory, or a single Postgres worker) are unaffected.
+
+### Added
+- `Snooze(seconds, reason=None)` return type (`elephantq.Snooze`). Returning it from a job handler re-schedules the job without consuming a retry slot. Useful for rate-limited APIs (HTTP 429) and webhook backpressure. Capped by the new `snooze_max_seconds` setting (default `86400`).
+- `retry_jitter` parameter on `@elephantq.job` (default `True`). Applies full-jitter to the exponential backoff when `retry_backoff=True`, sampling uniformly in `[computed/2, computed]` to prevent thundering-herd retries after batch failures. Set `retry_jitter=False` for deterministic timing.
+- `elephantq/core/leadership.py`: `advisory_key(name)` (blake2b-derived, cross-process stable) and `with_advisory_lock(backend, name)` async context manager. Backends without native support fall through to always-leader mode.
+- `PostgresBackend.with_advisory_lock(name)`: session-scoped `pg_try_advisory_lock` on a dedicated connection for the lifetime of the context.
+- `examples/snooze_on_rate_limit.py`: HTTP 429 demo wiring `Snooze` to `Retry-After`.
+
+### Changed
+- Exponential backoff (`retry_backoff=True`) now applies full-jitter by default. Jobs that depended on deterministic retry timing will see delays uniformly sampled in `[computed/2, computed]`. Set `retry_jitter=False` on the `@elephantq.job` decorator to restore the previous behavior.
+- `Worker._maybe_cleanup` (pruner + stale-worker rescuer) and `EnhancedRecurringScheduler._scheduler_loop` now run under an advisory-lock leader guard. Multi-worker deployments stop duplicating maintenance work N times per tick. Single-worker deployments see no change. The per-job optimistic lock in `_claim_and_advance_run` remains the correctness floor for recurring job claims.
+
+### Fixed
+- Removed orphan `asyncio.create_task(db_handler.setup_database())` call in `LoggingConfig.setup_enterprise_logging`. The target was a no-op, so the task never did anything; dropping it also eliminates a warning about an un-awaited coroutine when logging is configured synchronously.
+
+### Added (tests)
+- `tests/unit/test_no_orphan_tasks.py`: AST-walk guard against new orphan `asyncio.create_task` / `asyncio.ensure_future` calls.
+- `tests/integration/test_dead_letter_recursion.py`: bounded-time regression coverage for the `_rows_affected` recursion fix.
+- `tests/integration/test_schedule_builder_race.py`: 50-way concurrent-enqueue test pinning the `JobScheduleBuilder` dedup_key contract.
+- `tests/unit/test_no_depends_on.py`: expanded to `hasattr`, direct-import `ImportError`, and `__all__` assertions so the removed `depends_on` API cannot silently return.
+- `tests/unit/test_retry_backoff.py`: full-jitter bounds, RNG injection, and `retry_max_delay` cap under jitter.
+- `tests/unit/test_advisory_key.py` + `tests/integration/test_leader_election.py`: key stability across processes and exclusive-leader semantics under concurrent holders.
+- `tests/unit/test_snooze.py` + `tests/integration/test_snooze_postgres.py`: Snooze requeue path, attempts roll-back, cap enforcement, and end-to-end Postgres flow.
+### Fixed
+- Removed orphan `asyncio.create_task(db_handler.setup_database())` call in `LoggingConfig.setup_enterprise_logging`. The target was a no-op, so the task never did anything; dropping it also eliminates a warning about an un-awaited coroutine when logging is configured synchronously.
+
+### Added
+- `tests/unit/test_no_orphan_tasks.py`: AST-walk guard that fails if any new bare expression-statement `asyncio.create_task(...)` / `asyncio.ensure_future(...)` call is introduced in the package. Existing call sites store or track their tasks and remain allowed.
+- `tests/integration/test_dead_letter_recursion.py`: bounded-time regression coverage for the `_rows_affected` recursion fix across the `delete`, `bulk_delete`, and `move` paths of `DeadLetterManager`.
+- `tests/integration/test_schedule_builder_race.py`: pins the documented `JobScheduleBuilder` dedup_key contract under 50-way concurrent `enqueue()` - exactly one row, all callers receive the winning job id.
+- `tests/unit/test_no_depends_on.py`: additional assertions (`hasattr`, direct-import `ImportError`, `__all__`) to ensure the already-removed `depends_on` API cannot be silently reintroduced.
+
+## [0.3.0] - 2026-03-27
+
+### Architecture
+- **Pluggable storage backends** — `StorageBackend` Protocol with PostgreSQL, SQLite, and Memory implementations
+- **Auto-detection** — backend selected automatically from `database_url` (`.db` → SQLite, `postgresql://` → Postgres)
+- **Worker extraction** — `elephantq/worker.py` extracted from `client.py` (-247 lines)
+- **Three-tier test architecture** — smoke/unit/functional/integration with proper conftest isolation
+
+### Added
+- `PostgresBackend` — all SQL extracted from inline code into dedicated backend
+- `SQLiteBackend` — zero-setup local development (`pip install elephantq[sqlite]`)
+- `MemoryBackend` — in-memory backend for unit tests (zero external deps)
+- `@elephantq.periodic(cron="...", every_minutes=N)` — first-class decorator for recurring jobs
+- `JobContext` — runtime metadata injection for running jobs (`ctx: JobContext`)
+- `queueing_lock` parameter for flexible job deduplication
+- `elephantq.reset()` — test fixture cleanup via backend
+- Module discovery: auto `sys.path` fix, multi-module support, batch error reporting
+- Clean import paths: `from elephantq import every, cron` (no more `elephantq.features.X`)
+- `docs/backends.md`, `docs/agents.md`
+
+### Removed
+- `depends_on()` — experimental, unimplemented in worker
+- `EnterpriseFeatures` / `enterprise` aliases
+- All legacy/backward-compat code and comments
+- Legacy Fernet decryption path
+
+### Changed
+- Multi-scheduler safety via optimistic locking (`_claim_and_advance_run`)
+- Getting-started docs lead with SQLite (zero-setup) instead of requiring PostgreSQL
+- CI split into unit+sqlite (no Postgres) and integration (real Postgres) jobs
+
+## [0.2.0] - 2026-03-24
+
+### Breaking Changes
+- Default `job_timeout` changed from `None` (no timeout) to `300` seconds. Jobs exceeding 5 minutes are now treated as failures. Override per-job with `@elephantq.job(timeout=None)` or globally with `ELEPHANTQ_JOB_TIMEOUT=0`.
+- All timestamp columns normalized to `TIMESTAMP WITH TIME ZONE` in the base migration files.
+- Removed `EnterpriseFeatures` and `enterprise` aliases from `elephantq.features`.
+
+### Fixed
+- Fixed fragile error classification that silently dead-lettered retryable jobs when error messages contained "argument" or "parameter"
+- Fixed broken `examples/recurring_jobs.py` (used non-existent API)
+- Fixed broken `examples/transactional_enqueue.py` (passed unsupported arg to `setup()`)
+- Fixed LISTEN connection leak in worker loop (connection acquired outside try block)
+- Fixed `ELEPHANTQ_SKIP_UPDATE_LOCK` env var now only honored in debug/testing mode
+- Replaced 11 dead `docs.elephantq.dev` URLs with GitHub doc links
+
+### Added
+- Default 300-second job execution timeout with per-job override via `@elephantq.job(timeout=N)`
+- `py.typed` marker for PEP 561 type checker support
+- `init` callback on instance connection pool for UTC timezone initialization
+- End-to-end crash recovery tests
+- Concurrent dequeue race condition tests
+- Timeout enforcement tests
+- Connection pool exhaustion tests
+- Missing job handler tests
+- Example import smoke tests in CI
+- Coverage reporting in CI
+- mypy configuration and CI integration
+- Dead URL regression guard in CI
+
+### Changed
+- `list_jobs` default limit harmonized to 100 across all API entry points
+- Simplified `features/features.py` imports (35 aliased imports replaced with deferred module imports)
+- Per-query `SET timezone = 'UTC'` removed from processor (now handled by pool init callback)
+
+### Documentation
+- Added job timeout documentation to retries.md and getting-started.md
+- Rewrote stuck-job-recovery.md to document automatic heartbeat-based recovery
+- Added `__all__` exports to `features/recurring.py`
+
+## [Unreleased]
+
+### Fixed
+- Fixed infinite recursion in `dead_letter.py` `_rows_affected()` that crashed all dead letter operations
+- Fixed fire-and-forget `create_task()` calls in recurring.py that caused silent data loss
+- Fixed non-atomic state update in recurring job execution (in-memory updated before DB write)
+- Fixed `datetime.now()` without timezone in health.py
+- Fixed logging handler holding asyncio lock during database I/O
+- Removed unnecessary `async` from `high_priority()`, `background()`, `urgent()` convenience functions
+- Added experimental warning to `depends_on()` (dependency enforcement not yet implemented in worker)
+- Capped webhook response body reads at 4KB to prevent OOM
+- Added backpressure to webhook delivery queue (maxsize=1000)
+
+### Changed
+- Moved `_rows_affected()` to shared `elephantq/db/helpers.py` (deduplicated from 3 files)
+- Moved `croniter`, `aiohttp`, `structlog`, `cryptography` from core deps to optional extras
+- Core install now only requires `asyncpg`, `pydantic`, `pydantic-settings`
+- Refactored `process_jobs` and `process_jobs_with_registry` to share common logic
+- Replaced O(n) metrics lookup with O(1) dict index
+- Increased PBKDF2 iterations from 100k to 310k (NIST 2023 recommendation)
+- Moved dependencies table DDL from inline runtime creation to migration 004
+
+### Added
+- Migration 004: composite index on (queue, status, priority, scheduled_at) for the hottest query
+- Migration 004: `elephantq_job_dependencies` table (previously created inline)
+- GitHub Actions CI workflows for tests, linting, and PyPI publishing
+- At-least-once delivery semantics documented in getting-started, retries, production, and transactional-enqueue docs
+- Idempotency guidance added to docs
+- CHANGELOG.md
+
+### Documentation
+- Fixed false "exactly-once delivery" claim in transactional-enqueue docs
+- Marked `depends_on()` as experimental in docs/features.md and docs/scheduling.md
+- Added delivery semantics and idempotency sections across docs
+
+## [0.1.1] - 2025-05-01
+
+### Fixed
+- Fixed SQL injection vectors and TOCTOU race conditions
+- Fixed timezone bugs and memory leaks
+- Fixed zombie job handling and secret key leak
+- Replaced hardcoded PBKDF2 salt with random salt
+
+## [0.1.0] - 2025-04-15
+
+### Added
+- Initial release
+- PostgreSQL-backed async job queue with SKIP LOCKED
+- Transactional enqueue support
+- Retry engine with fixed, exponential, and per-attempt delays
+- Dead letter queue management
+- Worker heartbeat and stale worker recovery
+- Job scheduling with fluent builder API
+- Recurring jobs with cron and interval support
+- Webhook notifications for job lifecycle events
+- CLI for setup, worker management, and job inspection
+- Optional FastAPI dashboard
+- Health checks and metrics collection

soniq-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abhinav Saxena
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

soniq-0.0.1/MANIFEST.in

@@ -0,0 +1,16 @@
+# Include migration SQL files
+recursive-include elephantq/db/migrations *.sql
+
+# Include license and readme
+include LICENSE
+include README.md
+include CHANGELOG.md
+
+# Exclude test files, examples, and deployment configs
+exclude tests/
+exclude examples/
+exclude deployment/
+exclude jobs/
+exclude quickstart_test/
+exclude run_tests.py
+exclude release.py

soniq-0.0.1/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: soniq
+Version: 0.0.1
+Summary: ElephantQ - PostgreSQL-only async job queue - built for developer happiness.
+Author-email: Abhinav Saxena <abhinav@apiclabs.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/abhinavs/elephantq
+Project-URL: Repository, https://github.com/abhinavs/elephantq
+Project-URL: Documentation, https://github.com/abhinavs/elephantq/tree/main/docs
+Project-URL: Changelog, https://github.com/abhinavs/elephantq/blob/main/CHANGELOG.md
+Project-URL: Bug Tracker, https://github.com/abhinavs/elephantq/issues
+Keywords: async,job,queue,postgresql,task,redis-alternative,developer-experience,background-jobs
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: asyncpg<0.32.0,>=0.30.0
+Requires-Dist: pydantic<3.0.0,>=2.7.1
+Requires-Dist: pydantic-settings<3.0.0,>=2.0.0
+Provides-Extra: scheduling
+Requires-Dist: croniter>=1.4.0; extra == "scheduling"
+Provides-Extra: sqlite
+Requires-Dist: aiosqlite>=0.19.0; extra == "sqlite"
+Provides-Extra: webhooks
+Requires-Dist: aiohttp>=3.8.0; extra == "webhooks"
+Requires-Dist: cryptography>=3.4.0; extra == "webhooks"
+Provides-Extra: logging
+Requires-Dist: structlog>=22.0.0; extra == "logging"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: httpx>=0.24.0; extra == "dev"
+Requires-Dist: black==25.1.0; extra == "dev"
+Requires-Dist: flake8==7.1.0; extra == "dev"
+Requires-Dist: isort==6.0.1; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: pre-commit>=3.4.0; extra == "dev"
+Requires-Dist: croniter>=1.4.0; extra == "dev"
+Requires-Dist: aiohttp>=3.8.0; extra == "dev"
+Requires-Dist: aiosqlite>=0.19.0; extra == "dev"
+Requires-Dist: structlog>=22.0.0; extra == "dev"
+Requires-Dist: cryptography>=3.4.0; extra == "dev"
+Provides-Extra: dashboard
+Requires-Dist: fastapi>=0.100.0; extra == "dashboard"
+Requires-Dist: uvicorn>=0.20.0; extra == "dashboard"
+Provides-Extra: monitoring
+Requires-Dist: prometheus-client>=0.15.0; extra == "monitoring"
+Requires-Dist: psutil>=5.9.0; extra == "monitoring"
+Provides-Extra: full
+Requires-Dist: elephantq[dashboard,logging,monitoring,scheduling,sqlite,webhooks]; extra == "full"
+Dynamic: license-file
+
+# ElephantQ
+
+Background jobs for Python. Powered by the Postgres you already have.
+
+[![PyPI version](https://img.shields.io/pypi/v/elephantq)](https://pypi.org/project/elephantq/)
+[![Python versions](https://img.shields.io/pypi/pyversions/elephantq)](https://pypi.org/project/elephantq/)
+[![License](https://img.shields.io/github/license/abhinavs/elephantq)](https://github.com/abhinavs/elephantq/blob/main/LICENSE)
+[![Tests](https://img.shields.io/github/actions/workflow/status/abhinavs/elephantq/test.yml?label=tests)](https://github.com/abhinavs/elephantq/actions)
+
+## Quickstart
+
+```bash
+pip install elephantq
+```
+
+```python
+# jobs.py
+from elephantq import ElephantQ
+
+app = ElephantQ(database_url="postgresql://localhost/myapp")
+
+@app.job(max_retries=3)
+async def send_welcome(to: str):
+    print(f"Sending welcome email to {to}")
+```
+
+```python
+# enqueue from anywhere in your app
+await app.enqueue(send_welcome, to="dev@example.com")
+```
+
+```bash
+# set up tables and start processing
+elephantq setup
+elephantq start --concurrency 4
+```
+
+Four steps. Define a job, enqueue it, set up the database, start a worker.
+
+> **Local dev without Postgres?** Use SQLite: `ElephantQ(database_url='local.db')`.
+> For production, always use PostgreSQL.
+
+## Transactional enqueue
+
+Enqueue a job inside your database transaction. If the transaction rolls back, the job never existed.
+
+```python
+async with pool.acquire() as conn:
+    async with conn.transaction():
+        await conn.execute("INSERT INTO orders ...")
+        await app.enqueue(send_invoice, connection=conn, order_id=order_id)
+        # Both commit together, or neither does
+```
+
+No Redis queue can do this. Your job and your data land in the same commit. If something fails halfway through, both roll back. No stale jobs, no ghost tasks, no cleanup scripts.
+
+## Why ElephantQ
+
+Most Python job queues force you to run Redis or RabbitMQ alongside your database. That's another service to deploy, monitor, back up, and debug when things go wrong at 3am.
+
+ElephantQ uses your existing PostgreSQL. One dependency. One place your data lives. One thing to back up.
+
+| Feature             | ElephantQ | Celery         | RQ     |
+| ------------------- | --------- | -------------- | ------ |
+| No Redis dependency | Yes       | No             | No     |
+| Async native        | Yes       | Partial        | No     |
+| Transactional enq.  | Yes       | No             | No     |
+| Setup complexity    | Low       | High           | Medium |
+| Built-in dashboard  | Yes       | No (Flower)    | No     |
+| Dead-letter queue   | Yes       | No             | No     |
+
+## Features
+
+- **Retries with backoff** -- configurable delays, exponential backoff, per-attempt delay lists
+- **Dead-letter queue** -- failed jobs preserved for inspection and manual retry
+- **Job priorities** -- lower number = higher priority, processed first
+- **Scheduled jobs** -- run at a specific time or after a delay
+- **Recurring jobs** -- cron-based periodic tasks with `@app.periodic(cron="0 * * * *")`
+- **Transactional enqueue** -- atomic with your database writes
+- **Multiple queues** -- route jobs by type, run dedicated workers per queue
+- **Middleware hooks** -- `before_job`, `after_job`, `on_error` for logging, metrics, tracing
+- **Worker heartbeat** -- auto-detect crashed workers, requeue their jobs
+- **Job results** -- store and retrieve return values from completed jobs
+- **Deduplication** -- prevent duplicate jobs with `dedup_key` or `unique=True`
+- **CLI** -- `setup`, `start`, `status`, `workers`, dead-letter management
+- **Dashboard** -- web UI for monitoring queues, workers, and job state
+
+## Dashboard
+
+Monitor queues, workers, retries, and system health from a built-in web UI.
+
+```bash
+pip install elephantq[dashboard]
+elephantq dashboard
+```
+
+![ElephantQ Dashboard](https://raw.githubusercontent.com/abhinavs/elephantq/main/docs/assets/elephantq_dashboard.png)
+
+## Install
+
+```bash
+pip install elephantq              # core (Postgres backend)
+pip install elephantq[full]        # everything below
+pip install elephantq[sqlite]      # SQLite backend for local dev
+pip install elephantq[scheduling]  # cron-based recurring jobs
+pip install elephantq[dashboard]   # web dashboard
+pip install elephantq[monitoring]  # Prometheus metrics
+pip install elephantq[webhooks]    # webhook delivery + signing
+```
+
+## When NOT to use ElephantQ
+
+- **You need 10k+ jobs/sec sustained throughput.** PostgreSQL row locking has limits. Redis-backed queues like Celery or Arq are built for this.
+- **You need cross-language consumers.** ElephantQ is Python-only. If your workers are in Go or Node, use RabbitMQ or a similar broker.
+- **You're not using PostgreSQL.** The production backend requires PostgreSQL. If your stack is MySQL or MongoDB, this isn't for you.
+- **You need DAG-based workflow orchestration.** ElephantQ handles individual jobs, not pipelines. Look at Prefect or Airflow.
+
+## Documentation
+
+- [Quickstart](docs/getting-started/quickstart.md)
+- [FastAPI integration](docs/guides/fastapi.md)
+- [Jobs and concepts](docs/concepts/jobs.md)
+- [Production checklist](docs/production/checklist.md)
+- [Deployment](docs/production/deployment.md)
+- [CLI reference](docs/cli/commands.md)
+- [API reference](docs/api/elephantq.md)
+
+## License
+
+MIT

soniq-0.0.1/README.md

@@ -0,0 +1,130 @@
+# ElephantQ
+
+Background jobs for Python. Powered by the Postgres you already have.
+
+[![PyPI version](https://img.shields.io/pypi/v/elephantq)](https://pypi.org/project/elephantq/)
+[![Python versions](https://img.shields.io/pypi/pyversions/elephantq)](https://pypi.org/project/elephantq/)
+[![License](https://img.shields.io/github/license/abhinavs/elephantq)](https://github.com/abhinavs/elephantq/blob/main/LICENSE)
+[![Tests](https://img.shields.io/github/actions/workflow/status/abhinavs/elephantq/test.yml?label=tests)](https://github.com/abhinavs/elephantq/actions)
+
+## Quickstart
+
+```bash
+pip install elephantq
+```
+
+```python
+# jobs.py
+from elephantq import ElephantQ
+
+app = ElephantQ(database_url="postgresql://localhost/myapp")
+
+@app.job(max_retries=3)
+async def send_welcome(to: str):
+    print(f"Sending welcome email to {to}")
+```
+
+```python
+# enqueue from anywhere in your app
+await app.enqueue(send_welcome, to="dev@example.com")
+```
+
+```bash
+# set up tables and start processing
+elephantq setup
+elephantq start --concurrency 4
+```
+
+Four steps. Define a job, enqueue it, set up the database, start a worker.
+
+> **Local dev without Postgres?** Use SQLite: `ElephantQ(database_url='local.db')`.
+> For production, always use PostgreSQL.
+
+## Transactional enqueue
+
+Enqueue a job inside your database transaction. If the transaction rolls back, the job never existed.
+
+```python
+async with pool.acquire() as conn:
+    async with conn.transaction():
+        await conn.execute("INSERT INTO orders ...")
+        await app.enqueue(send_invoice, connection=conn, order_id=order_id)
+        # Both commit together, or neither does
+```
+
+No Redis queue can do this. Your job and your data land in the same commit. If something fails halfway through, both roll back. No stale jobs, no ghost tasks, no cleanup scripts.
+
+## Why ElephantQ
+
+Most Python job queues force you to run Redis or RabbitMQ alongside your database. That's another service to deploy, monitor, back up, and debug when things go wrong at 3am.
+
+ElephantQ uses your existing PostgreSQL. One dependency. One place your data lives. One thing to back up.
+
+| Feature             | ElephantQ | Celery         | RQ     |
+| ------------------- | --------- | -------------- | ------ |
+| No Redis dependency | Yes       | No             | No     |
+| Async native        | Yes       | Partial        | No     |
+| Transactional enq.  | Yes       | No             | No     |
+| Setup complexity    | Low       | High           | Medium |
+| Built-in dashboard  | Yes       | No (Flower)    | No     |
+| Dead-letter queue   | Yes       | No             | No     |
+
+## Features
+
+- **Retries with backoff** -- configurable delays, exponential backoff, per-attempt delay lists
+- **Dead-letter queue** -- failed jobs preserved for inspection and manual retry
+- **Job priorities** -- lower number = higher priority, processed first
+- **Scheduled jobs** -- run at a specific time or after a delay
+- **Recurring jobs** -- cron-based periodic tasks with `@app.periodic(cron="0 * * * *")`
+- **Transactional enqueue** -- atomic with your database writes
+- **Multiple queues** -- route jobs by type, run dedicated workers per queue
+- **Middleware hooks** -- `before_job`, `after_job`, `on_error` for logging, metrics, tracing
+- **Worker heartbeat** -- auto-detect crashed workers, requeue their jobs
+- **Job results** -- store and retrieve return values from completed jobs
+- **Deduplication** -- prevent duplicate jobs with `dedup_key` or `unique=True`
+- **CLI** -- `setup`, `start`, `status`, `workers`, dead-letter management
+- **Dashboard** -- web UI for monitoring queues, workers, and job state
+
+## Dashboard
+
+Monitor queues, workers, retries, and system health from a built-in web UI.
+
+```bash
+pip install elephantq[dashboard]
+elephantq dashboard
+```
+
+![ElephantQ Dashboard](https://raw.githubusercontent.com/abhinavs/elephantq/main/docs/assets/elephantq_dashboard.png)
+
+## Install
+
+```bash
+pip install elephantq              # core (Postgres backend)
+pip install elephantq[full]        # everything below
+pip install elephantq[sqlite]      # SQLite backend for local dev
+pip install elephantq[scheduling]  # cron-based recurring jobs
+pip install elephantq[dashboard]   # web dashboard
+pip install elephantq[monitoring]  # Prometheus metrics
+pip install elephantq[webhooks]    # webhook delivery + signing
+```
+
+## When NOT to use ElephantQ
+
+- **You need 10k+ jobs/sec sustained throughput.** PostgreSQL row locking has limits. Redis-backed queues like Celery or Arq are built for this.
+- **You need cross-language consumers.** ElephantQ is Python-only. If your workers are in Go or Node, use RabbitMQ or a similar broker.
+- **You're not using PostgreSQL.** The production backend requires PostgreSQL. If your stack is MySQL or MongoDB, this isn't for you.
+- **You need DAG-based workflow orchestration.** ElephantQ handles individual jobs, not pipelines. Look at Prefect or Airflow.
+
+## Documentation
+
+- [Quickstart](docs/getting-started/quickstart.md)
+- [FastAPI integration](docs/guides/fastapi.md)
+- [Jobs and concepts](docs/concepts/jobs.md)
+- [Production checklist](docs/production/checklist.md)
+- [Deployment](docs/production/deployment.md)
+- [CLI reference](docs/cli/commands.md)
+- [API reference](docs/api/elephantq.md)
+
+## License
+
+MIT