PgQueuer v1.0 releases

PGQueuer v0.24.0 — breaking release 💥

Overview
v0.24.0 adds per-job metadata via a new headers column. This requires a one-time database migration before upgrading.

🔴 Breaking Change: New headers column

• What: Adds a headers JSONB column to the queue table and a matching Job.headers field.

• Why: Enables arbitrary key/value metadata on jobs.

• Impact if skipped:

  • The application will fail to start because the column is missing.
  • Enqueues/dequeues that specify headers will raise errors.

🛠 Migration Guide

1. Automatic upgrade (recommended)
   Run the built-in CLI upgrade command:

   pgqueuer upgrade
   

   This will execute an ALTER TABLE similar to:

   ALTER TABLE pgqueuer ADD COLUMN IF NOT EXISTS headers JSONB;
   

2. Manual migration
   If you manage migrations yourself, apply the above ALTER TABLE in your migration tool of choice before deploying the new code.

3. Rollback
   If you must revert to v0.23.x, drop the column or ignore it—older versions will simply not use it:

   ALTER TABLE pgqueuer DROP COLUMN headers;
   

✨ New

• Per-job headers via enqueue(..., headers=…) and Job.headers. (#429)

• Drain benchmark strategy

  python3 tools/benchmark.py --strategy drain --jobs 50000 --dequeue 5 --dequeue-batch-size 10
  

  Enqueues a fixed number of jobs and measures time to empty the queue. (#423)

✨ Improvements

• Heartbeats fire twice as often to avoid premature retries (#431)
• tools/benchmark.py refactored into a strategy pattern (ThroughputSettings, DrainSettings) (#422)
• timeout_with_jitter now validates span bounds and raises on invalid input (#c7241bf)

🐛 Bug Fixes

• Jobs are no longer retried while still running (#431)
• Retry tests stabilised and simplified (#431)

🧪 Testing & CI

• Removed redundant @pytest.mark.asyncio decorators (#432)
• Removed icecream debug prints from tests (#c7241bf)
• CI benchmarks both throughput and drain strategies (#423)
• Added test_heartbeat_keeps_buffer_ticking (#431)

📝 Documentation

| Area | Change | PR |
| ------------ | ------------------------------------------------------- | ---- |
| Architecture | Added job-status lifecycle section with Mermaid diagram | #421 |
| Benchmark | Documented drain strategy in docs/benchmark.md | #423 |

House-keeping

• Streamlined imports, added -> None hints, introduced nullcontext in tests (#432)
• Benchmark artifact commit messages now include the strategy name (#423)

Thanks to @AntonKarabaza for reporting #430 – your detailed report made the fix possible!

Full Changelog: https://github.com/janbjorge/pgqueuer/compare/v0.23.2...v0.24.0