diff --git a/apps/docs/content/guides/queues/quickstart.mdx b/apps/docs/content/guides/queues/quickstart.mdx index 58af639d01c..ce44b7fda84 100644 --- a/apps/docs/content/guides/queues/quickstart.mdx +++ b/apps/docs/content/guides/queues/quickstart.mdx @@ -3,7 +3,6 @@ title: Quickstart subtitle: '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](/docs/guides/queues/api) for more details on our API. ## Concepts @@ -25,8 +24,6 @@ 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. -- **Partitioned Queue** (_Coming Soon_): A durable and scalable Queue that stores Messages in multiple table partitions for better performance. - ## Create Queues To get started, navigate to the [Supabase Queues](/dashboard/project/_/integrations/queues/overview) Postgres Module under Integrations in the Dashboard and enable the `pgmq` extension. @@ -40,8 +37,8 @@ To get started, navigate to the [Supabase Queues](/dashboard/project/_/integrati Supabase Dashboard Integrations page, showing the Queues Postgres Module - -If you've already created a Queue click the **Create a queue** button instead. - - +- Click **Create queue** button - Name your queue - + Queue names can only be lowercase and hyphens and underscores are permitted. - Select your [Queue Type](#queue-types) +- We recommend leaving Row Level Security (RLS) enabled. With it enabled, you don't need to set additional RLS on the queue tables. Create a Queue from the Supabase Dashboard -### What happens when you create a queue? + Every new Queue creates two tables in the `pgmq` schema. These tables are `pgmq.q_` to store and process active messages and `pgmq.a_` to store any archived messages. -A "Basic Queue" will create `pgmq.q_` and `pgmq.a_` tables as logged tables. +A "Basic Queue" creates `pgmq.q_` and `pgmq.a_` tables as logged tables. -However, an "Unlogged Queue" will create `pgmq.q_` as an unlogged table for better performance while sacrificing durability. The `pgmq.a_` table will still be created as a logged table so your archived messages remain safe and secure. +However, an "Unlogged Queue" creates `pgmq.q_` as an unlogged table for better performance while sacrificing durability. The `pgmq.a_` table is still created as a logged table so your archived messages remain safe and secure. + + ## Expose Queues to client-side consumers -Queues, by default, are not exposed over Supabase Data API and are only accessible via Postgres clients. +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 page](/dashboard/project/_/integrations/queues/settings) and toggle on “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. +To get started, navigate to the [**Queues > Settings**](/dashboard/project/_/integrations/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. -Screenshot of Queues settings with toggle to expose to PostgREST +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_`) -### Enable RLS on your tables in `pgmq` schema - -For security purposes, you must enable Row Level Security (RLS) on all Queue tables (all tables in `pgmq` schema that begin with `q_`) if the Data API is enabled. - -You’ll want to create RLS policies for any Queues you want your client-side consumers to interact with. - -Screenshot of creating an RLS policy from the Queues settings +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](/dashboard/project/_/integrations/queues/queues). ### Grant permissions to `pgmq_public` database functions @@ -139,13 +111,13 @@ The permissions required for each Queue API database function: | `read` `pop` | `Select` `Update` | | `archive` `delete` | `Select` `Delete` | -To manage your queue permissions, click on the Queue Settings button. +To manage your queue permissions, click on the Queue Settings cog button on [the overview page of any Queue in the Dashboard](/dashboard/project/_/integrations/queues/queues). Screenshot of accessing queue settings + - - -`postgres` and `service_role` roles should never be exposed client-side. +You should never expose `postgres` and `service_role` roles client-side. ### Enqueueing and dequeueing messages -Once your Queue has been created, you can begin enqueueing and dequeueing Messages. +Once you have created your Queue, you can begin enqueueing and dequeueing Messages.