Quickstart

Learn how to use Supabase Queues to add and read messages

This guide is an introduction to interacting with Supabase Queues via the Dashboard and official client library. Check out Queues API Reference for more details on our API.

Concepts#

Supabase Queues is a pull-based Message Queue consisting of three main components: Queues, Messages, and Queue Types.

Pull-Based Queue#

A pull-based Queue is a Message storage and delivery system where consumers actively fetch Messages when they're ready to process them - similar to constantly refreshing a webpage to display the latest updates. Our pull-based Queues process Messages in a First-In-First-Out (FIFO) manner without priority levels.

Message#

A Message in a Queue is a JSON object that is stored until a consumer explicitly processes and removes it, like a task waiting in a to-do list until someone checks and completes it.

Queue types#

Supabase Queues offers three types of Queues:

• Basic Queue: A durable Queue that stores Messages in a logged table.
• Unlogged Queue: A transient Queue that stores Messages in an unlogged table for better performance but may result in loss of Queue Messages.

Create Queues#

To get started, navigate to the Supabase Queues Postgres Module under Integrations in the Dashboard and enable the pgmq extension.

On the Queues page:

• Click Create queue button

• Name your queue

• Select your Queue Type
• We recommend leaving Row Level Security (RLS) enabled. With it enabled, you don't need to set additional RLS on the queue tables.

Expose Queues to client-side consumers#

Queues, by default, are not exposed over the Supabase Data API and are only accessible via Postgres clients.

However, you may grant client-side consumers access to your Queues by enabling the Supabase Data API and granting permissions to the Queues API, which is a collection of database functions in the pgmq_public schema that wraps the database functions in the pgmq schema.

This is to prevent direct access to the pgmq schema and its tables (RLS is not enabled by default on any tables) and database functions.

To get started, navigate to the Queues > Settings section of the Dashboard and enable Expose Queues via PostgREST. Once enabled, Supabase creates and exposes a pgmq_public schema containing database function wrappers to a subset of pgmq's database functions.

Add an RLS policy on your tables in pgmq#

If you expose your pgmq schema with the Data API, for security purposes, you must enable Row Level Security (RLS) on all Queue tables (all tables in pgmq schema that begin with q_)

Add an RLS policy for any Queues you want your client-side consumers to interact with, by clicking the Add RLS Policy button on the overview page of any Queue in the Dashboard.

Grant permissions to pgmq_public database functions#

On top of enabling RLS and writing RLS policies on the underlying Queue tables, you must grant the correct permissions to the pgmq_public database functions for each Data API role.

The permissions required for each Queue API database function:

To manage your queue permissions, click on the Queue Settings cog button on the overview page of any Queue in the Dashboard.

Then enable the required roles permissions.

Enqueueing and dequeueing messages#

Once you have created your Queue, you can begin enqueueing and dequeueing Messages.

1
import { createClient } from '@supabase/supabase-js'
2
3
const supabaseUrl = 'supabaseURL'
4
const supabaseKey = 'supabaseKey'
5
6
const supabase = createClient(supabaseUrl, supabaseKey)
7
8
const QueuesTest: React.FC = () => {
9
  //Add a Message
10
  const sendToQueue = async () => {
11
    const result = await supabase.schema('pgmq_public').rpc('send', {
12
      queue_name: 'foo',
13
      message: { hello: 'world' },
14
      sleep_seconds: 30,
15
    })
16
    console.log(result)
17
  }
18
19
  //Dequeue Message
20
  const popFromQueue = async () => {
21
    const result = await supabase.schema('pgmq_public').rpc('pop', { queue_name: 'foo' })
22
    console.log(result)
23
  }
24
25
  return (
26
    <div className="p-6">
27
      <h2 className="text-2xl font-bold mb-4">Queue Test Component</h2>
28
      <button
29
        onClick={sendToQueue}
30
        className="bg-blue-500 text-white px-4 py-2 rounded-sm hover:bg-blue-600 mr-4"
31
      >
32
        Add Message
33
      </button>
34
      <button
35
        onClick={popFromQueue}
36
        className="bg-blue-500 text-white px-4 py-2 rounded-sm hover:bg-blue-600"
37
      >
38
        Pop Message
39
      </button>
40
    </div>
41
  )
42
}
43
44
export default QueuesTest