litestar-saq

Configure SAQ background job queues, cron tasks, and workers in Litestar applications.

Updated Aug 17, 2026
One-click install
npx skills add https://github.com/renjianguo666/litecms --skill litestar-saq-renjianguo666
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: litestar-saq
Source: https://github.com/renjianguo666/litecms/tree/main/.agents/skills/litestar-saq
Command: npx skills add https://github.com/renjianguo666/litecms --skill litestar-saq-renjianguo666

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires litestar-saq, and includes references (resource) components.

What problem does it solve? Adding background jobs, scheduled tasks, and async workers to a Litestar app requires wiring queues, lifespan management, DI, and CLI tooling by hand. This Skill provides the canonical patterns for integrating SAQ with Litestar via the first-party litestar-saq plugin, including broker selection and production deployment. ## Core Features & Use Cases - Plugin Setup: Configure SAQPlugin, SAQConfig, and QueueConfig with Redis or PostgreSQL brokers, plus the optional SAQ web UI. - Task & Cron Definition: Define async tasks with ctx dict, keyword-only params, timeouts, heartbeats, and CronJob scheduled work. - Enqueueing via DI: Inject TaskQueues into route handlers and enqueue jobs with deduplication keys, retries, and timeouts. - Use Case: Build a notifications API where a handler enqueues a send_email task to a default queue, while a CronJob purges expired sessions every 15 minutes, with workers running in-process during development and as a separate process in production. ## Quick Start Set up a Litestar app with litestar-saq using a default queue, an email background task, and a scheduled cleanup CronJob.

Frequently Asked Questions about litestar-saq

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add background jobs to a Litestar app?

Use the litestar-saq plugin: create an SAQPlugin with SAQConfig defining your broker DSN and QueueConfig entries listing task dotted paths. Define async tasks with ctx as the first argument, then enqueue them from handlers via injected TaskQueues.

Should I use Redis or PostgreSQL as the SAQ broker?

Pick Redis when it is already in your stack for cache or sessions, you need the SAQ web UI, or throughput exceeds 1k jobs per second. Pick PostgreSQL for PG-only deployments, moderate throughput, or transactional enqueueing alongside business data.

How do I schedule recurring cron jobs in Litestar with SAQ?

Add CronJob entries to QueueConfig.scheduled_tasks with a cron expression and an explicit timeout. CronJobs participate in retries, timeouts, and observability, so prefer them over external cron tools for work that belongs in the queue.

Why do long-running SAQ jobs get re-queued unexpectedly?

SAQ marks jobs stuck when their heartbeat timestamp goes stale. Set the heartbeat option to roughly one third of expected job duration for tasks running longer than about 30 seconds, or update the heartbeat manually from inside the task.

When should I use a custom PostgreSQL-native queue instead of SAQ?

Choose a custom TaskService plus WorkerPlugin pattern when you need pg_notify wake-ups with zero polling lag, FOR UPDATE SKIP LOCKED atomic task claiming, or execution-target routing across local, Cloud Run, and immediate modes. Otherwise SAQ with a PG broker is simpler.