pgque-postgres-queue — Claude Code skill: Postgres queue
A skill that walks you through PgQue, a snapshot-based Postgres queue written in pure PL/pgSQL. Useful when events need to move inside the database.
npx skills add reason-machines/trending-skills --skill pgque-postgres-queue -a claude-codeWhat pgque-postgres-queue does
PgQue follows the PgQ design: events land in rotating tables and batches close on a tick. There is no row-level locking, since batches are snapshots and tables are cleared with TRUNCATE. Dead tuples do not pile up. Each subscriber gets its own copy of every batch, so fan-out comes for free.
The skill covers the install path: a single SQL file, the pgque_reader, pgque_writer and pgque_admin roles, plus calls like pgque.create_queue, pgque.subscribe, pgque.send, pgque.receive, pgque.ack and pgque.nack. Producer and consumer examples use Python with psycopg2. The lower-level API is there too, including pgque.insert_event and pgque.get_batch_events.
You need Postgres 14+ and a ticker: pg_cron or an external scheduler running pgque.ticker() every second. Skip the ticker and enqueue still works, but no batches appear and consumers stay idle. Delivery takes roughly 1–2 s, which is the trade-off of the snapshot approach.
What it helps with
- run an event queue inside Postgres without C extensions
- deliver one event to several services independently
- stop dead tuples from bloating queue tables
- write a Python producer and consumer with psycopg2
- set up retries and dead-letter handling for failed batches
Example prompts for the agent
- set up PgQue in my database: create the orders queue and an order-processor subscriber
- show me how to send a new_order event with pgque.send and receive it in the consumer
- explain when to use pgque.ack versus pgque.nack for a failed order
How to install pgque-postgres-queue
1Skills CLI (Vercel)
npx skills add reason-machines/trending-skills --skill pgque-postgres-queue -a claude-code2Manually: put the files in place
~/.claude/skills/pgque-postgres-queue/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/pgque-postgres-queue/
1Skills CLI (Vercel)
npx skills add reason-machines/trending-skills --skill pgque-postgres-queue -a codex2Manually: put the files in place
.agents/skills/pgque-postgres-queue/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add reason-machines/trending-skills --skill pgque-postgres-queue -a cursor2Manually: put the files in place
.cursor/skills/pgque-postgres-queue/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install reason-machines/trending-skills pgque-postgres-queue2Manually: put the files in place
.github/skills/pgque-postgres-queue/SKILL.md1Skills CLI (Vercel)
npx skills add reason-machines/trending-skills --skill pgque-postgres-queue -a gemini-cli2Platform CLI
gemini skills install https://github.com/reason-machines/trending-skills --path skills/pgque-postgres-queueManually: put the files in place
.devin/skills/pgque-postgres-queue/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add reason-machines/trending-skills --skill pgque-postgres-queue -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about pgque-postgres-queue
How do I install pgque-postgres-queue in Claude?
Run npx skills add reason-machines/trending-skills --skill pgque-postgres-queue -a claude-code. The skill lands in ~/.claude/skills/pgque-postgres-queue/SKILL.md.
What does pgque-postgres-queue do?
It guides the agent through setting up and using PgQue, a PL/pgSQL queue built on snapshots and table rotation. It covers installation, roles, the queue API and Python examples.
What does PgQue need to run?
Postgres 14+ and a running ticker: pg_cron or an external scheduler calling pgque.ticker() once a second. Without it, no batches are created.
