Supabase pgmq Tutorial: Reliable Background Job Queues
This Supabase pgmq tutorial shows you how to build reliable background jobs: create a queue, enqueue from Flutter, drain it with an Edge Function worker, and handle poison messages with a dead-letter queue.
Background jobs done right buy you four things: work that survives app restarts, automatic retries when a provider hiccups, an audit trail of everything processed, and heavy lifting moved off the request path so your UI stays fast. Supabase Queues — powered by pgmq , the Postgres-native message queue (1.5.1 on Supabase Cloud) — gives you all four without adding Redis, BullMQ, or another service to babysit. This Supabase pgmq tutorial builds the full producer/consumer pattern: a queue, an Edge Function worker, and the dead-letter handling that quickstart guides skip. *Last updated: 2026-10-10* Supabase pgmq tutorial: what you'll build A pgmq queue created and managed from SQL A producer path: enqueue jobs from your Flutter app via a secure RPC wrapper A worker: an Edge Function that drains the queue in batches Visibility-timeout mechanics that give you at-least-once delivery A dead-letter queue that quarantines poison messages instead of retrying them forever Archive-instead-of-delete for a free audit trail If you're still setting up the stack, the complete Flutter and Supabase guide gets you running. You should be comfortable with Edge Functions in Dart and basic SQL. If your need is "run something every hour" rather than "process this job reliably," plain scheduled SQL is the simpler tool — the decision table at the end spells out the boundary. And when work should fire on row changes instead of a clock, database triggers are the event-driven alternative. Step 1: Create a queue and enqueue your first message Enable the pgmq extension under Database > Extensions (or SQL), then create a queue. A queue in pgmq is just a name — messages are JSONB rows with delivery metadata attached: create extension if not exists pgmq; -- one queue per job type keeps retries and…