# pgque-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.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 400 installs · ★ 88
- Author: reason-machines
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/reason-machines/trending-skills/tree/HEAD/skills/pgque-postgres-queue/SKILL.md
- Updated: 2026-10-09
- HTML: https://affpapa.org/en/nevibecode/skills/pgque-postgres-queue

## What it 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.

## Requirements
- Works with: PostgreSQL

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add reason-machines/trending-skills --skill pgque-postgres-queue -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/pgque-postgres-queue/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/pgque-postgres-queue/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add reason-machines/trending-skills --skill pgque-postgres-queue -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/pgque-postgres-queue/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add reason-machines/trending-skills --skill pgque-postgres-queue -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/pgque-postgres-queue/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install reason-machines/trending-skills pgque-postgres-queue
```

2. **Manually: put the files in place**
- File: `.github/skills/pgque-postgres-queue/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add reason-machines/trending-skills --skill pgque-postgres-queue -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/reason-machines/trending-skills --path skills/pgque-postgres-queue
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/pgque-postgres-queue/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add reason-machines/trending-skills --skill pgque-postgres-queue -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/reason-machines/trending-skills/tree/HEAD/skills/pgque-postgres-queue/SKILL.md

## When to use it
- 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
- 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

## Similar
- [migrating-oracle-to-postgres-stored-procedures](https://affpapa.org/en/nevibecode/skills/migrating-oracle-to-postgres-stored-procedures.md) — skill · 1800 installs
- [postgresql-code-review](https://affpapa.org/en/nevibecode/skills/postgresql-code-review.md) — skill · 12608 installs
- [prisma-postgres](https://affpapa.org/en/nevibecode/skills/prisma-postgres.md) — skill · 382300 installs
- [prisma-postgres-setup](https://affpapa.org/en/nevibecode/skills/prisma-postgres-setup.md) — skill · 376800 installs
- [neon-postgres](https://affpapa.org/en/nevibecode/skills/neondatabase-neon-postgres.md) — skill · 281100 installs
- [neon-postgres-egress-optimizer](https://affpapa.org/en/nevibecode/skills/neon-postgres-egress-optimizer.md) — skill · 29300 installs

From the same set: [reason-machines/trending-skills](https://affpapa.org/en/nevibecode/by/reason-machines/trending-skills.md) — 42 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md