sql-job-queue — SKILL.md

Variant: standard · When to use: the skill is invoked, produces a working DB-backed ready-set scheduler (or the relevant slice of one) on SQLAlchemy 2.x, and control returns to the caller.

Overview

This skill teaches an agent to build a DB-backed ready-set job scheduler on SQLAlchemy 2.x — a thin tick loop you own, where the relational database is the only durable substrate (no broker, no second source of truth) and a job becomes runnable as its dependencies finish. It is for long-running, stateful jobs whose concurrency is capped by external limits (resources / rate / budget), running on a single box as an embeddable library, portable across SQLite, PostgreSQL, and MySQL. The load-bearing content is the per-dialect atomic lease — SELECT ... FOR UPDATE SKIP LOCKED on PostgreSQL and MySQL 8+ vs a BEGIN IMMEDIATE write-lock claim on SQLite — and the crash-resume / fair-share / idempotency patterns layered on top of it. It is sync-first: the worked path is synchronous, async is a short aside. It builds on the sqlalchemy sibling's data layer and locking primitive — it does not re-teach them.

When to activate

• ✅ Building an embeddable, single-box work queue whose readiness is dependency-driven (a DAG of jobs, each runnable once its upstreams are done), persisted in a relational DB, portable across SQLite/PostgreSQL/MySQL.
• ✅ Composing the atomic claim that stops two workers (processes / threads / async tasks) on one box from dispatching the same job — and needing the per-dialect branch.
• ✅ Making the queue crash-safe with no broker — heartbeat, lease expiry, stale-lease reclaim, and bounding a hung job.
• ✅ Allocating slots across job groups by weighted fair-share, or building the scan→rank→lease→dispatch→persist→reclaim tick loop.

Do NOT activate when: