A PostgreSQL-backed job queue service with HTTP API. Built for developers who want durability, inspectability, and simplicity.
| Use Case | Why OpenQueue |
|---|---|
| Need durable job storage | Jobs are rows in Postgres - query, debug, audit |
| Already using Postgres | No additional infrastructure |
| Building a SaaS | Built-in multi-tenancy with API tokens |
| Compliance needs | Full job history in relational DB |
| Simpler operations | One DB to manage |
docker compose up --buildThis starts:
openqueue-db- PostgreSQLopenqueue-api- FastAPI server (port 8000)openqueue-dashboard- Web dashboard (port 3000)
Access the dashboard at: http://localhost:3000
Features:
- Terminal-style dark interface
- Real-time queue stats with auto-refresh (30s)
- Job listing with filtering
- Job detail view
- Settings for API configuration
- Local storage caching for offline resilience
Default API token (development only):
Bearer token: oq_live_qXxA5liMxzRhz3uVTFYziaQSrw8tB05y2hU5O7VivyA
Use it:
curl -H "Authorization: Bearer oq_live_qXxA5liMxzRhz3uVTFYziaQSrw8tB05y2hU5O7VivyA" \
http://localhost:8000/dashboard/queuesfrom openqueue import OpenQueue
client = OpenQueue("http://localhost:8000", "your-token")
# Simple job
job_id = client.enqueue(
queue_name="emails",
payload={"to": "user@example.com", "subject": "Hello"}
)
# Scheduled job (run later)
job_id = client.enqueue(
queue_name="reminders",
payload={"message": "Reminder!"},
run_at="2026-01-01T09:00:00Z"
)
# Batch enqueue
job_ids = client.enqueue_batch([
{"queue_name": "emails", "payload": {"to": "a@b.com"}},
{"queue_name": "emails", "payload": {"to": "c@d.com"}, "priority": 10},
])from openqueue import OpenQueue
client = OpenQueue("http://localhost:8000", "your-token")
while True:
leased = client.lease(queue_name="emails", worker_id="worker-1")
if leased:
try:
# Process the job
payload = leased.job.payload
print(f"Processing: {payload}")
# Success
client.ack(leased.job.id, leased.lease_token, result={"done": True})
except Exception as e:
# Failure - retry
client.nack(leased.job.id, leased.lease_token, error=str(e))Refer to the below image:
- Job Priorities - Higher priority jobs are processed first
- Visibility Timeout - Auto-recovery from worker crashes
- Heartbeat - Long-running jobs stay leased
- Retry with Backoff - Exponential backoff prevents retry storms
- Dead Letter Queue - Failed jobs isolated for inspection
- Batch Operations - Enqueue multiple jobs efficiently
- Scheduled Jobs - Delay job execution with
run_at
POST /jobs- Enqueue jobGET /jobs/{id}- Get job statusGET /jobs- List jobsPOST /jobs/batch- Batch enqueuePOST /jobs/{id}/cancel- Cancel pending job
POST /queues/{name}/lease- Lease next jobPOST /jobs/{id}/ack- Acknowledge successPOST /jobs/{id}/nack- Report failurePOST /jobs/{id}/heartbeat- Extend lease
GET /dashboard/queues- Queue statistics
- Concept.md - Technical deep-dive for contributors
- BEGINNER_GUIDE.md - Architecture walkthrough
- system-design/OpenQueue-SystemDesign.excalidraw - Architecture diagram (import in excalidraw.io)
MIT