Supabase Guides

# AI & Vectors

The best vector database is the database you already have.

Supabase provides an open source toolkit for developing AI applications using Postgres and pgvector. Use the Supabase client libraries to store, index, and query your vector embeddings at scale.

The toolkit includes:

*   A [vector store](/docs/guides/ai/vector-columns) and embeddings support using Postgres and pgvector.
*   A [Python client](/docs/guides/ai/vecs-python-client) for managing unstructured embeddings.
*   An [embedding generation](/docs/guides/ai/quickstarts/generate-text-embeddings) process using open source models directly in Edge Functions.
*   [Database migrations](/docs/guides/ai/examples/headless-vector-search#prepare-your-database) for managing structured embeddings.
*   Integrations with all popular AI providers, such as [OpenAI](/docs/guides/ai/examples/openai), [Hugging Face](/docs/guides/ai/hugging-face), [LangChain](/docs/guides/ai/langchain), and more.


## Search

You can use Supabase to build different types of search features for your app, including:

*   [Semantic search](/docs/guides/ai/semantic-search): search by meaning rather than exact keywords
*   [Keyword search](/docs/guides/ai/keyword-search): search by words or phrases
*   [Hybrid search](/docs/guides/ai/hybrid-search): combine semantic search with keyword search


## Examples

Check out all of the AI [templates and examples](https://github.com/supabase/supabase/tree/master/examples/ai) in our GitHub repository.


## Integrations


## Case studies


# Automatic embeddings



Vector embeddings enable powerful [semantic search](/docs/guides/ai/semantic-search) capabilities in Postgres, but managing them alongside your content has traditionally been complex. This guide demonstrates how to automate embedding generation and updates using Supabase [Edge Functions](/docs/guides/functions), [pgmq](/docs/guides/database/extensions/pgmq), [pg\_net](/docs/guides/database/extensions/pg_net), and [pg\_cron](/docs/guides/cron).


## Understanding the challenge

When implementing semantic search with pgvector, developers typically need to:

1.  Generate embeddings via an external API (like OpenAI)
2.  Store these embeddings alongside the content
3.  Keep embeddings in sync when content changes
4.  Handle failures and retries in the embedding generation process

While Postgres [full-text search](/docs/guides/database/full-text-search) can handle this internally through synchronous calls to `to_tsvector` and [triggers](https://www.postgresql.org/docs/current/textsearch-features.html#TEXTSEARCH-UPDATE-TRIGGERS), semantic search requires asynchronous API calls to a provider like OpenAI to generate vector embeddings. This guide demonstrates how to use triggers, queues, and Supabase Edge Functions to bridge this gap.


## Understanding the architecture

We'll leverage the following Postgres and Supabase features to create the automated embedding system:

1.  [pgvector](/docs/guides/database/extensions/pgvector): Stores and queries vector embeddings
2.  [pgmq](/docs/guides/queues): Queues embedding generation requests for processing and retries
3.  [pg\_net](/docs/guides/database/extensions/pg_net): Handles asynchronous HTTP requests to Edge Functions directly from Postgres
4.  [pg\_cron](/docs/guides/cron): Automatically processes and retries embedding generations
5.  [Triggers](/docs/guides/database/postgres/triggers): Detects content changes and enqueues embedding generation requests
6.  [Edge Functions](/docs/guides/functions): Generates embeddings via an API like OpenAI (customizable)

We'll design the system to:

1.  Be generic, so that it can be used with any table and content. This allows you to configure embeddings in multiple places, each with the ability to customize the input used for embedding generation. These will all use the same queue infrastructure and Edge Function to generate the embeddings.

2.  Handle failures gracefully, by retrying failed jobs and providing detailed information about the status of each job.


## Implementation

We'll start by setting up the infrastructure needed to queue and process embedding generation requests. Then we'll create an example table with triggers to enqueue these embedding requests whenever content is inserted or updated.


### Step 1: Enable extensions

First, let's enable the required extensions:


### Step 2: Create utility functions

Before we set up our embedding logic, we need to create some utility functions:

```sql
-- Schema for utility functions
create schema util;

-- Utility function to get the Supabase project URL (required for Edge Functions)
create function util.project_url()
returns text
language plpgsql
security definer
as $$
declare
  secret_value text;
begin
  -- Retrieve the project URL from Vault
  select decrypted_secret into secret_value from vault.decrypted_secrets where name = 'project_url';
  return secret_value;
end;
$$;

-- Generic function to invoke any Edge Function
create or replace function util.invoke_edge_function(
  name text,
  body jsonb,
  timeout_milliseconds int = 5 * 60 * 1000  -- default 5 minute timeout
)
returns void
language plpgsql
as $$
declare
  headers_raw text;
  auth_header text;
begin
  -- If we're in a PostgREST session, reuse the request headers for authorization
  headers_raw := current_setting('request.headers', true);

  -- Only try to parse if headers are present
  auth_header := case
    when headers_raw is not null then
      (headers_raw::json->>'authorization')
    else
      null
  end;

  -- Perform async HTTP request to the edge function
  perform net.http_post(
    url => util.project_url() || '/functions/v1/' || name,
    headers => jsonb_build_object(
      'Content-Type', 'application/json',
      'Authorization', auth_header
    ),
    body => body,
    timeout_milliseconds => timeout_milliseconds
  );
end;
$$;

-- Generic trigger function to clear a column on update
create or replace function util.clear_column()
returns trigger
language plpgsql as $$
declare
    clear_column text := TG_ARGV[0];
begin
    NEW := NEW #= hstore(clear_column, NULL);
    return NEW;
end;
$$;
```

Here we create:

*   A schema `util` to store utility functions.
*   A function to retrieve the Supabase project URL from [Vault](/docs/guides/database/vault). We'll add this secret next.
*   A generic function to invoke any Edge Function with a given name and request body.
*   A generic trigger function to clear a column on update. This function accepts the column name as an argument and sets it to `NULL` in the `NEW` record. We'll explain how to use this function later.

Every project has a unique API URL that is required to invoke Edge Functions. Let's go ahead and add the project URL secret to Vault depending on your environment.

When working with a local Supabase stack, add the following to your `supabase/seed.sql` file:

```sql
select
  vault.create_secret('http://api.supabase.internal:8000', 'project_url');
```

When deploying to the cloud platform, open the [SQL editor](/dashboard/project/_/sql/new) and run the following, replacing `<project-url>` with your [project's API URL](/dashboard/project/_/settings/api):

```sql
select
  vault.create_secret('<project-url>', 'project_url');
```


### Step 3: Create queue and triggers

Our goal is to automatically generate embeddings whenever content is inserted or updated within a table. We can use triggers and queues to achieve this. Our approach is to automatically queue embedding jobs whenever records are inserted or updated in a table, then process them asynchronously using a cron job. If a job fails, it will remain in the queue and be retried in the next scheduled task.

First we create a `pgmq` queue for processing embedding requests:

```sql
-- Queue for processing embedding jobs
select pgmq.create('embedding_jobs');
```

Next we create a trigger function to queue embedding jobs. We'll use this function to handle both insert and update events:

```sql
-- Generic trigger function to queue embedding jobs
create or replace function util.queue_embeddings()
returns trigger
language plpgsql
as $$
declare
  content_function text = TG_ARGV[0];
  embedding_column text = TG_ARGV[1];
begin
  perform pgmq.send(
    queue_name => 'embedding_jobs',
    msg => jsonb_build_object(
      'id', NEW.id,
      'schema', TG_TABLE_SCHEMA,
      'table', TG_TABLE_NAME,
      'contentFunction', content_function,
      'embeddingColumn', embedding_column
    )
  );
  return NEW;
end;
$$;
```

Our `util.queue_embeddings` trigger function is generic and can be used with any table and content function. It accepts two arguments:

1.  `content_function`: The name of a function that returns the text content to be embedded. The function should accept a single row as input and return text (see the `embedding_input` example).

    This allows you to customize the text input passed to the embedding model - for example, you could concatenate multiple columns together like `title` and `content` and use the result as input.

2.  `embedding_column`: The name of the destination column where the embedding will be stored.

Note that the `util.queue_embeddings` trigger function requires a `for each row` clause to work correctly. See [Usage](#usage) for an example of how to use this trigger function with your table.

Next we'll create a function to process the embedding jobs. This function will read jobs from the queue, group them into batches, and invoke the Edge Function to generate embeddings. We'll use `pg_cron` to schedule this function to run every 10 seconds.

```sql
-- Function to process embedding jobs from the queue
create or replace function util.process_embeddings(
  batch_size int = 10,
  max_requests int = 10,
  timeout_milliseconds int = 5 * 60 * 1000 -- default 5 minute timeout
)
returns void
language plpgsql
as $$
declare
  job_batches jsonb[];
  batch jsonb;
begin
  with
    -- First get jobs and assign batch numbers
    numbered_jobs as (
      select
        message || jsonb_build_object('jobId', msg_id) as job_info,
        (row_number() over (order by 1) - 1) / batch_size as batch_num
      from pgmq.read(
        queue_name => 'embedding_jobs',
        vt => timeout_milliseconds / 1000,
        qty => max_requests * batch_size
      )
    ),
    -- Then group jobs into batches
    batched_jobs as (
      select
        jsonb_agg(job_info) as batch_array,
        batch_num
      from numbered_jobs
      group by batch_num
    )
  -- Finally aggregate all batches into array
  select array_agg(batch_array)
  from batched_jobs
  into job_batches;

  -- Invoke the embed edge function for each batch
  foreach batch in array job_batches loop
    perform util.invoke_edge_function(
      name => 'embed',
      body => batch,
      timeout_milliseconds => timeout_milliseconds
    );
  end loop;
end;
$$;

-- Schedule the embedding processing
select
  cron.schedule(
    'process-embeddings',
    '10 seconds',
    $$
    select util.process_embeddings();
    $$
  );
```

Let's discuss some common questions about this approach:


#### Why not generate all embeddings in a single Edge Function request?

While this is possible, it can lead to long processing times and potential timeouts. Batching allows us to process multiple embeddings concurrently and handle failures more effectively.


#### Why not one request per row?

This approach can lead to API rate limiting and performance issues. Batching provides a balance between efficiency and reliability.


#### Why queue requests instead of processing them immediately?

Queuing allows us to handle failures gracefully, retry requests, and manage concurrency more effectively. Specifically we are using `pgmq`'s visibility timeouts to ensure that failed requests are retried.


#### How do visibility timeouts work?

Every time we read a message from the queue, we set a visibility timeout which tells `pgmq` to hide the message from other readers for a certain period. If the Edge Function fails to process the message within this period, the message becomes visible again and will be retried by the next scheduled task.


#### How do we handle retries?

We use `pg_cron` to schedule a task that reads messages from the queue and processes them. If the Edge Function fails to process a message, it becomes visible again after a timeout and can be retried by the next scheduled task.


#### Is 10 seconds a good interval for processing?

This interval is a good starting point, but you may need to adjust it based on your workload and the time it takes to generate embeddings. You can adjust the `batch_size`, `max_requests`, and `timeout_milliseconds` parameters to optimize performance.


### Step 4: Create the Edge Function

Finally we'll create the Edge Function to generate embeddings. We'll use OpenAI's API in this example, but you can replace it with any other embedding generation service.

Use the Supabase CLI to create a new Edge Function:

```bash
supabase functions new embed
```

This will create a new directory `supabase/functions/embed` with an `index.ts` file. Replace the contents of this file with the following:

*supabase/functions/embed/index.ts*:

```typescript
// Setup type definitions for built-in Supabase Runtime APIs
import 'jsr:@supabase/functions-js/edge-runtime.d.ts'

// We'll use the OpenAI API to generate embeddings
import OpenAI from 'jsr:@openai/openai'

import { z } from 'npm:zod'

// We'll make a direct Postgres connection to update the document
import postgres from 'https://deno.land/x/postgresjs@v3.4.5/mod.js'

// Initialize OpenAI client
const openai = new OpenAI({
  // We'll need to manually set the `OPENAI_API_KEY` environment variable
  apiKey: Deno.env.get('OPENAI_API_KEY'),
})

// Initialize Postgres client
const sql = postgres(
  // `SUPABASE_DB_URL` is a built-in environment variable
  Deno.env.get('SUPABASE_DB_URL')!
)

const jobSchema = z.object({
  jobId: z.number(),
  id: z.number(),
  schema: z.string(),
  table: z.string(),
  contentFunction: z.string(),
  embeddingColumn: z.string(),
})

const failedJobSchema = jobSchema.extend({
  error: z.string(),
})

type Job = z.infer<typeof jobSchema>
type FailedJob = z.infer<typeof failedJobSchema>

type Row = {
  id: string
  content: unknown
}

const QUEUE_NAME = 'embedding_jobs'

// Listen for HTTP requests
Deno.serve(async (req) => {
  if (req.method !== 'POST') {
    return new Response('expected POST request', { status: 405 })
  }

  if (req.headers.get('content-type') !== 'application/json') {
    return new Response('expected json body', { status: 400 })
  }

  // Use Zod to parse and validate the request body
  const parseResult = z.array(jobSchema).safeParse(await req.json())

  if (parseResult.error) {
    return new Response(`invalid request body: ${parseResult.error.message}`, {
      status: 400,
    })
  }

  const pendingJobs = parseResult.data

  // Track jobs that completed successfully
  const completedJobs: Job[] = []

  // Track jobs that failed due to an error
  const failedJobs: FailedJob[] = []

  async function processJobs() {
    let currentJob: Job | undefined

    while ((currentJob = pendingJobs.shift()) !== undefined) {
      try {
        await processJob(currentJob)
        completedJobs.push(currentJob)
      } catch (error) {
        failedJobs.push({
          ...currentJob,
          error: error instanceof Error ? error.message : JSON.stringify(error),
        })
      }
    }
  }

  try {
    // Process jobs while listening for worker termination
    await Promise.race([processJobs(), catchUnload()])
  } catch (error) {
    // If the worker is terminating (e.g. wall clock limit reached),
    // add pending jobs to fail list with termination reason
    failedJobs.push(
      ...pendingJobs.map((job) => ({
        ...job,
        error: error instanceof Error ? error.message : JSON.stringify(error),
      }))
    )
  }

  // Log completed and failed jobs for traceability
  console.log('finished processing jobs:', {
    completedJobs: completedJobs.length,
    failedJobs: failedJobs.length,
  })

  return new Response(
    JSON.stringify({
      completedJobs,
      failedJobs,
    }),
    {
      // 200 OK response
      status: 200,

      // Custom headers to report job status
      headers: {
        'content-type': 'application/json',
        'x-completed-jobs': completedJobs.length.toString(),
        'x-failed-jobs': failedJobs.length.toString(),
      },
    }
  )
})

/**
 * Generates an embedding for the given text.
 */
async function generateEmbedding(text: string) {
  const response = await openai.embeddings.create({
    model: 'text-embedding-3-small',
    input: text,
  })
  const [data] = response.data

  if (!data) {
    throw new Error('failed to generate embedding')
  }

  return data.embedding
}

/**
 * Processes an embedding job.
 */
async function processJob(job: Job) {
  const { jobId, id, schema, table, contentFunction, embeddingColumn } = job

  // Fetch content for the schema/table/row combination
  const [row]: [Row] = await sql`
    select
      id,
      ${sql(contentFunction)}(t) as content
    from
      ${sql(schema)}.${sql(table)} t
    where
      id = ${id}
  `

  if (!row) {
    throw new Error(`row not found: ${schema}.${table}/${id}`)
  }

  if (typeof row.content !== 'string') {
    throw new Error(`invalid content - expected string: ${schema}.${table}/${id}`)
  }

  const embedding = await generateEmbedding(row.content)

  await sql`
    update
      ${sql(schema)}.${sql(table)}
    set
      ${sql(embeddingColumn)} = ${JSON.stringify(embedding)}
    where
      id = ${id}
  `

  await sql`
    select pgmq.delete(${QUEUE_NAME}, ${jobId}::bigint)
  `
}

/**
 * Returns a promise that rejects if the worker is terminating.
 */
function catchUnload() {
  return new Promise((reject) => {
    addEventListener('beforeunload', (ev: any) => {
      reject(new Error(ev.detail?.reason))
    })
  })
}
```

The Edge Function listens for incoming HTTP requests from `pg_net` and processes each embedding job. It is a generic worker that can handle embedding jobs for any table and column. It uses OpenAI's API to generate embeddings and updates the corresponding row in the database. It also deletes the job from the queue once it has been processed.

The function is designed to process multiple jobs independently. If one job fails, it will not affect the processing of other jobs. The function returns a `200 OK` response with a list of completed and failed jobs. We can use this information to diagnose failed jobs. See [Troubleshooting](#troubleshooting) for more details.

You will need to set the `OPENAI_API_KEY` environment variable to authenticate with OpenAI. When running the Edge Function locally, you can add it to a `.env` file:

*.env*:

    OPENAI_API_KEY=your-api-key

When you're ready to deploy the Edge Function, set can set the environment variable using the Supabase CLI:

```shell
supabase secrets set --env-file .env
```

or

```shell
supabase secrets set OPENAI_API_KEY=<your-api-key>
```

Alternatively, you can replace the `generateEmbedding` function with your own embedding generation logic.

See [Deploy to Production](/docs/guides/functions/deploy) for more information on how to deploy the Edge Function.


## Usage

Now that the infrastructure is in place, let's go through an example of how to use this system to automatically generate embeddings for a table of documents. You can use this approach with multiple tables and customize the input for each embedding generation as needed.


### 1. Create table to store documents with embeddings

We'll set up a new `documents` table that will store our content and embeddings:

```sql
-- Table to store documents with embeddings
create table documents (
  id integer primary key generated always as identity,
  title text not null,
  content text not null,
  embedding halfvec(1536),
  created_at timestamp with time zone default now()
);

-- Index for vector search over document embeddings
create index on documents using hnsw (embedding halfvec_cosine_ops);
```

Our `documents` table stores the title and content of each document along with its vector embedding. We use a `halfvec(1536)` column to store the embeddings.

`halfvec` is a `pgvector` data type that stores float values in half precision (16 bits) to save space. Our Edge Function used OpenAI's `text-embedding-3-small` model which generates 1536-dimensional embeddings, so we use the same dimensionality here. Adjust this based on the number of dimensions your embedding model generates.

We use an [HNSW index](/docs/guides/ai/vector-indexes/hnsw-indexes) on the vector column. Note that we are choosing `halfvec_cosine_ops` as the index method, which means our future queries will need to use cosine distance (`<=>`) to find similar embeddings. Also note that HNSW indexes support a maximum of 4000 dimensions for `halfvec` vectors, so keep this in mind when choosing an embedding model. If your model generates embeddings with more than 4000 dimensions, you will need to reduce the dimensionality before indexing them. See [Matryoshka embeddings](/blog/matryoshka-embeddings) for a potential solution to shortening dimensions.

Also note that the table must have a primary key column named `id` for our triggers to work correctly with the `util.queue_embeddings` function and for our Edge Function to update the correct row.


### 2. Create triggers to enqueue embedding jobs

Now we'll set up the triggers to enqueue embedding jobs whenever content is inserted or updated:

```sql
-- Customize the input for embedding generation
-- e.g. Concatenate title and content with a markdown header
create or replace function embedding_input(doc documents)
returns text
language plpgsql
immutable
as $$
begin
  return '# ' || doc.title || E'\n\n' || doc.content;
end;
$$;

-- Trigger for insert events
create trigger embed_documents_on_insert
  after insert
  on documents
  for each row
  execute function util.queue_embeddings('embedding_input', 'embedding');

-- Trigger for update events
create trigger embed_documents_on_update
  after update of title, content -- must match the columns in embedding_input()
  on documents
  for each row
  execute function util.queue_embeddings('embedding_input', 'embedding');
```

We create 2 triggers:

1.  `embed_documents_on_insert`: Enqueues embedding jobs whenever new rows are inserted into the `documents` table.

2.  `embed_documents_on_update`: Enqueues embedding jobs whenever the `title` or `content` columns are updated in the `documents` table.

Both of these triggers use the same `util.queue_embeddings` function that will queue the embedding jobs for processing. They accept 2 arguments:

1.  `embedding_input`: The name of the function that generates the input for embedding generation. This function allows you to customize the text input passed to the embedding model (e.g. concatenating the title and content). The function should accept a single row as input and return text.

2.  `embedding`: The name of the destination column where the embedding will be stored.

Note that the update trigger only fires when the `title` or `content` columns are updated. This is to avoid unnecessary updates to the embedding column when other columns are updated. Make sure that these columns match the columns used in the `embedding_input` function.


#### (Optional) Clearing embeddings on update

Note that our trigger will enqueue new embedding jobs when content is updated, but it will not clear any existing embeddings. This means that an embedding can be temporarily out of sync with the content until the new embedding is generated and updated.

If it is more important to have *accurate* embeddings than *any* embedding, you can add another trigger to clear the existing embedding until the new one is generated:

```sql
-- Trigger to clear the embedding column on update
create trigger clear_document_embedding_on_update
  before update of title, content -- must match the columns in embedding_input()
  on documents
  for each row
  execute function util.clear_column('embedding');
```

`util.clear_column` is a generic trigger function we created earlier that can be used to clear any column in a table.

*   It accepts the column name as an argument. This column must be nullable.
*   It requires a `before` trigger with a `for each row` clause.
*   It requires the `hstore` extension we created earlier.

This example will clear the `embedding` column whenever the `title` or `content` columns are updated (note the `of title, content` clause). This ensures that the embedding is always in sync with the title and content, but it will result in temporary gaps in search results until the new embedding is generated.

We intentionally use a `before` trigger because it allows us to modify the record before it's written to disk, avoiding an extra `update` statement that would be needed with an `after` trigger.


### 3. Insert and update documents

Let's insert a new document and update its content to see the embedding generation in action:

```sql
-- Insert a new document
insert into documents (title, content)
values
  ('Understanding Vector Databases', 'Vector databases are specialized...');

-- Immediately check the embedding column
select id, embedding
from documents
where title = 'Understanding Vector Databases';
```

You should observe that the `embedding` column is initially `null` after inserting the document. This is because the embedding generation is asynchronous and will be processed by the Edge Function in the next scheduled task.

Wait up to 10 seconds for the next task to run, then check the `embedding` column again:

```sql
select id, embedding
from documents
where title = 'Understanding Vector Databases';
```

You should see the generated embedding for the document.

Next let's update the content of the document:

```sql
-- Update the content of the document
update documents
set content = 'Vector databases allow you to query...'
where title = 'Understanding Vector Databases';

-- Immediately check the embedding column
select id, embedding
from documents
where title = 'Understanding Vector Databases';
```

You should observe that the `embedding` column is reset to `null` after updating the content. This is because of the trigger we added to clear existing embeddings whenever the content is updated. The embedding will be regenerated by the Edge Function in the next scheduled task.

Wait up to 10 seconds for the next task to run, then check the `embedding` column again:

```sql
select id, embedding
from documents
where title = 'Understanding Vector Databases';
```

You should see the updated embedding for the document.

Finally we'll update the title of the document:

```sql
-- Update the title of the document
update documents
set title = 'Understanding Vector Databases with Supabase'
where title = 'Understanding Vector Databases';
```

You should observe that the `embedding` column is once again reset to `null` after updating the title. This is because the trigger we added to clear existing embeddings fires when either the `content` or `title` columns are updated. The embedding will be regenerated by the Edge Function in the next scheduled task.

Wait up to 10 seconds for the next task to run, then check the `embedding` column again:

```sql
select id, embedding
from documents
where title = 'Understanding Vector Databases with Supabase';
```

You should see the updated embedding for the document.


## Troubleshooting

The `embed` Edge Function processes a batch of embedding jobs and returns a `200 OK` response with a list of completed and failed jobs in the body. For example:

```json
{
  "completedJobs": [
    {
      "jobId": "1",
      "id": "1",
      "schema": "public",
      "table": "documents",
      "contentFunction": "embedding_input",
      "embeddingColumn": "embedding"
    }
  ],
  "failedJobs": [
    {
      "jobId": "2",
      "id": "2",
      "schema": "public",
      "table": "documents",
      "contentFunction": "embedding_input",
      "embeddingColumn": "embedding",
      "error": "error connecting to openai api"
    }
  ]
}
```

It also returns the number of completed and failed jobs in the response headers. For example:

    x-completed-jobs: 1
    x-failed-jobs: 1

You can also use the `x-deno-execution-id` header to trace the execution of the Edge Function within the [dashboard](/dashboard/project/_/functions) logs.

Each failed job includes an `error` field with a description of the failure. Reasons for a job failing could include:

*   An error generating the embedding via external API
*   An error connecting to the database
*   The edge function being terminated (e.g. due to a wall clock limit)
*   Any other error thrown during processing

`pg_net` stores HTTP responses in the `net._http_response` table, which can be queried to diagnose issues with the embedding generation process.

```sql
select
  *
from
  net._http_response
where
  (headers->>'x-failed-jobs')::int > 0;
```


## Conclusion

Automating embedding generation and updates in Postgres allow you to build powerful semantic search capabilities without the complexity of managing embeddings manually.

By combining Postgres features like triggers, queues, and other extensions with Supabase Edge Functions, we can create a robust system that handles embedding generation asynchronously and retries failed jobs automatically.

This system can be customized to work with any content and embedding generation service, providing a flexible and scalable solution for semantic search in Postgres.


## See also

*   [What are embeddings?](/docs/guides/ai/concepts)
*   [Semantic search](/docs/guides/ai/semantic-search)
*   [Vector indexes](/docs/guides/ai/vector-indexes)
*   [Supabase Edge Functions](/docs/guides/functions)


# Choosing your Compute Add-on

Choosing the right Compute Add-on for your vector workload.

You have two options for scaling your vector workload:

1.  Increase the size of your database. This guide will help you choose the right size for your workload.
2.  Spread your workload across multiple databases. You can find more details about this approach in [Engineering for Scale](engineering-for-scale).


## Dimensionality

The number of dimensions in your embeddings is the most important factor in choosing the right Compute Add-on. In general, the lower the dimensionality the better the performance. We've provided guidance for some of the more common embedding dimensions below. For each benchmark, we used [Vecs](https://github.com/supabase/vecs) to create a collection, upload the embeddings to a single table, and create both the `IVFFlat` and `HNSW` indexes for `inner-product` distance measure for the embedding column. We then ran a series of queries to measure the performance of different compute add-ons:


## HNSW


### 384 dimensions \[#hnsw-384-dimensions]

This benchmark uses the dbpedia-entities-openai-1M dataset containing 1,000,000 embeddings of text, regenerated for 384 dimension embeddings. Each embedding is generated using [gte-small](https://huggingface.co/Supabase/gte-small).


### 960 dimensions \[#hnsw-960-dimensions]

This benchmark uses the [gist-960](http://corpus-texmex.irisa.fr/) dataset, which contains 1,000,000 embeddings of images. Each embedding is 960 dimensions.


### 1536 dimensions \[#hnsw-1536-dimensions]

This benchmark uses the [dbpedia-entities-openai-1M](https://huggingface.co/datasets/KShivendu/dbpedia-entities-openai-1M) dataset, which contains 1,000,000 embeddings of text. And 224,482 embeddings from [Wikipedia articles](https://huggingface.co/datasets/Supabase/wikipedia-en-embeddings) for compute add-ons `large` and below. Each embedding is 1536 dimensions created with the [OpenAI Embeddings API](https://platform.openai.com/docs/guides/embeddings).


## IVFFlat


### 384 dimensions \[#ivfflat-384-dimensions]

This benchmark uses the dbpedia-entities-openai-1M dataset containing 1,000,000 embeddings of text, regenerated for 384 dimension embeddings. Each embedding is generated using [gte-small](https://huggingface.co/Supabase/gte-small).


### 960 dimensions \[#ivfflat-960-dimensions]

This benchmark uses the [gist-960](http://corpus-texmex.irisa.fr/) dataset, which contains 1,000,000 embeddings of images. Each embedding is 960 dimensions.


### 1536 dimensions \[#ivfflat-1536-dimensions]

This benchmark uses the [dbpedia-entities-openai-1M](https://huggingface.co/datasets/KShivendu/dbpedia-entities-openai-1M) dataset, which contains 1,000,000 embeddings of text. Each embedding is 1536 dimensions created with the [OpenAI Embeddings API](https://platform.openai.com/docs/guides/embeddings).


## Performance tips

There are various ways to improve your pgvector performance. Here are some tips:


### Pre-warming your database

It's useful to execute a few thousand “warm-up” queries before going into production. This helps help with RAM utilization. This can also help to determine that you've selected the right compute size for your workload.


### Fine-tune index parameters

You can increase the Requests per Second by increasing `m` and `ef_construction` or `lists`. This also has an important caveat: building the index takes longer with higher values for these parameters.

Check out more tips and the complete step-by-step guide in [Going to Production for AI applications](going-to-prod).


## Benchmark methodology

We follow techniques outlined in the [ANN Benchmarks](https://github.com/erikbern/ann-benchmarks) methodology. A Python test runner is responsible for uploading the data, creating the index, and running the queries. The pgvector engine is implemented using [vecs](https://github.com/supabase/vecs), a Python client for pgvector.

Each test is run for a minimum of 30-40 minutes. They include a series of experiments executed at different concurrency levels to measure the engine's performance under different load types. The results are then averaged.

As a general recommendation, we suggest using a concurrency level of 5 or more for most workloads and 30 or more for high-load workloads.


# Concepts



Embeddings are core to many AI and vector applications. This guide covers these concepts. If you prefer to get started right away, see our guide on [Generating Embeddings](/docs/guides/ai/quickstarts/generate-text-embeddings).


## What are embeddings?

Embeddings capture the "relatedness" of text, images, video, or other types of information. This relatedness is most commonly used for:

*   **Search:** how similar is a search term to a body of text?
*   **Recommendations:** how similar are two products?
*   **Classifications:** how do we categorize a body of text?
*   **Clustering:** how do we identify trends?

Let's explore an example of text embeddings. Say we have three phrases:

1.  "The cat chases the mouse"
2.  "The kitten hunts rodents"
3.  "I like ham sandwiches"

Your job is to group phrases with similar meaning. If you are a human, this should be obvious. Phrases 1 and 2 are almost identical, while phrase 3 has a completely different meaning.

Although phrases 1 and 2 are similar, they share no common vocabulary (besides "the"). Yet their meanings are nearly identical. How can we teach a computer that these are the same?


## Human language

Humans use words and symbols to communicate language. But words in isolation are mostly meaningless - we need to draw from shared knowledge & experience in order to make sense of them. The phrase “You should Google it” only makes sense if you know that Google is a search engine and that people have been using it as a verb.

In the same way, we need to train a neural network model to understand human language. An effective model should be trained on millions of different examples to understand what each word, phrase, sentence, or paragraph could mean in different contexts.

So how does this relate to embeddings?


## How do embeddings work?

Embeddings compress discrete information (words & symbols) into distributed continuous-valued data (vectors). If we took our phrases from before and plot them on a chart, it might look something like this:

Phrases 1 and 2 would be plotted close to each other, since their meanings are similar. We would expect phrase 3 to live somewhere far away since it isn't related. If we had a fourth phrase, “Sally ate Swiss cheese”, this might exist somewhere between phrase 3 (cheese can go on sandwiches) and phrase 1 (mice like Swiss cheese).

In this example we only have 2 dimensions: the X and Y axis. In reality, we would need many more dimensions to effectively capture the complexities of human language.


## Using embeddings

Compared to our 2-dimensional example above, most embedding models will output many more dimensions. For example the open source [`gte-small`](https://huggingface.co/Supabase/gte-small) model outputs 384 dimensions.

Why is this useful? Once we have generated embeddings on multiple texts, it is trivial to calculate how similar they are using vector math operations like cosine distance. A common use case for this is search. Your process might look something like this:

1.  Pre-process your knowledge base and generate embeddings for each page
2.  Store your embeddings to be referenced later
3.  Build a search page that prompts your user for input
4.  Take user's input, generate a one-time embedding, then perform a similarity search against your pre-processed embeddings.
5.  Return the most similar pages to the user


## See also

*   [Structured and Unstructured embeddings](/docs/guides/ai/structured-unstructured)


# Engineering for Scale

Building an enterprise-grade vector architecture.

Content sources for vectors can be extremely large. As you grow you should run your Vector workloads across several secondary databases (sometimes called "pods"), which allows each collection to scale independently.


## Simple workloads

For small workloads, it's typical to store your data in a single database.

If you've used [Vecs](/docs/guides/ai/vecs-python-client) to create 3 different collections, you can expose collections to your web or mobile application using [views](/docs/guides/database/tables#views):

For example, with 3 collections, called `docs`, `posts`, and `images`, we could expose the "docs" inside the public schema like this:

```sql
create view public.docs as
select
  id,
  embedding,
  metadata, # Expose the metadata as JSON
  (metadata->>'url')::text as url # Extract the URL as a string
from vector
```

You can then use any of the client libraries to access your collections within your applications:

```js
const { data, error } = await supabase
  .from('docs')
  .select('id, embedding, metadata')
  .eq('url', '/hello-world')
```


## Enterprise workloads

As you move into production, we recommend splitting your collections into separate projects. This is because it allows your vector stores to scale independently of your production data. Vectors typically grow faster than operational data, and they have different resource requirements. Running them on separate databases removes the single-point-of-failure.

You can use as many secondary databases as you need to manage your collections. With this architecture, you have 2 options for accessing collections within your application:

1.  Query the collections directly using Vecs.
2.  Access the collections from your Primary database through a Wrapper.

You can use both of these in tandem to suit your use-case. We recommend option `1` wherever possible, as it offers the most scalability.


### Query collections using Vecs

Vecs provides methods for querying collections, either using a [cosine similarity function](https://supabase.github.io/vecs/api/#basic) or with [metadata filtering](https://supabase.github.io/vecs/api/#metadata-filtering).

```python
# cosine similarity
docs.query(query_vector=[0.4,0.5,0.6], limit=5)

# metadata filtering
docs.query(
    query_vector=[0.4,0.5,0.6],
    limit=5,
    filters={"year": {"$eq": 2012}}, # metadata filters
)
```


### Accessing external collections using Wrappers

Supabase supports [Foreign Data Wrappers](/blog/postgres-foreign-data-wrappers-rust). Wrappers allow you to connect two databases together so that you can query them over the network.

This involves 2 steps: connecting to your remote database from the primary and creating a Foreign Table.


#### Connecting your remote database

Inside your Primary database we need to provide the credentials to access the secondary database:

```sql
create extension postgres_fdw;

create server docs_server
foreign data wrapper postgres_fdw
options (host 'db.xxx.supabase.co', port '5432', dbname 'postgres');

create user mapping for docs_user
server docs_server
options (user 'postgres', password 'password');
```


#### Create a foreign table

We can now create a foreign table to access the data in our secondary project.

```sql
create foreign table docs (
  id text not null,
  embedding vector(384),
  metadata jsonb,
  url text
)
server docs_server
options (schema_name 'public', table_name 'docs');
```

This looks very similar to our View example above, and you can continue to use the client libraries to access your collections through the foreign table:

```js
const { data, error } = await supabase
  .from('docs')
  .select('id, embedding, metadata')
  .eq('url', '/hello-world')
```


### Enterprise architecture

This diagram provides an example architecture that allows you to access the collections either with our client libraries or using Vecs. You can add as many secondary databases as you need (in this example we only show one):


# Building ChatGPT plugins

Use Supabase as a Retrieval Store for your ChatGPT plugin.

ChatGPT recently released [Plugins](https://openai.com/blog/chatgpt-plugins) which help ChatGPT access up-to-date information, run computations, or use third-party services.
If you're building a plugin for ChatGPT, you'll probably want to answer questions from a specific source. We can solve this with “retrieval plugins”, which allow ChatGPT to access information from a database.


## What is ChatGPT Retrieval Plugin?

A [Retrieval Plugin](https://github.com/openai/chatgpt-retrieval-plugin) is a Python project designed to inject external data into a ChatGPT conversation. It does a few things:

1.  Turn documents into smaller chunks.
2.  Converts chunks into embeddings using OpenAI's `text-embedding-ada-002` model.
3.  Stores the embeddings into a vector database.
4.  Queries the vector database for relevant documents when a question is asked.

It allows ChatGPT to dynamically pull relevant information into conversations from your data sources. This could be PDF documents, Confluence, or Notion knowledge bases.


## Example: Chat with Postgres docs

Let’s build an example where we can “ask ChatGPT questions” about the Postgres documentation. Although ChatGPT already knows about the Postgres documentation because it is publicly available, this is a simple example which demonstrates how to work with PDF files.

This plugin requires several steps:

1.  Download all the [Postgres docs as a PDF](https://www.postgresql.org/files/documentation/pdf/15/postgresql-15-US.pdf)
2.  Convert the docs into chunks of embedded text and store them in Supabase
3.  Run our plugin locally so that we can ask questions about the Postgres docs.

We'll be saving the Postgres documentation in Postgres, and ChatGPT will be retrieving the documentation whenever a user asks a question:


### Step 1: Fork the ChatGPT Retrieval Plugin repository

Fork the ChatGPT Retrieval Plugin repository to your GitHub account and clone it to your local machine. Read through the `README.md` file to understand the project structure.


### Step 2: Install dependencies

Choose your desired datastore provider and remove unused dependencies from `pyproject.toml`. For this example, we'll use Supabase. And install dependencies with Poetry:

```bash
poetry install
```


### Step 3: Create a Supabase project

Create a [Supabase project](https://supabase.com/dashboard) and database by following the instructions [here](https://supabase.com/docs/guides/platform). Export the environment variables required for the retrieval plugin to work:

```bash
export OPENAI_API_KEY=<open_ai_api_key>
export DATASTORE=supabase
export SUPABASE_URL=<supabase_url>
export SUPABASE_SERVICE_ROLE_KEY=<supabase_key>
```

For Postgres datastore, you'll need to export these environment variables instead:

```bash
export OPENAI_API_KEY=<open_ai_api_key>
export DATASTORE=postgres
export PG_HOST=<postgres_host_url>
export PG_PASSWORD=<postgres_password>
```


### Step 4: Run Postgres locally

To start quicker you may use Supabase CLI to spin everything up locally as it already includes pgvector from the start. Install `supabase-cli`, go to the `examples/providers` folder in the repo and run:

```bash
supabase start
```

This will pull all docker images and run Supabase stack in docker on your local machine. It will also apply all the necessary migrations to set the whole thing up. You can then use your local setup the same way, just export the environment variables and follow to the next steps.

Using `supabase-cli` is not required and you can use any other docker image or hosted version of Postgres that includes `pgvector`. Just make sure you run migrations from `examples/providers/supabase/migrations/20230414142107_init_pg_vector.sql`.


### Step 5: Obtain OpenAI API key

To create embeddings Plugin uses OpenAI API and `text-embedding-ada-002` model. Each time we add some data to our datastore, or try to query relevant information from it, embedding will be created either for inserted data chunk, or for the query itself. To make it work we need to export `OPENAI_API_KEY`. If you already have an account in OpenAI, you just need to go to [User Settings - API keys](https://platform.openai.com/account/api-keys) and Create new secret key.

![OpenAI Secret Keys](/docs/img/ai/chatgpt-plugins/openai-secret-keys.png)


### Step 6: Run the plugin

Execute the following command to run the plugin:

```bash
poetry run dev
# output
INFO:     Will watch for changes in these directories: ['./chatgpt-retrieval-plugin']
INFO:     Uvicorn running on http://localhost:3333 (Press CTRL+C to quit)
INFO:     Started reloader process [87843] using WatchFiles
INFO:     Started server process [87849]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
```

The plugin will start on your localhost - port `:3333` by default.


### Step 6: Populating data in the datastore

For this example, we'll upload Postgres documentation to the datastore. Download the [Postgres documentation](https://www.postgresql.org/files/documentation/pdf/15/postgresql-15-US.pdf) and use the `/upsert-file` endpoint to upload it:

```bash
curl -X POST -F \\"file=@./postgresql-15-US.pdf\\" <http://localhost:3333/upsert-file>
```

The plugin will split your data and documents into smaller chunks automatically. You can view the chunks using the Supabase dashboard or any other SQL client you prefer. The entire Postgres Documentation yielded 7,904 records, which is not a lot, but we can try to add index for `embedding` column to speed things up by a little. To do so, you should run the following SQL command:

```sql
create index on documents
using hnsw (embedding vector_ip_ops)
with (lists = 10);
```

This will create an index for the inner product distance function. Important to note that it is an approximate index. It will change the logic from performing the exact nearest neighbor search to the approximate nearest neighbor search.

We are using `lists = 10`, because as a general guideline, you should start looking for optimal lists constant value with the formula: `rows / 1000` when you have less than 1 million records in your table.


### Step 7: Using our plugin within ChatGPT

To integrate our plugin with ChatGPT, register it in the ChatGPT dashboard. Assuming you have access to ChatGPT Plugins and plugin development, select the Plugins model in a new chat, then choose "Plugin store" and "Develop your own plugin." Enter `localhost:3333` into the domain input, and your plugin is now part of ChatGPT.

![ChatGPT Plugin Store](/docs/img/ai/chatgpt-plugins/chatgpt-plugin-store.png)

![ChatGPT Local Plugin](/docs/img/ai/chatgpt-plugins/chatgpt-local-plugin.png)

You can now ask questions about Postgres and receive answers derived from the documentation.

Let's try it out: ask ChatGPT to find out when to use `check` and when to use `using`. You will be able to see what queries were sent to our plugin and what it responded to.

![Ask ChatGPT](/docs/img/ai/chatgpt-plugins/ask-chatgpt.png)

And after ChatGPT receives a response from the plugin it will answer your question with the data from the documentation.

![ChatGPT Reply](/docs/img/ai/chatgpt-plugins/chatgpt-reply.png)


## Resources

*   ChatGPT Retrieval Plugin: [github.com/openai/chatgpt-retrieval-plugin](https://github.com/openai/chatgpt-retrieval-plugin)
*   ChatGPT Plugins: [official documentation](https://platform.openai.com/docs/plugins/introduction)


# Adding generative Q&A for your documentation

Learn how to build a ChatGPT-style doc search powered using our headless search toolkit.

Supabase provides a [Headless Search Toolkit](https://github.com/supabase/headless-vector-search) for adding "Generative Q\&A" to your documentation. The toolkit is "headless", so that you can integrate it into your existing website and style it to match your website theme.

You can see how this works with the Supabase docs. Just hit `cmd+k` and "ask" for something like "what are the features of Supabase?". You will see that the response is streamed back, using the information provided in the docs:

![headless search](/docs/img/ai/headless-search/headless.png)


## Tech stack

*   Supabase: Database & Edge Functions.
*   OpenAI: Embeddings and completions.
*   GitHub Actions: for ingesting your markdown docs.


## Toolkit

This toolkit consists of 2 parts:

*   The [Headless Vector Search](https://github.com/supabase/headless-vector-search) template which you can deploy in your own organization.
*   A [GitHub Action](https://github.com/supabase/embeddings-generator) which will ingest your markdown files, convert them to embeddings, and store them in your database.


## Usage

There are 3 steps to build similarity search inside your documentation:

1.  Prepare your database.
2.  Ingest your documentation.
3.  Add a search interface.


### Prepare your database

To prepare, create a [new Supabase project](https://database.new) and store the database and API credentials, which you can find in the project [settings](https://supabase.com/dashboard/project/_/settings).

Now we can use the [Headless Vector Search](https://github.com/supabase/headless-vector-search#set-up) instructions to set up the database:

1.  Clone the repo to your local machine: `git clone git@github.com:supabase/headless-vector-search.git`
2.  Link the repo to your remote project: `supabase link --project-ref XXX`
3.  Apply the database migrations: `supabase db push`
4.  Set your OpenAI key as a secret: `supabase secrets set OPENAI_API_KEY=sk-xxx`
5.  Deploy the Edge Functions: `supabase functions deploy --no-verify-jwt`
6.  Expose `docs` schema via API in Supabase Dashboard [settings](https://supabase.com/dashboard/project/_/settings/api) > `API Settings` > `Exposed schemas`


### Ingest your documentation

Now we need to push your documentation into the database as embeddings. You can do this manually, but to make it easier we've created a [GitHub Action](https://github.com/marketplace/actions/supabase-embeddings-generator) which can update your database every time there is a Pull Request.

In your knowledge base repository, create a new action called `.github/workflows/generate_embeddings.yml` with the following content:

```yml
name: 'generate_embeddings'
on: # run on main branch changes
  push:
    branches:
      - main

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: supabase/embeddings-generator@v0.0.x # Update this to the latest version.
        with:
          supabase-url: 'https://your-project-ref.supabase.co' # Update this to your project URL.
          supabase-service-role-key: ${{ secrets.SUPABASE_SERVICE_ROLE_KEY }}
          openai-key: ${{ secrets.OPENAI_API_KEY }}
          docs-root-path: 'docs' # the path to the root of your md(x) files
```

Make sure to choose the latest version, and set your `SUPABASE_SERVICE_ROLE_KEY` and `OPENAI_API_KEY` as repository secrets in your repo settings (settings > secrets > actions).


### Add a search interface

Now inside your docs, you need to create a search interface. Because this is a headless interface, you can use it with any language. The only requirement is that you send the user query to the `query` Edge Function, which will stream an answer back from OpenAI. It might look something like this:

```js
const onSubmit = (e: Event) => {
  e.preventDefault()
  answer.value = ""
  isLoading.value = true

  const query = new URLSearchParams({ query: inputRef.current!.value })
  const projectUrl = `https://your-project-ref.supabase.co/functions/v1`
  const queryURL = `${projectURL}/${query}`
  const eventSource = new EventSource(queryURL)

  eventSource.addEventListener("error", (err) => {
    isLoading.value = false
    console.error(err)
  })

  eventSource.addEventListener("message", (e: MessageEvent) => {
    isLoading.value = false

    if (e.data === "[DONE]") {
      eventSource.close()
      return
    }

    const completionResponse: CreateCompletionResponse = JSON.parse(e.data)
    const text = completionResponse.choices[0].text

    answer.value += text
  });

  isLoading.value = true
}
```


## Resources

*   Read about how we built [ChatGPT for the Supabase Docs](https://supabase.com/blog/chatgpt-supabase-docs).
*   Read the pgvector Docs for [Embeddings and vector similarity](/docs/guides/database/extensions/pgvector)
*   See how to build something like this from scratch [using Next.js](/docs/guides/ai/examples/nextjs-vector-search).


# Generate image captions using Hugging Face

Use the Hugging Face Inference API to make calls to 100,000+ Machine Learning models from Supabase Edge Functions.

We can combine Hugging Face with [Supabase Storage](https://supabase.com/storage) and [Database Webhooks](https://supabase.com/docs/guides/database/webhooks) to automatically caption for any image we upload to a storage bucket.


## About Hugging Face

[Hugging Face](https://huggingface.co/) is the collaboration platform for the machine learning community.

[Huggingface.js](https://huggingface.co/docs/huggingface.js/index) provides a convenient way to make calls to 100,000+ Machine Learning models, making it easy to incorporate AI functionality into your [Supabase Edge Functions](https://supabase.com/edge-functions).


## Setup

*   Open your Supabase project dashboard or [create a new project](https://supabase.com/dashboard/projects).
*   [Create a new bucket](https://supabase.com/dashboard/project/_/storage/buckets) called `images`.
*   Generate TypeScript types from remote Database.
*   Create a new Database table called `image_caption`.
    *   Create `id` column of type `uuid` which references `storage.objects.id`.
    *   Create a `caption` column of type `text`.
*   Regenerate TypeScript types to include new `image_caption` table.
*   Deploy the function to Supabase: `supabase functions deploy huggingface-image-captioning`.
*   Create the Database Webhook in the [Supabase Dashboard](https://supabase.com/dashboard/project/_/database/hooks) to trigger the `huggingface-image-captioning` function anytime a record is added to the `storage.objects` table.


## Generate TypeScript types

To generate the types.ts file for the storage and public schemas, run the following command in the terminal:

```bash
supabase gen types typescript --project-id=your-project-ref --schema=storage,public > supabase/functions/huggingface-image-captioning/types.ts
```


## Code

Find the complete code on [GitHub](https://github.com/supabase/supabase/tree/master/examples/edge-functions/supabase/functions/huggingface-image-captioning).

```ts
import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
import { HfInference } from 'https://esm.sh/@huggingface/inference@2.3.2'
import { createClient } from 'jsr:@supabase/supabase-js@2'
import { Database } from './types.ts'

console.log('Hello from `huggingface-image-captioning` function!')

const hf = new HfInference(Deno.env.get('HUGGINGFACE_ACCESS_TOKEN'))

type SoRecord = Database['storage']['Tables']['objects']['Row']
interface WebhookPayload {
  type: 'INSERT' | 'UPDATE' | 'DELETE'
  table: string
  record: SoRecord
  schema: 'public'
  old_record: null | SoRecord
}

serve(async (req) => {
  const payload: WebhookPayload = await req.json()
  const soRecord = payload.record
  const supabaseAdminClient = createClient<Database>(
    // Supabase API URL - env var exported by default when deployed.
    Deno.env.get('SUPABASE_URL') ?? '',
    // Supabase API SERVICE ROLE KEY - env var exported by default when deployed.
    Deno.env.get('SUPABASE_SERVICE_ROLE_KEY') ?? ''
  )

  // Construct image url from storage
  const { data, error } = await supabaseAdminClient.storage
    .from(soRecord.bucket_id!)
    .createSignedUrl(soRecord.path_tokens!.join('/'), 60)
  if (error) throw error
  const { signedUrl } = data

  // Run image captioning with Huggingface
  const imgDesc = await hf.imageToText({
    data: await (await fetch(signedUrl)).blob(),
    model: 'nlpconnect/vit-gpt2-image-captioning',
  })

  // Store image caption in Database table
  await supabaseAdminClient
    .from('image_caption')
    .insert({ id: soRecord.id!, caption: imgDesc.generated_text })
    .throwOnError()

  return new Response('ok')
})
```


# Image Search with OpenAI CLIP

Implement image search with the OpenAI CLIP Model and Supabase Vector.

The [OpenAI CLIP Model](https://github.com/openai/CLIP) was trained on a variety of (image, text)-pairs. You can use the CLIP model for:

*   Text-to-Image / Image-To-Text / Image-to-Image / Text-to-Text Search
*   You can fine-tune it on your own image and text data with the regular `SentenceTransformers` training code.

[`SentenceTransformers`](https://www.sbert.net/examples/applications/image-search/README.html) provides models that allow you to embed images and text into the same vector space. You can use this to find similar images as well as to implement image search.

You can find the full application code as a Python Poetry project on [GitHub](https://github.com/supabase/supabase/tree/master/examples/ai/image_search#image-search-with-supabase-vector).


## Create a new Python project with Poetry

[Poetry](https://python-poetry.org/) provides packaging and dependency management for Python. If you haven't already, install poetry via pip:

```shell
pip install poetry
```

Then initialize a new project:

```shell
poetry new image-search
```


## Setup Supabase project

If you haven't already, [install the Supabase CLI](/docs/guides/cli), then initialize Supabase in the root of your newly created poetry project:

```shell
supabase init
```

Next, start your local Supabase stack:

```shell
supabase start
```

This will start up the Supabase stack locally and print out a bunch of environment details, including your local `DB URL`. Make a note of that for later user.


## Install the dependencies

We will need to add the following dependencies to our project:

*   [`vecs`](https://github.com/supabase/vecs#vecs): Supabase Vector Python Client.
*   [`sentence-transformers`](https://huggingface.co/sentence-transformers/clip-ViT-B-32): a framework for sentence, text and image embeddings (used with OpenAI CLIP model)
*   [`matplotlib`](https://matplotlib.org/): for displaying our image result

```shell
poetry add vecs sentence-transformers matplotlib
```


## Import the necessary dependencies

At the top of your main python script, import the dependencies and store your `DB URL` from above in a variable:

```python
from PIL import Image
from sentence_transformers import SentenceTransformer
import vecs
from matplotlib import pyplot as plt
from matplotlib import image as mpimg

DB_CONNECTION = "postgresql://postgres:postgres@localhost:54322/postgres"
```


## Create embeddings for your images

In the root of your project, create a new folder called `images` and add some images. You can use the images from the example project on [GitHub](https://github.com/supabase/supabase/tree/master/examples/ai/image_search/images) or you can find license free images on [Unsplash](https://unsplash.com).

Next, create a `seed` method, which will create a new Supabase Vector Collection, generate embeddings for your images, and upsert the embeddings into your database:

```python
def seed():
    # create vector store client
    vx = vecs.create_client(DB_CONNECTION)

    # create a collection of vectors with 3 dimensions
    images = vx.get_or_create_collection(name="image_vectors", dimension=512)

    # Load CLIP model
    model = SentenceTransformer('clip-ViT-B-32')

    # Encode an image:
    img_emb1 = model.encode(Image.open('./images/one.jpg'))
    img_emb2 = model.encode(Image.open('./images/two.jpg'))
    img_emb3 = model.encode(Image.open('./images/three.jpg'))
    img_emb4 = model.encode(Image.open('./images/four.jpg'))

    # add records to the *images* collection
    images.upsert(
        records=[
            (
                "one.jpg",        # the vector's identifier
                img_emb1,          # the vector. list or np.array
                {"type": "jpg"}   # associated  metadata
            ), (
                "two.jpg",
                img_emb2,
                {"type": "jpg"}
            ), (
                "three.jpg",
                img_emb3,
                {"type": "jpg"}
            ), (
                "four.jpg",
                img_emb4,
                {"type": "jpg"}
            )
        ]
    )
    print("Inserted images")

    # index the collection for fast search performance
    images.create_index()
    print("Created index")
```

Add this method as a script in your `pyproject.toml` file:

```toml
[tool.poetry.scripts]
seed = "image_search.main:seed"
search = "image_search.main:search"
```

After activating the virtual environment with `poetry shell` you can now run your seed script via `poetry run seed`. You can inspect the generated embeddings in your local database by visiting the local Supabase dashboard at [localhost:54323](http://localhost:54323/project/default/editor), selecting the `vecs` schema, and the `image_vectors` database.


## Perform an image search from a text query

With Supabase Vector we can query our embeddings. We can use either an image as search input or alternative we can generate an embedding from a string input and use that as the query input:

```python
def search():
    # create vector store client
    vx = vecs.create_client(DB_CONNECTION)
    images = vx.get_or_create_collection(name="image_vectors", dimension=512)

    # Load CLIP model
    model = SentenceTransformer('clip-ViT-B-32')
    # Encode text query
    query_string = "a bike in front of a red brick wall"
    text_emb = model.encode(query_string)

    # query the collection filtering metadata for "type" = "jpg"
    results = images.query(
        data=text_emb,                      # required
        limit=1,                            # number of records to return
        filters={"type": {"$eq": "jpg"}},   # metadata filters
    )
    result = results[0]
    print(result)
    plt.title(result)
    image = mpimg.imread('./images/' + result)
    plt.imshow(image)
    plt.show()
```

By limiting the query to one result, we can show the most relevant image to the user. Finally we use `matplotlib` to show the image result to the user.

Go ahead and test it out by running `poetry run search` and you will be presented with an image of a "bike in front of a red brick wall".


## Conclusion

With just a couple of lines of Python you are able to implement image search as well as reverse image search using OpenAI's CLIP model and Supabase Vector.


# Video Search with Mixpeek Multimodal Embeddings

Implement video search with the Mixpeek Multimodal Embed API and Supabase Vector.

The [Mixpeek Embed API](https://docs.mixpeek.com/api-documentation/inference/embed) allows you to generate embeddings for various types of content, including videos and text. You can use these embeddings for:

*   Text-to-Video / Video-To-Text / Video-to-Video / Text-to-Text Search
*   Fine-tuning on your own video and text data

This guide demonstrates how to implement video search using Mixpeek Embed for video processing and embedding, and Supabase Vector for storing and querying embeddings.

You can find the full application code as a Python Poetry project on [GitHub](https://github.com/yourusername/your-repo-name).


## Create a new Python project with Poetry

[Poetry](https://python-poetry.org/) provides packaging and dependency management for Python. If you haven't already, install poetry via pip:

```shell
pip install poetry
```

Then initialize a new project:

```shell
poetry new video-search
```


## Setup Supabase project

If you haven't already, [install the Supabase CLI](https://supabase.com/docs/guides/cli), then initialize Supabase in the root of your newly created poetry project:

```shell
supabase init
```

Next, start your local Supabase stack:

```shell
supabase start
```

This will start up the Supabase stack locally and print out a bunch of environment details, including your local `DB URL`. Make a note of that for later use.


## Install the dependencies

Add the following dependencies to your project:

*   [`supabase`](https://github.com/supabase-community/supabase-py): Supabase Python Client
*   [`mixpeek`](https://github.com/mixpeek/python-client): Mixpeek Python Client for embedding generation

```shell
poetry add supabase mixpeek
```


## Import the necessary dependencies

At the top of your main Python script, import the dependencies and store your environment variables:

```python
from supabase import create_client, Client
from mixpeek import Mixpeek
import os

SUPABASE_URL = os.getenv("SUPABASE_URL")
SUPABASE_KEY = os.getenv("SUPABASE_API_KEY")
MIXPEEK_API_KEY = os.getenv("MIXPEEK_API_KEY")
```


## Create embeddings for your videos

Next, create a `seed` method, which will create a new Supabase table, generate embeddings for your video chunks, and insert the embeddings into your database:

```python
def seed():
    # Initialize Supabase and Mixpeek clients
    supabase: Client = create_client(SUPABASE_URL, SUPABASE_KEY)
    mixpeek = Mixpeek(MIXPEEK_API_KEY)

    # Create a table for storing video chunk embeddings
    supabase.table("video_chunks").create({
        "id": "text",
        "start_time": "float8",
        "end_time": "float8",
        "embedding": "vector(768)",
        "metadata": "jsonb"
    })

    # Process and embed video
    video_url = "https://example.com/your_video.mp4"
    processed_chunks = mixpeek.tools.video.process(
        video_source=video_url,
        chunk_interval=1,  # 1 second intervals
        resolution=[720, 1280]
    )

    for chunk in processed_chunks:
        print(f"Processing video chunk: {chunk['start_time']}")

        # Generate embedding using Mixpeek
        embed_response = mixpeek.embed.video(
            model_id="vuse-generic-v1",
            input=chunk['base64_chunk'],
            input_type="base64"
        )

        # Insert into Supabase
        supabase.table("video_chunks").insert({
            "id": f"chunk_{chunk['start_time']}",
            "start_time": chunk["start_time"],
            "end_time": chunk["end_time"],
            "embedding": embed_response['embedding'],
            "metadata": {"video_url": video_url}
        }).execute()

    print("Video processed and embeddings inserted")

    # Create index for fast search performance
    supabase.query("CREATE INDEX ON video_chunks USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100)").execute()
    print("Created index")
```

Add this method as a script in your `pyproject.toml` file:

```toml
[tool.poetry.scripts]
seed = "video_search.main:seed"
search = "video_search.main:search"
```

After activating the virtual environment with `poetry shell`, you can now run your seed script via `poetry run seed`. You can inspect the generated embeddings in your local database by visiting the local Supabase dashboard at [localhost:54323](http://localhost:54323/project/default/editor).


## Perform a video search from a text query

With Supabase Vector, you can query your embeddings. You can use either a video clip as search input or alternatively, you can generate an embedding from a string input and use that as the query input:

```python
def search():
    # Initialize Supabase and Mixpeek clients
    supabase: Client = create_client(SUPABASE_URL, SUPABASE_KEY)
    mixpeek = Mixpeek(MIXPEEK_API_KEY)

    # Generate embedding for text query
    query_string = "a car chase scene"
    text_emb = mixpeek.embed.video(
        model_id="vuse-generic-v1",
        input=query_string,
        input_type="text"
    )

    # Query the collection
    results = supabase.rpc(
        'match_video_chunks',
        {
            'query_embedding': text_emb['embedding'],
            'match_threshold': 0.8,
            'match_count': 5
        }
    ).execute()

    # Display the results
    if results.data:
        for result in results.data:
            print(f"Matched chunk from {result['start_time']} to {result['end_time']} seconds")
            print(f"Video URL: {result['metadata']['video_url']}")
            print(f"Similarity: {result['similarity']}")
            print("---")
    else:
        print("No matching video chunks found")
```

This query will return the top 5 most similar video chunks from your database.

You can now test it out by running `poetry run search`, and you will be presented with the most relevant video chunks to the query "a car chase scene".


## Conclusion

With just a couple of Python scripts, you are able to implement video search as well as reverse video search using Mixpeek Embed and Supabase Vector. This approach allows for powerful semantic search capabilities that can be integrated into various applications, enabling you to search through video content using both text and video queries.


# Vector search with Next.js and OpenAI

Learn how to build a ChatGPT-style doc search powered by Next.js, OpenAI, and Supabase.

While our [Headless Vector search](/docs/guides/ai/examples/headless-vector-search) provides a toolkit for generative Q\&A, in this tutorial we'll go more in-depth, build a custom ChatGPT-like search experience from the ground-up using Next.js. You will:

1.  Convert your markdown into embeddings using OpenAI.
2.  Store you embeddings in Postgres using pgvector.
3.  Deploy a function for answering your users' questions.

You can read our [Supabase Clippy](https://supabase.com/blog/chatgpt-supabase-docs) blog post for a full example.

We assume that you have a Next.js project with a collection of `.mdx` files nested inside your `pages` directory. We will start developing locally with the Supabase CLI and then push our local database changes to our hosted Supabase project. You can find the [full Next.js example on GitHub](https://github.com/supabase-community/nextjs-openai-doc-search).


## Create a project

1.  [Create a new project](https://supabase.com/dashboard) in the Supabase Dashboard.
2.  Enter your project details.
3.  Wait for the new database to launch.


## Prepare the database

Let's prepare the database schema. We can use the "OpenAI Vector Search" quickstart in the [SQL Editor](https://supabase.com/dashboard/project/_/sql), or you can copy/paste the SQL below and run it yourself.


## Pre-process the knowledge base at build time

With our database set up, we need to process and store all `.mdx` files in the `pages` directory. You can find the full script [here](https://github.com/supabase-community/nextjs-openai-doc-search/blob/main/lib/generate-embeddings.ts), or follow the steps below:


## Create text completion with OpenAI API

Anytime a user asks a question, we need to create an embedding for their question, perform a similarity search, and then send a text completion request to the OpenAI API with the query and then context content merged together into a prompt.

All of this is glued together in a [Vercel Edge Function](https://vercel.com/docs/concepts/functions/edge-functions), the code for which can be found on [GitHub](https://github.com/supabase-community/nextjs-openai-doc-search/blob/main/pages/api/vector-search.ts).


## Display the answer on the frontend

In a last step, we need to process the event stream from the OpenAI API and print the answer to the user. The full code for this can be found on [GitHub](https://github.com/supabase-community/nextjs-openai-doc-search/blob/main/components/SearchDialog.tsx).

```ts
const handleConfirm = React.useCallback(
  async (query: string) => {
    setAnswer(undefined)
    setQuestion(query)
    setSearch('')
    dispatchPromptData({ index: promptIndex, answer: undefined, query })
    setHasError(false)
    setIsLoading(true)

    const eventSource = new SSE(`api/vector-search`, {
      headers: {
        apikey: process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY ?? '',
        Authorization: `Bearer ${process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY}`,
        'Content-Type': 'application/json',
      },
      payload: JSON.stringify({ query }),
    })

    function handleError<T>(err: T) {
      setIsLoading(false)
      setHasError(true)
      console.error(err)
    }

    eventSource.addEventListener('error', handleError)
    eventSource.addEventListener('message', (e: any) => {
      try {
        setIsLoading(false)

        if (e.data === '[DONE]') {
          setPromptIndex((x) => {
            return x + 1
          })
          return
        }

        const completionResponse: CreateCompletionResponse = JSON.parse(e.data)
        const text = completionResponse.choices[0].text

        setAnswer((answer) => {
          const currentAnswer = answer ?? ''

          dispatchPromptData({
            index: promptIndex,
            answer: currentAnswer + text,
          })

          return (answer ?? '') + text
        })
      } catch (err) {
        handleError(err)
      }
    })

    eventSource.stream()

    eventSourceRef.current = eventSource

    setIsLoading(true)
  },
  [promptIndex, promptData]
)
```


## Learn more

Want to learn more about the awesome tech that is powering this?

*   Read about how we built [ChatGPT for the Supabase Docs](https://supabase.com/blog/chatgpt-supabase-docs).
*   Read the pgvector Docs for [Embeddings and vector similarity](https://supabase.com/docs/guides/database/extensions/pgvector)
*   Watch Greg's video for a full breakdown:


# Generating OpenAI GPT3 completions

Generate GPT text completions using OpenAI and Supabase Edge Functions.

OpenAI provides a [completions API](https://platform.openai.com/docs/api-reference/completions) that allows you to use their generative GPT models in your own applications.

OpenAI's API is intended to be used from the server-side. Supabase offers Edge Functions to make it easy to interact with third party APIs like OpenAI.


## Setup Supabase project

If you haven't already, [install the Supabase CLI](/docs/guides/cli) and initialize your project:

```shell
supabase init
```


## Create edge function

Scaffold a new edge function called `openai` by running:

```shell
supabase functions new openai
```

A new edge function will now exist under `./supabase/functions/openai/index.ts`.

We'll design the function to take your user's query (via POST request) and forward it to OpenAI's API.

```ts index.ts
import OpenAI from 'https://deno.land/x/openai@v4.24.0/mod.ts'

Deno.serve(async (req) => {
  const { query } = await req.json()
  const apiKey = Deno.env.get('OPENAI_API_KEY')
  const openai = new OpenAI({
    apiKey: apiKey,
  })

  // Documentation here: https://github.com/openai/openai-node
  const chatCompletion = await openai.chat.completions.create({
    messages: [{ role: 'user', content: query }],
    // Choose model from here: https://platform.openai.com/docs/models
    model: 'gpt-3.5-turbo',
    stream: false,
  })

  const reply = chatCompletion.choices[0].message.content

  return new Response(reply, {
    headers: { 'Content-Type': 'text/plain' },
  })
})
```

Note that we are setting `stream` to `false` which will wait until the entire response is complete before returning. If you wish to stream GPT's response word-by-word back to your client, set `stream` to `true`.


## Create OpenAI key

You may have noticed we were passing `OPENAI_API_KEY` in the Authorization header to OpenAI. To generate this key, go to https://platform.openai.com/account/api-keys and create a new secret key.

After getting the key, copy it into a new file called `.env.local` in your `./supabase` folder:

    OPENAI_API_KEY=your-key-here


## Run locally

Serve the edge function locally by running:

```bash
supabase functions serve --env-file ./supabase/.env.local --no-verify-jwt
```

Notice how we are passing in the `.env.local` file.

Use cURL or Postman to make a POST request to http://localhost:54321/functions/v1/openai.

```bash
curl -i --location --request POST http://localhost:54321/functions/v1/openai \
  --header 'Content-Type: application/json' \
  --data '{"query":"What is Supabase?"}'
```

You should see a GPT response come back from OpenAI!


## Deploy

Deploy your function to the cloud by running:

```bash
supabase functions deploy --no-verify-jwt openai
supabase secrets set --env-file ./supabase/.env.local
```


## Go deeper

If you're interesting in learning how to use this to build your own ChatGPT, read [the blog post](/blog/chatgpt-supabase-docs) and check out the video:


# Semantic Image Search with Amazon Titan

Implement semantic image search with Amazon Titan and Supabase Vector in Python.

[Amazon Bedrock](https://aws.amazon.com/bedrock) is a fully managed service that offers a choice of high-performing foundation models (FMs) from leading AI companies like AI21 Labs, Anthropic, Cohere, Meta, Mistral AI, Stability AI, and Amazon. Each model is accessible through a common API which implements a broad set of features to help build generative AI applications with security, privacy, and responsible AI in mind.

[Amazon Titan](https://aws.amazon.com/bedrock/titan/) is a family of foundation models (FMs) for text and image generation, summarization, classification, open-ended Q\&A, information extraction, and text or image search.

In this guide we'll look at how we can get started with Amazon Bedrock and Supabase Vector in Python using the Amazon Titan multimodal model and the [vecs client](/docs/guides/ai/vecs-python-client).

You can find the full application code as a Python Poetry project on [GitHub](https://github.com/supabase/supabase/tree/master/examples/ai/aws_bedrock_image_search).


## Create a new Python project with Poetry

[Poetry](https://python-poetry.org/) provides packaging and dependency management for Python. If you haven't already, install poetry via pip:

```shell
pip install poetry
```

Then initialize a new project:

```shell
poetry new aws_bedrock_image_search
```


## Spin up a Postgres database with pgvector

If you haven't already, head over to [database.new](https://database.new) and create a new project. Every Supabase project comes with a full Postgres database and the [pgvector extension](/docs/guides/database/extensions/pgvector) preconfigured.

When creating your project, make sure to note down your database password as you will need it to construct the `DB_URL` in the next step.

You can find the database connection string in your Supabase Dashboard [database settings](https://supabase.com/dashboard/project/_/settings/database). Select "Use connection pooling" with `Mode: Session` for a direct connection to your Postgres database. It will look something like this:

```txt
postgresql://postgres.[PROJECT-REF]:[YOUR-PASSWORD]@aws-0-[REGION].pooler.supabase.com:5432/postgres
```


## Install the dependencies

We will need to add the following dependencies to our project:

*   [`vecs`](https://github.com/supabase/vecs#vecs): Supabase Vector Python Client.
*   [`boto3`](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html): AWS SDK for Python.
*   [`matplotlib`](https://matplotlib.org/): for displaying our image result.

```shell
poetry add vecs boto3 matplotlib
```


## Import the necessary dependencies

At the top of your main python script, import the dependencies and store your `DB URL` from above in a variable:

```python
import sys
import boto3
import vecs
import json
import base64
from matplotlib import pyplot as plt
from matplotlib import image as mpimg
from typing import Optional

DB_CONNECTION = "postgresql://postgres.[PROJECT-REF]:[YOUR-PASSWORD]@aws-0-[REGION].pooler.supabase.com:5432/postgres"
```

Next, get the [credentials to your AWS account](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html) and instantiate the `boto3` client:

```python
bedrock_client = boto3.client(
    'bedrock-runtime',
    region_name='us-west-2',
    # Credentials from your AWS account
    aws_access_key_id='<replace_your_own_credentials>',
    aws_secret_access_key='<replace_your_own_credentials>',
    aws_session_token='<replace_your_own_credentials>',
)
```


## Create embeddings for your images

In the root of your project, create a new folder called `images` and add some images. You can use the images from the example project on [GitHub](https://github.com/supabase/supabase/tree/master/examples/ai/aws_bedrock_image_search/images) or you can find license free images on [Unsplash](https://unsplash.com).

To send images to the Amazon Bedrock API we need to need to encode them as `base64` strings. Create the following helper methods:

```python
def readFileAsBase64(file_path):
    """Encode image as base64 string."""
    try:
        with open(file_path, "rb") as image_file:
            input_image = base64.b64encode(image_file.read()).decode("utf8")
        return input_image
    except:
        print("bad file name")
        sys.exit(0)


def construct_bedrock_image_body(base64_string):
    """Construct the request body.

    https://docs.aws.amazon.com/bedrock/latest/userguide/model-parameters-titan-embed-mm.html
    """
    return json.dumps(
        {
            "inputImage": base64_string,
            "embeddingConfig": {"outputEmbeddingLength": 1024},
        }
    )


def get_embedding_from_titan_multimodal(body):
    """Invoke the Amazon Titan Model via API request."""
    response = bedrock_client.invoke_model(
        body=body,
        modelId="amazon.titan-embed-image-v1",
        accept="application/json",
        contentType="application/json",
    )

    response_body = json.loads(response.get("body").read())
    print(response_body)
    return response_body["embedding"]


def encode_image(file_path):
    """Generate embedding for the image at file_path."""
    base64_string = readFileAsBase64(file_path)
    body = construct_bedrock_image_body(base64_string)
    emb = get_embedding_from_titan_multimodal(body)
    return emb
```

Next, create a `seed` method, which will create a new Supabase Vector Collection, generate embeddings for your images, and upsert the embeddings into your database:

```python
def seed():
    # create vector store client
    vx = vecs.create_client(DB_CONNECTION)

    # get or create a collection of vectors with 1024 dimensions
    images = vx.get_or_create_collection(name="image_vectors", dimension=1024)

    # Generate image embeddings with Amazon Titan Model
    img_emb1 = encode_image('./images/one.jpg')
    img_emb2 = encode_image('./images/two.jpg')
    img_emb3 = encode_image('./images/three.jpg')
    img_emb4 = encode_image('./images/four.jpg')

    # add records to the *images* collection
    images.upsert(
        records=[
            (
                "one.jpg",       # the vector's identifier
                img_emb1,        # the vector. list or np.array
                {"type": "jpg"}  # associated  metadata
            ), (
                "two.jpg",
                img_emb2,
                {"type": "jpg"}
            ), (
                "three.jpg",
                img_emb3,
                {"type": "jpg"}
            ), (
                "four.jpg",
                img_emb4,
                {"type": "jpg"}
            )
        ]
    )
    print("Inserted images")

    # index the collection for fast search performance
    images.create_index()
    print("Created index")
```

Add this method as a script in your `pyproject.toml` file:

```toml
[tool.poetry.scripts]
seed = "image_search.main:seed"
search = "image_search.main:search"
```

After activating the virtual environment with `poetry shell` you can now run your seed script via `poetry run seed`. You can inspect the generated embeddings in your Supabase Dashboard by visiting the [Table Editor](https://supabase.com/dashboard/project/_/editor), selecting the `vecs` schema, and the `image_vectors` table.


## Perform an image search from a text query

We can use Supabase Vector to query our embeddings. We can either use an image as the search input or generate an embedding from a string input:

```python
def search(query_term: Optional[str] = None):
    if query_term is None:
        query_term = sys.argv[1]

    # create vector store client
    vx = vecs.create_client(DB_CONNECTION)
    images = vx.get_or_create_collection(name="image_vectors", dimension=1024)

    # Encode text query
    text_emb = get_embedding_from_titan_multimodal(json.dumps(
        {
            "inputText": query_term,
            "embeddingConfig": {"outputEmbeddingLength": 1024},
        }
    ))

    # query the collection filtering metadata for "type" = "jpg"
    results = images.query(
        data=text_emb,                      # required
        limit=1,                            # number of records to return
        filters={"type": {"$eq": "jpg"}},   # metadata filters
    )
    result = results[0]
    print(result)
    plt.title(result)
    image = mpimg.imread('./images/' + result)
    plt.imshow(image)
    plt.show()
```

By limiting the query to one result, we can show the most relevant image to the user. Finally we use `matplotlib` to show the image result to the user.

Go ahead and test it out by running `poetry run search` and you will be presented with an image of a "bike in front of a red brick wall".


## Conclusion

With just a couple of lines of Python you are able to implement image search as well as reverse image search using the Amazon Titan multimodal model and Supabase Vector.


# Going to Production

Going to production checklist for AI applications.

This guide will help you to prepare your application for production. We'll provide actionable steps to help you scale your application, ensure that it is reliable, can handle the load, and provide optimal accuracy for your use case.

See our [Engineering for Scale](/docs/guides/ai/engineering-for-scale) guide for more information about engineering at scale.


## Do you need indexes?

Sequential scans will result in significantly higher latencies and lower throughput, guaranteeing 100% accuracy and not being RAM bound.

There are a couple of cases where you might not need indexes:

*   You have a small dataset and don't need to scale it.
*   You are not expecting high amounts of vector search queries per second.
*   You need to guarantee 100% accuracy.

You don't have to create indexes in these cases and can use sequential scans instead. This type of workload will not be RAM bound and will not require any additional resources but will result in higher latencies and lower throughput. Extra CPU cores may help to improve queries per second, but it will not help to improve latency.

On the other hand, if you need to scale your application, you will need to [create indexes](/docs/guides/ai/vector-indexes). This will result in lower latencies and higher throughput, but will require additional RAM to make use of Postgres Caching. Also, using indexes will result in lower accuracy, since you are replacing exact (KNN) search with approximate (ANN) search.


## HNSW vs IVFFlat indexes

`pgvector` supports two types of indexes: HNSW and IVFFlat. We recommend using [HNSW](/docs/guides/ai/vector-indexes/hnsw-indexes) because of its [performance](https://supabase.com/blog/increase-performance-pgvector-hnsw#hnsw-performance-1536-dimensions) and [robustness against changing data](/docs/guides/ai/vector-indexes/hnsw-indexes#when-should-you-create-hnsw-indexes).


## HNSW, understanding `ef_construction`, `ef_search`, and `m`

Index build parameters:

*   `m` is the number of bi-directional links created for every new element during construction. Higher `m` is suitable for datasets with high dimensionality and/or high accuracy requirements. Reasonable values for `m` are between 2 and 100. Range 12-48 is a good starting point for most use cases (16 is the default value).

*   `ef_construction` is the size of the dynamic list for the nearest neighbors (used during the construction algorithm). Higher `ef_construction` will result in better index quality and higher accuracy, but it will also increase the time required to build the index. `ef_construction` has to be at least 2 \* `m` (64 is the default value). At some point, increasing `ef_construction` does not improve the quality of the index. You can measure accuracy when `ef_search`=`ef_construction`: if accuracy is lower than 0.9, then there is room for improvement.

Search parameters:

*   `ef_search` is the size of the dynamic list for the nearest neighbors (used during the search). Increasing `ef_search` will result in better accuracy, but it will also increase the time required to execute a query (40 is the default value).


## IVFFlat, understanding `probes` and `lists`

Indexes used for approximate vector similarity search in pgvector divides a dataset into partitions. The number of these partitions is defined by the `lists` constant. The `probes` controls how many lists are going to be searched during a query.

The values of lists and probes directly affect accuracy and queries per second (QPS).

*   Higher `lists` means an index will be built slower, but you can achieve better QPS and accuracy.
*   Higher `probes` means that select queries will be slower, but you can achieve better accuracy.
*   `lists` and `probes` are not independent. Higher `lists` means that you will have to use higher `probes` to achieve the same accuracy.

You can find more examples of how `lists` and `probes` constants affect accuracy and QPS in [pgvector 0.4.0 performance](https://supabase.com/blog/pgvector-performance) blogpost.


## Performance tips when using indexes

First, a few generic tips which you can pick and choose from:

1.  The Supabase managed platform will automatically optimize Postgres configs for you based on your compute add-on. But if you self-host, consider **adjusting your Postgres config** based on RAM & CPU cores. See [example optimizations](https://gist.github.com/egor-romanov/323e2847851bbd758081511785573c08) for more details.
2.  Prefer `inner-product` to `L2` or `Cosine` distances if your vectors are normalized (like `text-embedding-ada-002`). If embeddings are not normalized, `Cosine` distance should give the best results with an index.
3.  **Pre-warm your database.** Implement the warm-up technique before transitioning to production or running benchmarks.
    *   Use [pg\_prewarm](https://www.postgresql.org/docs/current/pgprewarm.html) to load the index into RAM `select pg_prewarm('vecs.docs_vec_idx');`. This will help to avoid cold cache issues.
    *   Execute 10,000 to 50,000 "warm-up" queries before each benchmark/prod. This will help to utilize cache and buffers more efficiently.
4.  **Establish your workload.** Fine-tune `m` and `ef_construction` or `lists` constants for the pgvector index to accelerate your queries (at the expense of a slower build times). For instance, for benchmarks with 1,000,000 OpenAI embeddings, we set `m` and `ef_construction` to 32 and 80, and it resulted in 35% higher QPS than 24 and 56 values respectively.
5.  **Benchmark your own specific workloads.** Doing this during cache warm-up helps gauge the best value for the index build parameters, balancing accuracy with queries per second (QPS).


## Going into production

1.  Decide if you are going to use indexes or not. You can skip the rest of this guide if you do not use indexes.
2.  Over-provision RAM during preparation. You can scale down in step `5`, but it's better to start with a larger size to get the best results for RAM requirements. (We'd recommend at least 8XL if you're using Supabase.)
3.  Upload your data to the database. If you use the [`vecs`](/docs/guides/ai/python/api) library, it will automatically generate an index with default parameters.
4.  Run a benchmark using randomly generated queries and observe the results. Again, you can use the `vecs` library with the `ann-benchmarks` tool. Do it with default values for index build parameters, you can later adjust them to get the best results.
5.  Monitor the RAM usage, and save it as a note for yourself. You would likely want to use a compute add-on in the future that has the same amount of RAM that was used at the moment (both actual RAM usage and RAM used for cache and buffers).
6.  Scale down your compute add-on to the one that would have the same amount of RAM used at the moment.
7.  Repeat step 3 to load the data into RAM. You should see QPS increase on subsequent runs, and stop when it no longer increases.
8.  Run a benchmark using real queries and observe the results. You can use the `vecs` library for that as well with `ann-benchmarks` tool. Tweak `ef_search` for HNSW or `probes` for IVFFlat until you see that both accuracy and QPS match your requirements.
9.  If you want higher QPS you can increase `m` and `ef_construction` for HNSW or `lists` for IVFFlat parameters (consider switching from IVF to HNSW). You have to rebuild the index with a higher `m` and `ef_construction` values and repeat steps 6-7 to find the best combination of `m`, `ef_construction` and `ef_search` constants to achieve the best QPS and accuracy values. Higher `m`, `ef_construction` mean that index will build slower, but you can achieve better QPS and accuracy. Higher `ef_search` mean that select queries will be slower, but you can achieve better accuracy.


## Useful links

Don't forget to check out the general [Production Checklist](/docs/guides/platform/going-into-prod) to ensure your project is secure, performant, and will remain available for your users.

You can look at our [Choosing Compute Add-on](/docs/guides/ai/choosing-compute-addon) guide to get a basic understanding of how much compute you might need for your workload.

Or take a look at our [pgvector 0.5.0 performance](https://supabase.com/blog/increase-performance-pgvector-hnsw) and [pgvector 0.4.0 performance](https://supabase.com/blog/pgvector-performance) blog posts to see what pgvector is capable of and how the above technique can be used to achieve the best results.


# Google Colab

Use Google Colab to manage your Supabase Vector store.

Google Colab is a hosted Jupyter Notebook service. It provides free access to computing resources, including GPUs and TPUs, and is well-suited to machine learning, data science, and education. We can use Colab to manage collections using [Supabase Vecs](/docs/guides/ai/vecs-python-client).

In this tutorial we'll connect to a database running on the Supabase [platform](https://supabase.com/dashboard/). If you don't already have a database, you can create one here: [database.new](https://database.new).


## Create a new notebook

Start by visiting [colab.research.google.com](https://colab.research.google.com/). There you can create a new notebook.

![Google Colab new notebook](/docs/img/ai/google-colab/colab-new.png)


## Install Vecs

We'll use the Supabase Vector client, [Vecs](/docs/guides/ai/vecs-python-client), to manage our collections.

At the top of the notebook add the notebook paste the following code and hit the "execute" button (`ctrl+enter`):

```py
pip install vecs
```

![Install vecs](/docs/img/ai/google-colab/install-vecs.png)


## Connect to your database

Find the Postgres pooler connection string for your Supabase project in the [database settings](https://supabase.com/dashboard/project/_/settings/database) of the dashboard. Copy the "URI" format, which should look something like `postgres://postgres.xxxx:password@xxxx.pooler.supabase.com:6543/postgres`

Create a new code block below the install block (`ctrl+m b`) and add the following code using the Postgres URI you copied above:

```py
import vecs

DB_CONNECTION = "postgres://postgres.xxxx:password@xxxx.pooler.supabase.com:6543/postgres"

# create vector store client
vx = vecs.create_client(DB_CONNECTION)
```

Execute the code block (`ctrl+enter`). If no errors were returned then your connection was successful.


## Create a collection

Now we're going to create a new collection and insert some documents.

Create a new code block below the install block (`ctrl+m b`). Add the following code to the code block and execute it (`ctrl+enter`):

```py
collection = vx.get_or_create_collection(name="colab_collection", dimension=3)

collection.upsert(
    vectors=[
        (
         "vec0",           # the vector's identifier
         [0.1, 0.2, 0.3],  # the vector. list or np.array
         {"year": 1973}    # associated  metadata
        ),
        (
         "vec1",
         [0.7, 0.8, 0.9],
         {"year": 2012}
        )
    ]
)
```

This will create a table inside your database within the `vecs` schema, called `colab_collection`. You can view the inserted items in the [Table Editor](https://supabase.com/dashboard/project/_/editor/), by selecting the `vecs` schema from the schema dropdown.

![Colab documents](/docs/img/ai/google-colab/colab-documents.png)


## Query your documents

Now we can search for documents based on their similarity. Create a new code block and execute the following code:

```py
collection.query(
    query_vector=[0.4,0.5,0.6],  # required
    limit=5,                     # number of records to return
    filters={},                  # metadata filters
    measure="cosine_distance",   # distance measure to use
    include_value=False,         # should distance measure values be returned?
    include_metadata=False,      # should record metadata be returned?
)
```

You will see that this returns two documents in an array `['vec1', 'vec0']`:

![Colab results](/docs/img/ai/google-colab/colab-results.png)

It also returns a warning:

    Query does not have a covering index for cosine_distance.

You can lean more about creating indexes in the [Vecs documentation](https://supabase.github.io/vecs/api/#create-an-index).


## Resources

*   Vecs API: [supabase.github.io/vecs/api](https://supabase.github.io/vecs/api)


# Hugging Face Inference API



[Hugging Face](https://huggingface.co) is an open source hub for AI/ML models and tools. With over 100,000 machine learning models available, Hugging Face provides a great way to integrate specialized AI & ML tasks into your application.

There are 3 ways to use Hugging Face models in your application:

1.  Use the [Transformers](https://huggingface.co/docs/transformers/index) Python library to perform inference in a Python backend.
2.  [Generate embeddings](/docs/guides/ai/quickstarts/generate-text-embeddings) directly in Edge Functions using Transformers.js.
3.  Use Hugging Face's hosted [Inference API](https://huggingface.co/inference-api) to execute AI tasks remotely on Hugging Face servers. This guide will walk you through this approach.


## AI tasks

Below are some of the types of tasks you can perform with Hugging Face:


### Natural language

*   [Summarization](https://huggingface.co/tasks/summarization)
*   [Text classification](https://huggingface.co/tasks/text-classification)
*   [Text generation](https://huggingface.co/tasks/text-generation)
*   [Translation](https://huggingface.co/tasks/translation)
*   [Fill in the blank](https://huggingface.co/tasks/fill-mask)


### Computer vision

*   [Image to text](https://huggingface.co/tasks/image-to-text)
*   [Text to image](https://huggingface.co/tasks/text-to-image)
*   [Image classification](https://huggingface.co/tasks/image-classification)
*   [Video classification](https://huggingface.co/tasks/video-classification)
*   [Object detection](https://huggingface.co/tasks/object-detection)
*   [Image segmentation](https://huggingface.co/tasks/image-segmentation)


### Audio

*   [Text to speech](https://huggingface.co/tasks/text-to-speech)
*   [Speech to text](https://huggingface.co/tasks/automatic-speech-recognition)
*   [Audio classification](https://huggingface.co/tasks/audio-classification)

See a [full list of tasks](https://huggingface.co/tasks).


## Access token

First generate a Hugging Face access token for your app:

https://huggingface.co/settings/tokens

Name your token based on the app its being used for and the environment. For example, if you are building an image generation app you might create 2 tokens:

*   "Image Generator (Dev)"
*   "Image Generator (Prod)"

Since we will be using this token for the inference API, choose the `read` role.


## Edge Functions

Edge Functions are server-side TypeScript functions that run on-demand. Since Edge Functions run on a server, you can safely give them access to your Hugging Face access token.

To create a new Edge Function, navigate to your local project and initialize Supabase if you haven't already:

```shell
supabase init
```

Then create an Edge Function:

```shell
supabase functions new text-to-image
```

Create a file called `.env.local` to store your Hugging Face access token:

```shell
HUGGING_FACE_ACCESS_TOKEN=<your-token-here>
```

Let's modify the Edge Function to import Hugging Face's inference client and perform a `text-to-image` request:

```ts
import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
import { HfInference } from 'https://esm.sh/@huggingface/inference@2.3.2'

const hf = new HfInference(Deno.env.get('HUGGING_FACE_ACCESS_TOKEN'))

serve(async (req) => {
  const { prompt } = await req.json()

  const image = await hf.textToImage(
    {
      inputs: prompt,
      model: 'stabilityai/stable-diffusion-2',
    },
    {
      use_cache: false,
    }
  )

  return new Response(image)
})
```

1.  This function creates a new instance of `HfInference` using the `HUGGING_FACE_ACCESS_TOKEN` environment variable.

2.  It expects a POST request that includes a JSON request body. The JSON body should include a parameter called `prompt` that represents the text-to-image prompt that we will pass to Hugging Face's inference API.

3.  Next we call `textToImage()`, passing in the user's prompt along with the model that we would like to use for the image generation. Today Hugging Face recommends `stabilityai/stable-diffusion-2`, but you can change this to any other text-to-image model. You can see a list of which models are supported for each task by navigating to their [models page](https://huggingface.co/models?pipeline_tag=text-to-image) and filtering by task.

4.  We set `use_cache` to `false` so that repeat queries with the same prompt will produce new images. If the task and model you are using is deterministic (will always produce the same result based on the same input), consider setting `use_cache` to `true` for faster responses.

5.  The `image` result returned from the API will be a `Blob`. We can pass the `Blob` directly into a `new Response()` which will automatically set the content type and body of the response from the `image`.

Finally let's serve the Edge Function locally to test it:

```shell
supabase functions serve --env-file .env.local --no-verify-jwt
```

Remember to pass in the `.env.local` file using the `--env-file` parameter so that the Edge Function can access the `HUGGING_FACE_ACCESS_TOKEN`.

At this point, you can make an API request to your Edge Function using your preferred frontend framework (Next.js, React, Expo, etc). We can also test from the terminal using `curl`:

```shell
curl --output result.jpg --location --request POST 'http://localhost:54321/functions/v1/text-to-image' \
  --header 'Content-Type: application/json' \
  --data '{"prompt":"Llama wearing sunglasses"}'
```

In this example, your generated image will save to `result.jpg`:


## Next steps

You can now create an Edge Function that invokes a Hugging Face task using your model of choice.

Try running some other [AI tasks](#ai-tasks).


## Resources

*   Official [Hugging Face site](https://huggingface.co/).
*   Official [Hugging Face JS docs](https://huggingface.co/docs/huggingface.js).
*   [Generate image captions](/docs/guides/ai/examples/huggingface-image-captioning) using Hugging Face.


# Hybrid search

Combine keyword search with semantic search.

Hybrid search combines [full text search](/docs/guides/ai/keyword-search) (searching by keyword) with [semantic search](/docs/guides/ai/semantic-search) (searching by meaning) to identify results that are both directly and contextually relevant to the user's query.


## Use cases for hybrid search

Sometimes a single search method doesn't quite capture what a user is really looking for. For example, if a user searches for "Italian recipes with tomato sauce" on a cooking app, a keyword search would pull up recipes that specifically mention "Italian," "recipes," and "tomato sauce" in the text. However, it might miss out on dishes that are quintessentially Italian and use tomato sauce but don't explicitly label themselves with these words, or use variations like "pasta sauce" or "marinara." On the other hand, a semantic search might understand the culinary context and find recipes that match the intent, such as a traditional "Spaghetti Marinara," even if they don't match the exact keyword phrase. However, it could also suggest recipes that are contextually related but not what the user is looking for, like a "Mexican salsa" recipe, because it understands the context to be broadly about tomato-based sauces.

Hybrid search combines the strengths of both these methods. It would ensure that recipes explicitly mentioning the keywords are prioritized, thus capturing direct hits that satisfy the keyword criteria. At the same time, it would include recipes identified through semantic understanding as being related in meaning or context, like different Italian dishes that traditionally use tomato sauce but might not have been tagged explicitly with the user's search terms. It identifies results that are both directly and contextually relevant to the user's query while ideally minimizing misses and irrelevant suggestions.


## When to consider hybrid search

The decision to use hybrid search depends on what your users are looking for in your app. For a code repository where developers need to find exact lines of code or error messages, keyword search is likely ideal because it matches specific terms. In a mental health forum where users search for advice or experiences related to their feelings, semantic search may be better because it finds results based on the meaning of a query, not just specific words. For a shopping app where customers might search for specific product names yet also be open to related suggestions, hybrid search combines the best of both worlds - finding exact matches while also uncovering similar products based on the shopping context.


## How to combine search methods

Hybrid search merges keyword search and semantic search, but how does this process work?

First, each search method is executed separately. Keyword search, which involves searching by specific words or phrases present in the content, will yield its own set of results. Similarly, semantic search, which involves understanding the context or meaning behind the search query rather than the specific words used, will generate its own unique results.

Now with these separate result lists available, the next step is to combine them into a single, unified list. This is achieved through a process known as “fusion”. Fusion takes the results from both search methods and merges them together based on a certain ranking or scoring system. This system may prioritize certain results based on factors like their relevance to the search query, their ranking in the individual lists, or other criteria. The result is a final list that integrates the strengths of both keyword and semantic search methods.


## Reciprocal Ranked Fusion (RRF)

One of the most common fusion methods is Reciprocal Ranked Fusion (RRF). The key idea behind RRF is to give more weight to the top-ranked items in each individual result list when building the final combined list.

In RRF, we iterate over each record and assign a score (noting that each record could exist in one or both lists). The score is calculated as 1 divided by that record's rank in each list, summed together between both lists. For example, if a record with an ID of `123` was ranked third in the keyword search and ninth in semantic search, it would receive a score of $$\dfrac + \dfrac = 0.444$$. If the record was found in only one list and not the other, it would receive a score of 0 for the other list. The records are then sorted by this score to create the final list. The items with the highest scores are ranked first, and lowest scores ranked last.

This method ensures that items that are ranked high in multiple lists are given a high rank in the final list. It also ensures that items that are ranked high in only a few lists but low in others are not given a high rank in the final list. Placing the rank in the denominator when calculating score helps penalize the low ranking records.


### Smoothing constant `k`

To prevent extremely high scores for items that are ranked first (since we're dividing by the rank), a `k` constant is often added to the denominator to smooth the score:

$$\dfrac$$

This constant can be any positive number, but is typically small. A constant of 1 would mean that a record ranked first would have a score of $$\dfrac = 0.5$$ instead of $$1$$. This adjustment can help balance the influence of items that are ranked very high in individual lists when creating the final combined list.


## Hybrid search in Postgres

Let's implement hybrid search in Postgres using `tsvector` (keyword search) and `pgvector` (semantic search).

First we'll create a `documents` table to store the documents that we will search over. This is just an example - adjust this to match the structure of your application.

```sql
create table documents (
  id bigint primary key generated always as identity,
  content text,
  fts tsvector generated always as (to_tsvector('english', content)) stored,
  embedding vector(512)
);
```

The table contains 4 columns:

*   `id` is an auto-generated unique ID for the record. We'll use this later to match records when performing RRF.
*   `content` contains the actual text we will be searching over.
*   `fts` is an auto-generated `tsvector` column that is generated using the text in `content`. We will use this for [full text search](/docs/guides/database/full-text-search) (search by keyword).
*   `embedding` is a [vector column](/docs/guides/ai/vector-columns) that stores the vector generated from our embedding model. We will use this for [semantic search](/docs/guides/ai/semantic-search) (search by meaning). We chose 512 dimensions for this example, but adjust this to match the size of the embedding vectors generated from your preferred model.

Next we'll create indexes on the `fts` and `embedding` columns so that their individual queries will remain fast at scale:

```sql
-- Create an index for the full-text search
create index on documents using gin(fts);

-- Create an index for the semantic vector search
create index on documents using hnsw (embedding vector_ip_ops);
```

For full text search we use a [generalized inverted (GIN) index](https://www.postgresql.org/docs/current/gin-intro.html) which is designed for handling composite values like those stored in a `tsvector`.

For semantic vector search we use an [HNSW index](/docs/guides/ai/vector-indexes/hnsw-indexes), which is a high performing approximate nearest neighbor (ANN) search algorithm. Note that we are using the `vector_ip_ops` (inner product) operator with this index because we plan on using the inner product (`<#>`) operator later in our query. If you plan to use a different operator like cosine distance (`<=>`), be sure to update the index accordingly. For more information, see [distance operators](/docs/guides/ai/vector-indexes#distance-operators).

Finally we'll create our `hybrid_search` function:

```sql
create or replace function hybrid_search(
  query_text text,
  query_embedding vector(512),
  match_count int,
  full_text_weight float = 1,
  semantic_weight float = 1,
  rrf_k int = 50
)
returns setof documents
language sql
as $$
with full_text as (
  select
    id,
    -- Note: ts_rank_cd is not indexable but will only rank matches of the where clause
    -- which shouldn't be too big
    row_number() over(order by ts_rank_cd(fts, websearch_to_tsquery(query_text)) desc) as rank_ix
  from
    documents
  where
    fts @@ websearch_to_tsquery(query_text)
  order by rank_ix
  limit least(match_count, 30) * 2
),
semantic as (
  select
    id,
    row_number() over (order by embedding <#> query_embedding) as rank_ix
  from
    documents
  order by rank_ix
  limit least(match_count, 30) * 2
)
select
  documents.*
from
  full_text
  full outer join semantic
    on full_text.id = semantic.id
  join documents
    on coalesce(full_text.id, semantic.id) = documents.id
order by
  coalesce(1.0 / (rrf_k + full_text.rank_ix), 0.0) * full_text_weight +
  coalesce(1.0 / (rrf_k + semantic.rank_ix), 0.0) * semantic_weight
  desc
limit
  least(match_count, 30)
$$;
```

Let's break this down:

*   **Parameters:** The function accepts quite a few parameters, but the main (required) ones are `query_text`, `query_embedding`, and `match_count`.

    *   `query_text` is the user's query text (more on this shortly)
    *   `query_embedding` is the vector representation of the user's query produced by the embedding model. We chose 512 dimensions for this example, but adjust this to match the size of the embedding vectors generated from your preferred model. This must match the size of the `embedding` vector on the `documents` table (and use the same model).
    *   `match_count` is the number of records returned in the `limit` clause.

    The other parameters are optional, but give more control over the fusion process.

    *   `full_text_weight` and `semantic_weight` decide how much weight each search method gets in the final score. These are both 1 by default which means they both equally contribute towards the final rank. A `full_text_weight` of 2 and `semantic_weight` of 1 would give full-text search twice as much weight as semantic search.
    *   `rrf_k` is the `k` [smoothing constant](#smoothing-constant-k) added to the reciprocal rank. The default is 50.

*   **Return type:** The function returns a set of records from our `documents` table.

*   **CTE:** We create two [common table expressions (CTE)](https://www.postgresql.org/docs/current/queries-with.html), one for full-text search and one for semantic search. These perform each query individually prior to joining them.

*   **RRF:** The final query combines the results from the two CTEs using [reciprocal rank fusion (RRF)](#reciprocal-ranked-fusion-rrf).


## Running hybrid search

To use this function in SQL, we can run:

```sql
select
  *
from
  hybrid_search(
    'Italian recipes with tomato sauce', -- user query
    '[...]'::vector(512), -- embedding generated from user query
    10
  );
```

In practice, you will likely be calling this from the [Supabase client](/docs/reference/javascript/introduction) or through a custom backend layer. Here is a quick example of how you might call this from an [Edge Function](/docs/guides/functions) using JavaScript:

```tsx
import { createClient } from 'jsr:@supabase/supabase-js@2'
import OpenAI from 'npm:openai'

const supabaseUrl = Deno.env.get('SUPABASE_URL')!
const supabaseServiceRoleKey = Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!
const openaiApiKey = Deno.env.get('OPENAI_API_KEY')!

Deno.serve(async (req) => {
  // Grab the user's query from the JSON payload
  const { query } = await req.json()

  // Instantiate OpenAI client
  const openai = new OpenAI({ apiKey: openaiApiKey })

  // Generate a one-time embedding for the user's query
  const embeddingResponse = await openai.embeddings.create({
    model: 'text-embedding-3-large',
    input: query,
    dimensions: 512,
  })

  const [{ embedding }] = embeddingResponse.data

  // Instantiate the Supabase client
  // (replace service role key with user's JWT if using Supabase auth and RLS)
  const supabase = createClient(supabaseUrl, supabaseServiceRoleKey)

  // Call hybrid_search Postgres function via RPC
  const { data: documents } = await supabase.rpc('hybrid_search', {
    query_text: query,
    query_embedding: embedding,
    match_count: 10,
  })

  return new Response(JSON.stringify(documents), {
    headers: { 'Content-Type': 'application/json' },
  })
})
```

This uses OpenAI's `text-embedding-3-large` model to generate embeddings (shortened to 512 dimensions for faster retrieval). Swap in your preferred embedding model (and dimension size) accordingly.

To test this, make a `POST` request to the function's endpoint while passing in a JSON payload containing the user's query. Here is an example `POST` request using cURL:

```tsx
curl -i --location --request POST \
  'http://127.0.0.1:54321/functions/v1/hybrid-search' \
  --header 'Authorization: Bearer <anonymous key>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"Italian recipes with tomato sauce"}'
```

For more information on how to create, test, and deploy edge functions, see [Getting started](/docs/guides/functions/quickstart).


## See also

*   [Embedding concepts](/docs/guides/ai/concepts)
*   [Vector columns](/docs/guides/ai/vector-columns)
*   [Vector indexes](/docs/guides/ai/vector-indexes)
*   [Semantic search](/docs/guides/ai/semantic-search)
*   [Full text (keyword) search](/docs/guides/database/full-text-search)


# Amazon Bedrock



[Amazon Bedrock](https://aws.amazon.com/bedrock) is a fully managed service that offers a choice of high-performing foundation models (FMs) from leading AI companies like AI21 Labs, Anthropic, Cohere, Meta, Mistral AI, Stability AI, and Amazon. Each model is accessible through a common API which implements a broad set of features to help build generative AI applications with security, privacy, and responsible AI in mind.

This guide will walk you through an example using Amazon Bedrock SDK with `vecs`. We will create embeddings using the Amazon Titan Embeddings G1 – Text v1.2 (amazon.titan-embed-text-v1) model, insert these embeddings into a Postgres database using vecs, and then query the collection to find the most similar sentences to a given query sentence.


## Create an environment

First, you need to set up your environment. You will need Python 3.7+ with the `vecs` and `boto3` libraries installed.

You can install the necessary Python libraries using pip:

```sh
pip install vecs boto3
```

You'll also need:

*   [Credentials to your AWS account](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html)
*   [A Postgres Database with the pgvector extension](hosting.md)


## Create embeddings

Next, we will use Amazon’s Titan Embedding G1 - Text v1.2 model to create embeddings for a set of sentences.

```python
import boto3
import vecs
import json

client = boto3.client(
    'bedrock-runtime',
    region_name='us-east-1',
	# Credentials from your AWS account
    aws_access_key_id='<replace_your_own_credentials>',
    aws_secret_access_key='<replace_your_own_credentials>',
    aws_session_token='<replace_your_own_credentials>',
)

dataset = [
    "The cat sat on the mat.",
    "The quick brown fox jumps over the lazy dog.",
    "Friends, Romans, countrymen, lend me your ears",
    "To be or not to be, that is the question.",
]

embeddings = []

for sentence in dataset:
    # invoke the embeddings model for each sentence
    response = client.invoke_model(
        body= json.dumps({"inputText": sentence}),
        modelId= "amazon.titan-embed-text-v1",
        accept = "application/json",
        contentType = "application/json"
    )
    # collect the embedding from the response
    response_body = json.loads(response["body"].read())
    # add the embedding to the embedding list
    embeddings.append((sentence, response_body.get("embedding"), {}))

```


### Store the embeddings with vecs

Now that we have our embeddings, we can insert them into a Postgres database using vecs.

```python
import vecs

DB_CONNECTION = "postgresql://<user>:<password>@<host>:<port>/<db_name>"

# create vector store client
vx = vecs.Client(DB_CONNECTION)

# create a collection named 'sentences' with 1536 dimensional vectors
# to match the default dimension of the Titan Embeddings G1 - Text model
sentences = vx.get_or_create_collection(name="sentences", dimension=1536)

# upsert the embeddings into the 'sentences' collection
sentences.upsert(records=embeddings)

# create an index for the 'sentences' collection
sentences.create_index()
```


### Querying for most similar sentences

Now, we query the `sentences` collection to find the most similar sentences to a sample query sentence. First need to create an embedding for the query sentence. Next, we query the collection we created earlier to find the most similar sentences.

```python
query_sentence = "A quick animal jumps over a lazy one."

# create vector store client
vx = vecs.Client(DB_CONNECTION)

# create an embedding for the query sentence
response = client.invoke_model(
        body= json.dumps({"inputText": query_sentence}),
        modelId= "amazon.titan-embed-text-v1",
        accept = "application/json",
        contentType = "application/json"
    )

response_body = json.loads(response["body"].read())

query_embedding = response_body.get("embedding")

# query the 'sentences' collection for the most similar sentences
results = sentences.query(
    data=query_embedding,
    limit=3,
    include_value = True
)

# print the results
for result in results:
    print(result)
```

This returns the most similar 3 records and their distance to the query vector.

    ('The quick brown fox jumps over the lazy dog.', 0.27600620558852)
    ('The cat sat on the mat.', 0.609986272479202)
    ('To be or not to be, that is the question.', 0.744849503688346)


## Resources

*   [Amazon Bedrock](https://aws.amazon.com/bedrock)
*   [Amazon Titan](https://aws.amazon.com/bedrock/titan)
*   [Semantic Image Search with Amazon Titan](/docs/guides/ai/examples/semantic-image-search-amazon-titan)


# Learn how to integrate Supabase with LlamaIndex, a data framework for your LLM applications.

Learn how to integrate Supabase with LlamaIndex, a data framework for your LLM applications.

This guide will walk you through a basic example using the LlamaIndex [`SupabaseVectorStore`](https://github.com/supabase/supabase/blob/master/examples/ai/llamaindex/llamaindex.ipynb).


## Launching a notebook

Launch our [LlamaIndex](https://github.com/supabase/supabase/blob/master/examples/ai/llamaindex/llamaindex.ipynb) notebook in Colab:

At the top of the notebook, you'll see a button `Copy to Drive`. Click this button to copy the notebook to your Google Drive.


## Fill in your OpenAI credentials

Inside the Notebook, add your `OPENAI_API_KEY` key. Find the cell which contains this code:

```py
import os
os.environ['OPENAI_API_KEY'] = "[your_openai_api_key]"
```


## Connecting to your database

Inside the Notebook, find the cell which specifies the `DB_CONNECTION`. It will contain some code like this:

```python
DB_CONNECTION = "postgresql://<user>:<password>@<host>:<port>/<db_name>"

# create vector store client
vx = vecs.create_client(DB_CONNECTION)
```

Replace the `DB_CONNECTION` with your own connection string for your database. You can find the Postgres connection string in the [Database Settings](https://supabase.com/dashboard/project/_/settings/database) of your Supabase project.


## Stepping through the notebook

Now all that's left is to step through the notebook. You can do this by clicking the "execute" button (`ctrl+enter`) at the top left of each code cell. The notebook guides you through the process of creating a collection, adding data to it, and querying it.

You can view the inserted items in the [Table Editor](https://supabase.com/dashboard/project/_/editor/), by selecting the `vecs` schema from the schema dropdown.

![Colab documents](/docs/img/ai/google-colab/colab-documents.png)


## Resources

*   Visit the LlamaIndex + `SupabaseVectorStore` [docs](https://gpt-index.readthedocs.io/en/latest/examples/vector_stores/SupabaseVectorIndexDemo.html)
*   Visit the official LlamaIndex [repo](https://github.com/jerryjliu/llama_index/)


# Roboflow

Learn how to integrate Supabase with Roboflow, a tool for running fine-tuned and foundation vision models.

In this guide, we will walk through two examples of using [Roboflow Inference](https://inference.roboflow.com) to run fine-tuned and foundation models. We will run inference and save predictions using an object detection model and [CLIP](https://github.com/openai/CLIP).


## Save computer vision predictions

Once you have a trained vision model, you need to create business logic for your application. In many cases, you want to save inference results to a file.

The steps below show you how to run a vision model locally and save predictions to Supabase.


### Preparation: Set up a model

Before you begin, you will need an object detection model trained on your data.

You can [train a model on Roboflow](https://blog.roboflow.com/getting-started-with-roboflow/), leveraging end-to-end tools from data management and annotation to deployment, or [upload custom model weights](https://docs.roboflow.com/deploy/upload-custom-weights) for deployment.

All models have an infinitely scalable API through which you can query your model, and can be run locally.

For this guide, we will use a demo [rock, paper, scissors](https://universe.roboflow.com/roboflow-58fyf/rock-paper-scissors-sxsw) model.


### Step 1: Install and start Roboflow Inference

You will deploy our model locally using Roboflow Inference, a computer vision inference server.

To install and start Roboflow Inference, first install Docker on your machine.

Then, run:

    pip install inference inference-cli inference-sdk && inference server start

An inference server will be available at `http://localhost:9001`.


### Step 2: Run inference on an image

You can run inference on images and videos. Let's run inference on an image.

Create a new Python file and add the following code:

```python
from inference_sdk import InferenceHTTPClient

image = "example.jpg"
MODEL_ID = "rock-paper-scissors-sxsw/11"

client = InferenceHTTPClient(
    api_url="http://localhost:9001",
    api_key="ROBOFLOW_API_KEY"
)
with client.use_model(MODEL_ID):
    predictions = client.infer(image)

print(predictions)
```

Above, replace:

1.  The image URL with the name of the image on which you want to run inference.
2.  `ROBOFLOW_API_KEY` with your Roboflow API key. [Learn how to retrieve your Roboflow API key](https://docs.roboflow.com/api-reference/authentication#retrieve-an-api-key).
3.  `MODEL_ID` with your Roboflow model ID. [Learn how to retrieve your model ID](https://docs.roboflow.com/api-reference/workspace-and-project-ids).

When you run the code above, a list of predictions will be printed to the console:

    {'time': 0.05402109300121083, 'image': {'width': 640, 'height': 480}, 'predictions': [{'x': 312.5, 'y': 392.0, 'width': 255.0, 'height': 110.0, 'confidence': 0.8620790839195251, 'class': 'Paper', 'class_id': 0}]}


### Step 3: Save results in Supabase

To save results in Supabase, add the following code to your script:

```python
import os
from supabase import create_client, Client

url: str = os.environ.get("SUPABASE_URL")
key: str = os.environ.get("SUPABASE_KEY")
supabase: Client = create_client(url, key)

result = supabase.table('predictions') \
    .insert({"filename": image, "predictions": predictions}) \
    .execute()
```

You can then query your predictions using the following code:

```python
result = supabase.table('predictions') \
    .select("predictions") \
    .filter("filename", "eq", image) \
    .execute()

print(result)
```

Here is an example result:

    data=[{'predictions': {'time': 0.08492901099998562, 'image': {'width': 640, 'height': 480}, 'predictions': [{'x': 312.5, 'y': 392.0, 'width': 255.0, 'height': 110.0, 'confidence': 0.8620790839195251, 'class': 'Paper', 'class_id': 0}]}}, {'predictions': {'time': 0.08818970100037404, 'image': {'width': 640, 'height': 480}, 'predictions': [{'x': 312.5, 'y': 392.0, 'width': 255.0, 'height': 110.0, 'confidence': 0.8620790839195251, 'class': 'Paper', 'class_id': 0}]}}] count=None


## Calculate and save CLIP embeddings

You can use the Supabase vector database functionality to store and query CLIP embeddings.

Roboflow Inference provides a HTTP interface through which you can calculate image and text embeddings using CLIP.


### Step 1: Install and start Roboflow Inference

See [Step #1: Install and Start Roboflow Inference](#step-1-install-and-start-roboflow-inference) above to install and start Roboflow Inference.


### Step 2: Run CLIP on an image

Create a new Python file and add the following code:

```python
import cv2
import supervision as sv
import requests
import base64
import os

IMAGE_DIR = "images/train/images/"
API_KEY = ""
SERVER_URL = "http://localhost:9001"

results = []

for i, image in enumerate(os.listdir(IMAGE_DIR)):
    print(f"Processing image {image}")
    infer_clip_payload = {
        "image": {
            "type": "base64",
            "value": base64.b64encode(open(IMAGE_DIR + image, "rb").read()).decode("utf-8"),
        },
    }

    res = requests.post(
        f"{SERVER_URL}/clip/embed_image?api_key={API_KEY}",
        json=infer_clip_payload,
    )

    embeddings = res.json()['embeddings']

    results.append({
        "filename": image,
        "embeddings": embeddings
    })
```

This code will calculate CLIP embeddings for each image in the directory and print the results to the console.

Above, replace:

1.  `IMAGE_DIR` with the directory containing the images on which you want to run inference.
2.  `ROBOFLOW_API_KEY` with your Roboflow API key. [Learn how to retrieve your Roboflow API key](https://docs.roboflow.com/api-reference/authentication#retrieve-an-api-key).

You can also calculate CLIP embeddings in the cloud by setting `SERVER_URL` to `https://infer.roboflow.com`.


### Step 3: Save embeddings in Supabase

You can store your image embeddings in Supabase using the Supabase `vecs` Python package:

First, install `vecs`:

    pip install vecs

Next, add the following code to your script to create an index:

```python

import vecs

DB_CONNECTION = "postgresql://postgres:[password]@[host]:[port]/[database]"

vx = vecs.create_client(DB_CONNECTION)

# create a collection of vectors with 3 dimensions
images = vx.get_or_create_collection(name="image_vectors", dimension=512)

for result in results:
    image = result["filename"]
    embeddings = result["embeddings"][0]

    # insert a vector into the collection
    images.upsert(
        records=[
            (
                image,
                embeddings,
                {} # metadata
            )
        ]
    )

images.create_index()
```

Replace `DB_CONNECTION` with the authentication information for your database. You can retrieve this from the Supabase dashboard in `Project Settings > Database Settings`.

You can then query your embeddings using the following code:

```python
infer_clip_payload = {
    "text": "cat",
}

res = requests.post(
    f"{SERVER_URL}/clip/embed_text?api_key={API_KEY}",
    json=infer_clip_payload,
)

embeddings = res.json()['embeddings']

result = images.query(
    data=embeddings[0],
    limit=1
)

print(result[0])
```


## Resources

*   [Roboflow Inference documentation](https://inference.roboflow.com)
*   [Roboflow Getting Started guide](https://blog.roboflow.com/getting-started-with-roboflow/)
*   [How to Build a Semantic Image Search Engine with Supabase and OpenAI CLIP](https://blog.roboflow.com/how-to-use-semantic-search-supabase-openai-clip/)


# Keyword search

Learn how to search by words or phrases.

Keyword search involves locating documents or records that contain specific words or phrases, primarily based on the exact match between the search terms and the text within the data. It differs from [semantic search](/docs/guides/ai/semantic-search), which interprets the meaning behind the query to provide results that are contextually related, even if the exact words aren't present in the text. Semantic search considers synonyms, intent, and natural language nuances to provide a more nuanced approach to information retrieval.

In Postgres, keyword search is implemented using [full-text search](/docs/guides/database/full-text-search). It supports indexing and text analysis for data retrieval, focusing on records that match the search criteria. Postgres' full-text search extends beyond simple keyword matching to address linguistic nuances, making it effective for applications that require precise text queries.


## When and why to use keyword search

Keyword search is particularly useful in scenarios where precision and specificity matter. It's more effective than semantic search when users are looking for information using exact terminology or specific identifiers. It ensures that results directly contain those terms, reducing the chance of retrieving irrelevant information that might be semantically related but not what the user seeks.

For example in technical or academic research databases, researchers often search for specific studies, compounds, or concepts identified by certain terms or codes. Searching for a specific chemical compound using its exact molecular formula or a unique identifier will yield more focused and relevant results compared to a semantic search, which could return a wide range of documents discussing the compound in different contexts. Keyword search ensures documents that explicitly mention the exact term are found, allowing users to access the precise data they need efficiently.

It's also possible to combine keyword search with semantic search to get the best of both worlds. See [Hybrid search](/docs/guides/ai/hybrid-search) for more details.


## Using full-text search

For an in-depth guide to Postgres' full-text search, including how to store, index, and query records, see [Full text search](/docs/guides/database/full-text-search).


## See also

*   [Semantic search](/docs/guides/ai/semantic-search)
*   [Hybrid search](/docs/guides/ai/hybrid-search)


# LangChain



[LangChain](https://langchain.com/) is a popular framework for working with AI, Vectors, and embeddings. LangChain supports using Supabase as a [vector store](https://js.langchain.com/docs/modules/indexes/vector_stores/integrations/supabase), using the `pgvector` extension.


## Initializing your database

Prepare you database with the relevant tables:


## Usage

You can now search your documents using any Node.js application. This is intended to be run on a secure server route.

```js
import { SupabaseVectorStore } from 'langchain/vectorstores/supabase'
import { OpenAIEmbeddings } from 'langchain/embeddings/openai'
import { createClient } from '@supabase/supabase-js'

const supabaseKey = process.env.SUPABASE_SERVICE_ROLE_KEY
if (!supabaseKey) throw new Error(`Expected SUPABASE_SERVICE_ROLE_KEY`)

const url = process.env.SUPABASE_URL
if (!url) throw new Error(`Expected env var SUPABASE_URL`)

export const run = async () => {
  const client = createClient(url, supabaseKey)

  const vectorStore = await SupabaseVectorStore.fromTexts(
    ['Hello world', 'Bye bye', "What's this?"],
    [{ id: 2 }, { id: 1 }, { id: 3 }],
    new OpenAIEmbeddings(),
    {
      client,
      tableName: 'documents',
      queryName: 'match_documents',
    }
  )

  const resultOne = await vectorStore.similaritySearch('Hello world', 1)

  console.log(resultOne)
}
```


### Simple metadata filtering

Given the above `match_documents` Postgres function, you can also pass a filter parameter to only return documents with a specific metadata field value. This filter parameter is a JSON object, and the `match_documents` function will use the Postgres JSONB Containment operator `@>` to filter documents by the metadata field values you specify. See details on the [Postgres JSONB Containment operator](https://www.postgresql.org/docs/current/datatype-json.html#JSON-CONTAINMENT) for more information.

```js
import { SupabaseVectorStore } from 'langchain/vectorstores/supabase'
import { OpenAIEmbeddings } from 'langchain/embeddings/openai'
import { createClient } from '@supabase/supabase-js'

// First, follow set-up instructions above

const privateKey = process.env.SUPABASE_SERVICE_ROLE_KEY
if (!privateKey) throw new Error(`Expected env var SUPABASE_SERVICE_ROLE_KEY`)

const url = process.env.SUPABASE_URL
if (!url) throw new Error(`Expected env var SUPABASE_URL`)

export const run = async () => {
  const client = createClient(url, privateKey)

  const vectorStore = await SupabaseVectorStore.fromTexts(
    ['Hello world', 'Hello world', 'Hello world'],
    [{ user_id: 2 }, { user_id: 1 }, { user_id: 3 }],
    new OpenAIEmbeddings(),
    {
      client,
      tableName: 'documents',
      queryName: 'match_documents',
    }
  )

  const result = await vectorStore.similaritySearch('Hello world', 1, {
    user_id: 3,
  })

  console.log(result)
}
```


### Advanced metadata filtering

You can also use query builder-style filtering ([similar to how the Supabase JavaScript library works](https://supabase.com/docs/reference/javascript/using-filters)) instead of passing an object. Note that since the filter properties will be in the metadata column, you need to use arrow operators (`->` for integer or `->>` for text) as defined in [PostgREST API documentation](https://postgrest.org/en/stable/references/api/tables_views.html?highlight=operators#json-columns) and specify the data type of the property (e.g. the column should look something like `metadata->some_int_value::int`).

```js
import { SupabaseFilterRPCCall, SupabaseVectorStore } from 'langchain/vectorstores/supabase'
import { OpenAIEmbeddings } from 'langchain/embeddings/openai'
import { createClient } from '@supabase/supabase-js'

// First, follow set-up instructions above

const privateKey = process.env.SUPABASE_SERVICE_ROLE_KEY
if (!privateKey) throw new Error(`Expected env var SUPABASE_SERVICE_ROLE_KEY`)

const url = process.env.SUPABASE_URL
if (!url) throw new Error(`Expected env var SUPABASE_URL`)

export const run = async () => {
  const client = createClient(url, privateKey)

  const embeddings = new OpenAIEmbeddings()

  const store = new SupabaseVectorStore(embeddings, {
    client,
    tableName: 'documents',
  })

  const docs = [
    {
      pageContent:
        'This is a long text, but it actually means something because vector database does not understand Lorem Ipsum. So I would need to expand upon the notion of quantum fluff, a theoretical concept where subatomic particles coalesce to form transient multidimensional spaces. Yet, this abstraction holds no real-world application or comprehensible meaning, reflecting a cosmic puzzle.',
      metadata: { b: 1, c: 10, stuff: 'right' },
    },
    {
      pageContent:
        'This is a long text, but it actually means something because vector database does not understand Lorem Ipsum. So I would need to proceed by discussing the echo of virtual tweets in the binary corridors of the digital universe. Each tweet, like a pixelated canary, hums in an unseen frequency, a fascinatingly perplexing phenomenon that, while conjuring vivid imagery, lacks any concrete implication or real-world relevance, portraying a paradox of multidimensional spaces in the age of cyber folklore.',
      metadata: { b: 2, c: 9, stuff: 'right' },
    },
    { pageContent: 'hello', metadata: { b: 1, c: 9, stuff: 'right' } },
    { pageContent: 'hello', metadata: { b: 1, c: 9, stuff: 'wrong' } },
    { pageContent: 'hi', metadata: { b: 2, c: 8, stuff: 'right' } },
    { pageContent: 'bye', metadata: { b: 3, c: 7, stuff: 'right' } },
    { pageContent: "what's this", metadata: { b: 4, c: 6, stuff: 'right' } },
  ]

  await store.addDocuments(docs)

  const funcFilterA: SupabaseFilterRPCCall = (rpc) =>
    rpc
      .filter('metadata->b::int', 'lt', 3)
      .filter('metadata->c::int', 'gt', 7)
      .textSearch('content', `'multidimensional' & 'spaces'`, {
        config: 'english',
      })

  const resultA = await store.similaritySearch('quantum', 4, funcFilterA)

  const funcFilterB: SupabaseFilterRPCCall = (rpc) =>
    rpc
      .filter('metadata->b::int', 'lt', 3)
      .filter('metadata->c::int', 'gt', 7)
      .filter('metadata->>stuff', 'eq', 'right')

  const resultB = await store.similaritySearch('hello', 2, funcFilterB)

  console.log(resultA, resultB)
}
```


## Hybrid search

LangChain supports the concept of a hybrid search, which combines Similarity Search with Full Text Search. Read the official docs to get started: [Supabase Hybrid Search](https://js.langchain.com/docs/modules/indexes/retrievers/supabase-hybrid).

You can install the LangChain Hybrid Search function though our [database.dev package manager](https://database.dev/langchain/hybrid_search).


## Resources

*   Official [LangChain site](https://langchain.com/).
*   Official [LangChain docs](https://js.langchain.com/docs/modules/indexes/vector_stores/integrations/supabase).
*   Supabase [Hybrid Search](https://js.langchain.com/docs/modules/indexes/retrievers/supabase-hybrid).


# Choosing a Client



As described in [Structured & Unstructured Embeddings](/docs/guides/ai/structured-unstructured), AI workloads come in many forms.

For data science or ephemeral workloads, the [Supabase Vecs](https://supabase.github.io/vecs/) client gets you started quickly. All you need is a connection string and vecs handles setting up your database to store and query vectors with associated metadata.

For production python applications with version controlled migrations, we recommend adding first class vector support to your toolchain by [registering the vector type with your ORM](https://github.com/pgvector/pgvector-python). pgvector provides bindings for the most commonly used SQL drivers/libraries including Django, SQLAlchemy, SQLModel, psycopg, asyncpg and Peewee.


# Face similarity search

Identify the celebrities who look most similar to you using Supabase Vecs.

This guide will walk you through a ["Face Similarity Search"](https://github.com/supabase/supabase/blob/master/examples/ai/face_similarity.ipynb) example using Colab and Supabase Vecs. You will be able to identify the celebrities who look most similar to you (or any other person). You will:

1.  Launch a Postgres database that uses pgvector to store embeddings
2.  Launch a notebook that connects to your database
3.  Load the "`ashraq/tmdb-people-image`" celebrity dataset
4.  Use the `face_recognition` model to create an embedding for every celebrity photo.
5.  Search for similar faces inside the dataset.


## Launching a notebook

Launch our [`semantic_text_deduplication`](https://github.com/supabase/supabase/blob/master/examples/ai/face_similarity.ipynb) notebook in Colab:

At the top of the notebook, you'll see a button `Copy to Drive`. Click this button to copy the notebook to your Google Drive.


## Connecting to your database

Inside the Notebook, find the cell which specifies the `DB_CONNECTION`. It will contain some code like this:

```python
import vecs

DB_CONNECTION = "postgresql://<user>:<password>@<host>:<port>/<db_name>"

# create vector store client
vx = vecs.create_client(DB_CONNECTION)
```

Replace the `DB_CONNECTION` with your own connection string for your database. You can find the Postgres connection string in the [Database Settings](https://supabase.com/dashboard/project/_/settings/database) of your Supabase project.


## Stepping through the notebook

Now all that's left is to step through the notebook. You can do this by clicking the "execute" button (`ctrl+enter`) at the top left of each code cell. The notebook guides you through the process of creating a collection, adding data to it, and querying it.

You can view the inserted items in the [Table Editor](https://supabase.com/dashboard/project/_/editor/), by selecting the `vecs` schema from the schema dropdown.

![Colab documents](/docs/img/ai/google-colab/colab-documents.png)


## Next steps

You can now start building your own applications with Vecs. Check our [examples](/docs/guides/ai#examples) for ideas.


# Generate Embeddings

Generate text embeddings using Edge Functions.

This guide will walk you through how to generate high quality text embeddings in [Edge Functions](/docs/guides/functions) using its built-in AI inference API, so no external API is required.


## Build the Edge Function

Let's build an Edge Function that will accept an input string and generate an embedding for it. Edge Functions are server-side TypeScript HTTP endpoints that run on-demand closest to your users.


## Next steps

*   Learn more about [embedding concepts](/docs/guides/ai/concepts)
*   [Store your embeddings](/docs/guides/ai/vector-columns) in a database


# Creating and managing collections

Connecting to your database with Colab.

This guide will walk you through a basic ["Hello World"](https://github.com/supabase/supabase/blob/master/examples/ai/vector_hello_world.ipynb) example using Colab and Supabase Vecs. You'll learn how to:

1.  Launch a Postgres database that uses pgvector to store embeddings
2.  Launch a notebook that connects to your database
3.  Create a vector collection
4.  Add data to the collection
5.  Query the collection


## Launching a notebook

Launch our [`vector_hello_world`](https://github.com/supabase/supabase/blob/master/examples/ai/vector_hello_world.ipynb) notebook in Colab:

At the top of the notebook, you'll see a button `Copy to Drive`. Click this button to copy the notebook to your Google Drive.


## Connecting to your database

Inside the Notebook, find the cell which specifies the `DB_CONNECTION`. It will contain some code like this:

```python
import vecs

DB_CONNECTION = "postgresql://<user>:<password>@<host>:<port>/<db_name>"

# create vector store client
vx = vecs.create_client(DB_CONNECTION)
```

Replace the `DB_CONNECTION` with your own connection string for your database. You can find the Postgres connection string in the [Database Settings](https://supabase.com/dashboard/project/_/settings/database) of your Supabase project.


## Stepping through the notebook

Now all that's left is to step through the notebook. You can do this by clicking the "execute" button (`ctrl+enter`) at the top left of each code cell. The notebook guides you through the process of creating a collection, adding data to it, and querying it.

You can view the inserted items in the [Table Editor](https://supabase.com/dashboard/project/_/editor/), by selecting the `vecs` schema from the schema dropdown.

![Colab documents](/docs/img/ai/google-colab/colab-documents.png)


## Next steps

You can now start building your own applications with Vecs. Check our [examples](/docs/guides/ai#examples) for ideas.


# Semantic Text Deduplication

Finding duplicate movie reviews with Supabase Vecs.

This guide will walk you through a ["Semantic Text Deduplication"](https://github.com/supabase/supabase/blob/master/examples/ai/semantic_text_deduplication.ipynb) example using Colab and Supabase Vecs. You'll learn how to find similar movie reviews using embeddings, and remove any that seem like duplicates. You will:

1.  Launch a Postgres database that uses pgvector to store embeddings
2.  Launch a notebook that connects to your database
3.  Load the IMDB dataset
4.  Use the `sentence-transformers/all-MiniLM-L6-v2` model to create an embedding representing the semantic meaning of each review.
5.  Search for all duplicates.


## Launching a notebook

Launch our [`semantic_text_deduplication`](https://github.com/supabase/supabase/blob/master/examples/ai/semantic_text_deduplication.ipynb) notebook in Colab:

At the top of the notebook, you'll see a button `Copy to Drive`. Click this button to copy the notebook to your Google Drive.


## Connecting to your database

Inside the Notebook, find the cell which specifies the `DB_CONNECTION`. It will contain some code like this:

```python
import vecs

DB_CONNECTION = "postgresql://<user>:<password>@<host>:<port>/<db_name>"

# create vector store client
vx = vecs.create_client(DB_CONNECTION)
```

Replace the `DB_CONNECTION` with your own connection string for your database. You can find the Postgres connection string in the [Database Settings](https://supabase.com/dashboard/project/_/settings/database) of your Supabase project.


## Stepping through the notebook

Now all that's left is to step through the notebook. You can do this by clicking the "execute" button (`ctrl+enter`) at the top left of each code cell. The notebook guides you through the process of creating a collection, adding data to it, and querying it.

You can view the inserted items in the [Table Editor](https://supabase.com/dashboard/project/_/editor/), by selecting the `vecs` schema from the schema dropdown.

![Colab documents](/docs/img/ai/google-colab/colab-documents.png)


## Next steps

You can now start building your own applications with Vecs. Check our [examples](/docs/guides/ai#examples) for ideas.


# RAG with Permissions

Fine-grain access control with Retrieval Augmented Generation.

Since pgvector is built on top of Postgres, you can implement fine-grain access control on your vector database using [Row Level Security (RLS)](/docs/guides/database/postgres/row-level-security). This means you can restrict which documents are returned during a vector similarity search to users that have access to them. Supabase also supports [Foreign Data Wrappers (FDW)](/docs/guides/database/extensions/wrappers/overview) which means you can use an external database or data source to determine these permissions if your user data doesn't exist in Supabase.

Use this guide to learn how to restrict access to documents when performing retrieval augmented generation (RAG).


## Example

In a typical RAG setup, your documents are chunked into small subsections and similarity is performed over those sections:

```sql
-- Track documents/pages/files/etc
create table documents (
  id bigint primary key generated always as identity,
  name text not null,
  owner_id uuid not null references auth.users (id) default auth.uid(),
  created_at timestamp with time zone not null default now()
);

-- Store the content and embedding vector for each section in the document
-- with a reference to original document (one-to-many)
create table document_sections (
  id bigint primary key generated always as identity,
  document_id bigint not null references documents (id),
  content text not null,
  embedding vector (384)
);
```

Notice how we record the `owner_id` on each document. Let's create an RLS policy that restricts access to `document_sections` based on whether or not they own the linked document:

```sql
-- enable row level security
alter table document_sections enable row level security;

-- setup RLS for select operations
create policy "Users can query their own document sections"
on document_sections for select to authenticated using (
  document_id in (
    select id
    from documents
    where (owner_id = (select auth.uid()))
  )
);
```

Now every `select` query executed on `document_sections` will implicitly filter the returned sections based on whether or not the current user has access to them.

For example, executing:

```sql
select * from document_sections;
```

as an authenticated user will only return rows that they are the owner of (as determined by the linked document). More importantly, semantic search over these sections (or any additional filtering for that matter) will continue to respect these RLS policies:

```sql
-- Perform inner product similarity based on a match_threshold
select *
from document_sections
where document_sections.embedding <#> embedding < -match_threshold
order by document_sections.embedding <#> embedding;
```

The above example only configures `select` access to users. If you wanted, you could create more RLS policies for inserts, updates, and deletes in order to apply the same permission logic for those other operations. See [Row Level Security](/docs/guides/database/postgres/row-level-security) for a more in-depth guide on RLS policies.


## Alternative scenarios

Every app has its own unique requirements and may differ from the above example. Here are some alternative scenarios we often see and how they are implemented in Supabase.


### Documents owned by multiple people

Instead of a one-to-many relationship between `users` and `documents`, you may require a many-to-many relationship so that multiple people can access the same document. Let's reimplement this using a join table:

```sql
create table document_owners (
  id bigint primary key generated always as identity,
  owner_id uuid not null references auth.users (id) default auth.uid(),
  document_id bigint not null references documents (id)
);
```

Then your RLS policy would change to:

```sql
create policy "Users can query their own document sections"
on document_sections for select to authenticated using (
  document_id in (
    select document_id
    from document_owners
    where (owner_id = (select auth.uid()))
  )
);
```

Instead of directly querying the `documents` table, we query the join table.


### User and document data live outside of Supabase

You may have an existing system that stores users, documents, and their permissions in a separate database. Let's explore the scenario where this data exists in another Postgres database. We'll use a foreign data wrapper (FDW) to connect to the external DB from within your Supabase DB:

Let's assume your external DB contains a `users` and `documents` table like this:

```sql
create table public.users (
  id bigint primary key generated always as identity,
  email text not null,
  created_at timestamp with time zone not null default now()
);

create table public.documents (
  id bigint primary key generated always as identity,
  name text not null,
  owner_id bigint not null references public.users (id),
  created_at timestamp with time zone not null default now()
);
```

In your Supabase DB, let's create foreign tables that link to the above tables:

```sql
create schema external;
create extension postgres_fdw with schema extensions;

-- Setup the foreign server
create server foreign_server
  foreign data wrapper postgres_fdw
  options (host '<db-host>', port '<db-port>', dbname '<db-name>');

-- Map local 'authenticated' role to external 'postgres' user
create user mapping for authenticated
  server foreign_server
  options (user 'postgres', password '<user-password>');

-- Import foreign 'users' and 'documents' tables into 'external' schema
import foreign schema public limit to (users, documents)
  from server foreign_server into external;
```

We'll store `document_sections` and their embeddings in Supabase so that we can perform similarity search over them via pgvector.

```sql
create table document_sections (
  id bigint primary key generated always as identity,
  document_id bigint not null,
  content text not null,
  embedding vector (384)
);
```

We maintain a reference to the foreign document via `document_id`, but without a foreign key reference since foreign keys can only be added to local tables. Be sure to use the same ID data type that you use on your external documents table.

Since we're managing users and authentication outside of Supabase, we have two options:

1.  Make a direct Postgres connection to the Supabase DB and set the current user every request
2.  Issue a custom JWT from your system and use it to authenticate with the REST API


#### Direct Postgres connection

You can directly connect to your Supabase Postgres DB using the [connection info](/dashboard/project/_/settings/database) on your project's database settings page. To use RLS with this method, we use a custom session variable that contains the current user's ID:

```sql
-- enable row level security
alter table document_sections enable row level security;

-- setup RLS for select operations
create policy "Users can query their own document sections"
on document_sections for select to authenticated using (
  document_id in (
    select id
    from external.documents
    where owner_id = current_setting('app.current_user_id')::bigint
  )
);
```

The session variable is accessed through the `current_setting()` function. We name the variable `app.current_user_id` here, but you can modify this to any name you like. We also cast it to a `bigint` since that was the data type of the `user.id` column. Change this to whatever data type you use for your ID.

Now for every request, we set the user's ID at the beginning of the session:

```sql
set app.current_user_id = '<current-user-id>';
```

Then all subsequent queries will inherit the permission of that user:

```sql
-- Only document sections owned by the user are returned
select *
from document_sections
where document_sections.embedding <#> embedding < -match_threshold
order by document_sections.embedding <#> embedding;
```


#### Custom JWT with REST API

If you would like to use the auto-generated REST API to query your Supabase database using JWTs from an external auth provider, you can get your auth provider to issue a custom JWT for Supabase.

See the [Clerk Supabase docs](https://clerk.com/docs/integrations/databases/supabase) for an example of how this can be done. Modify the instructions to work with your own auth provider as needed.

Now we can use the same RLS policy from our first example:

```sql
-- enable row level security
alter table document_sections enable row level security;

-- setup RLS for select operations
create policy "Users can query their own document sections"
on document_sections for select to authenticated using (
  document_id in (
    select id
    from documents
    where (owner_id = (select auth.uid()))
  )
);
```

Under the hood, `auth.uid()` references `current_setting('request.jwt.claim.sub')` which corresponds to the JWT's `sub` (subject) claim. This setting is automatically set at the beginning of each request to the REST API.

All subsequent queries will inherit the permission of that user:

```sql
-- Only document sections owned by the user are returned
select *
from document_sections
where document_sections.embedding <#> embedding < -match_threshold
order by document_sections.embedding <#> embedding;
```


### Other scenarios

There are endless approaches to this problem based on the complexities of each system. Luckily Postgres comes with all the primitives needed to provide access control in the way that works best for your project.

If the examples above didn't fit your use case or you need to adjust them slightly to better fit your existing system, feel free to reach out to [support](https://supabase.com/dashboard/support/new) and we'll be happy to assist you.


# Semantic search

Learn how to search by meaning rather than exact keywords.

Semantic search interprets the meaning behind user queries rather than exact [keywords](/docs/guides/ai/keyword-search). It uses machine learning to capture the intent and context behind the query, handling language nuances like synonyms, phrasing variations, and word relationships.


## When to use semantic search

Semantic search is useful in applications where the depth of understanding and context is important for delivering relevant results. A good example is in customer support or knowledge base search engines. Users often phrase their problems or questions in various ways, and a traditional keyword-based search might not always retrieve the most helpful documents. With semantic search, the system can understand the meaning behind the queries and match them with relevant solutions or articles, even if the exact wording differs.

For instance, a user searching for "increase text size on display" might miss articles titled "How to adjust font size in settings" in a keyword-based search system. However, a semantic search engine would understand the intent behind the query and correctly match it to relevant articles, regardless of the specific terminology used.

It's also possible to combine semantic search with keyword search to get the best of both worlds. See [Hybrid search](/docs/guides/ai/hybrid-search) for more details.


## How semantic search works

Semantic search uses an intermediate representation called an “embedding vector” to link database records with search queries. A vector, in the context of semantic search, is a list of numerical values. They represent various features of the text and allow for the semantic comparison between different pieces of text.

The best way to think of embeddings is by plotting them on a graph, where each embedding is a single point whose coordinates are the numerical values within its vector. Importantly, embeddings are plotted such that similar concepts are positioned close together while dissimilar concepts are far apart. For more details, see [What are embeddings?](/docs/guides/ai/concepts#what-are-embeddings)

Embeddings are generated using a language model, and embeddings are compared to each other using a similarity metric. The language model is trained to understand the semantics of language, including syntax, context, and the relationships between words. It generates embeddings for both the content in the database and the search queries. Then the similarity metric, often a function like cosine similarity or dot product, is used to compare the query embeddings with the document embeddings (in other words, to measure how close they are to each other on the graph). The documents with embeddings most similar to the query's are deemed the most relevant and are returned as search results.


## Embedding models

There are many embedding models available today. Supabase Edge Functions has [built in support](/docs/guides/functions/examples/semantic-search) for the `gte-small` model. Others can be accessed through third-party APIs like [OpenAI](https://platform.openai.com/docs/guides/embeddings), where you send your text in the request and receive an embedding vector in the response. Others can run locally on your own compute, such as through Transformers.js for JavaScript implementations. For more information on local implementation, see [Generate embeddings](/docs/guides/ai/quickstarts/generate-text-embeddings).

It's crucial to remember that when using embedding models with semantic search, you must use the same model for all embedding comparisons. Comparing embeddings created by different models will yield meaningless results.


## Semantic search in Postgres

To implement semantic search in Postgres we use `pgvector` - an extension that allows for efficient storage and retrieval of high-dimensional vectors. These vectors are numerical representations of text (or other types of data) generated by embedding models.

1.  Enable the `pgvector` extension by running:

    ```sql
    create extension vector
    with
      schema extensions;
    ```

2.  Create a table to store the embeddings:

    ```sql
    create table documents (
      id bigint primary key generated always as identity,
      content text,
      embedding vector(512)
    );
    ```

    Or if you have an existing table, you can add a vector column like so:

    ```sql
    alter table documents
    add column embedding vector(512);
    ```

    In this example, we create a column named `embedding` which uses the newly enabled `vector` data type. The size of the vector (as indicated in parentheses) represents the number of dimensions in the embedding. Here we use 512, but adjust this to match the number of dimensions produced by your embedding model.

For more details on vector columns, including how to generate embeddings and store them, see [Vector columns](/docs/guides/ai/vector-columns).


### Similarity metric

`pgvector` support 3 operators for computing distance between embeddings:

| **Operator** | **Description**        |
| ------------ | ---------------------- |
| `<->`        | Euclidean distance     |
| `<#>`        | negative inner product |
| `<=>`        | cosine distance        |

These operators are used directly in your SQL query to retrieve records that are most similar to the user's search query. Choosing the right operator depends on your needs. Inner product (also known as dot product) tends to be the fastest if your vectors are normalized.

The easiest way to perform semantic search in Postgres is by creating a function:

```sql
-- Match documents using cosine distance (<=>)
create or replace function match_documents (
  query_embedding vector(512),
  match_threshold float,
  match_count int
)
returns setof documents
language sql
as $$
  select *
  from documents
  where documents.embedding <=> query_embedding < 1 - match_threshold
  order by documents.embedding <=> query_embedding asc
  limit least(match_count, 200);
$$;
```

Here we create a function `match_documents` that accepts three parameters:

1.  `query_embedding`: a one-time embedding generated for the user's search query. Here we set the size to 512, but adjust this to match the number of dimensions produced by your embedding model.
2.  `match_threshold`: the minimum similarity between embeddings. This is a value between 1 and -1, where 1 is most similar and -1 is most dissimilar.
3.  `match_count`: the maximum number of results to return. Note the query may return less than this number if `match_threshold` resulted in a small shortlist. Limited to 200 records to avoid unintentionally overloading your database.

In this example, we return a `setof documents` and refer to `documents` throughout the query. Adjust this to use the relevant tables in your application.

You'll notice we are using the cosine distance (`<=>`) operator in our query. Cosine distance is a safe default when you don't know whether or not your embeddings are normalized. If you know for a fact that they are normalized (for example, your embedding is returned from OpenAI), you can use negative inner product (`<#>`) for better performance:

```sql
-- Match documents using negative inner product (<#>)
create or replace function match_documents (
  query_embedding vector(512),
  match_threshold float,
  match_count int
)
returns setof documents
language sql
as $$
  select *
  from documents
  where documents.embedding <#> query_embedding < -match_threshold
  order by documents.embedding <#> query_embedding asc
  limit least(match_count, 200);
$$;
```

Note that since `<#>` is negative, we negate `match_threshold` accordingly in the `where` clause. For more information on the different operators, see the [pgvector docs](https://github.com/pgvector/pgvector?tab=readme-ov-file#vector-operators).


### Calling from your application

Finally you can execute this function from your application. If you are using a Supabase client library such as [`supabase-js`](https://github.com/supabase/supabase-js), you can invoke it using the `rpc()` method:

```tsx
const { data: documents } = await supabase.rpc('match_documents', {
  query_embedding: embedding, // pass the query embedding
  match_threshold: 0.78, // choose an appropriate threshold for your data
  match_count: 10, // choose the number of matches
})
```

You can also call this method directly from SQL:

```sql
select *
from match_documents(
  '[...]'::vector(512), -- pass the query embedding
  0.78, -- chose an appropriate threshold for your data
  10 -- choose the number of matches
);
```

In this scenario, you'll likely use a Postgres client library to establish a direct connection from your application to the database. It's best practice to parameterize your arguments before executing the query.


## Next steps

As your database scales, you will need an index on your vector columns to maintain fast query speeds. See [Vector indexes](/docs/guides/ai/vector-indexes) for an in-depth guide on the different types of indexes and how they work.


## See also

*   [Embedding concepts](/docs/guides/ai/concepts)
*   [Vector columns](/docs/guides/ai/vector-columns)
*   [Vector indexes](/docs/guides/ai/vector-indexes)
*   [Hybrid search](/docs/guides/ai/hybrid-search)
*   [Keyword search](/docs/guides/ai/keyword-search)


# Structured and Unstructured

Supabase is flexible enough to associate structured and unstructured metadata with embeddings.

Most vector stores treat metadata associated with embeddings like NoSQL, unstructured data. Supabase is flexible enough to store unstructured and structured metadata.


## Structured

```sql
create table docs (
  id uuid primary key,
  embedding vector(3),
  content text,
  url text
);

insert into docs
  (id, embedding, content, url)
values
  ('79409372-7556-4ccc-ab8f-5786a6cfa4f7', array[0.1, 0.2, 0.3], 'Hello world', '/hello-world');
```

Notice that we've associated two pieces of metadata, `content` and `url`, with the embedding. Those fields can be filtered, constrained, indexed, and generally operated on using the full power of SQL. Structured metadata fits naturally with a traditional Supabase application, and can be managed via database [migrations](/docs/guides/deployment/database-migrations).


## Unstructured

```sql
create table docs (
  id uuid primary key,
  embedding vector(3),
  meta jsonb
);

insert into docs
  (id, embedding, meta)
values
  (
    '79409372-7556-4ccc-ab8f-5786a6cfa4f7',
    array[0.1, 0.2, 0.3],
    '{"content": "Hello world", "url": "/hello-world"}'
  );
```

An unstructured approach does not specify the metadata fields that are expected. It stores all metadata in a flexible `json`/`jsonb` column. The tradeoff is that the querying/filtering capabilities of a schemaless data type are less flexible than when each field has a dedicated column. It also pushes the burden of metadata data integrity onto application code, which is more error prone than enforcing constraints in the database.

The unstructured approach is recommended:

*   for ephemeral/interactive workloads e.g. data science or scientific research
*   when metadata fields are user-defined or unknown
*   during rapid prototyping

Client libraries like python's [vecs](https://github.com/supabase/vecs) use this structure. For example, running:

```py
#!/usr/bin/env python3
import vecs

# In practice, do not hard-code your password. Use environment variables.
DB_CONNECTION = "postgresql://<user>:<password>@<host>:<port>/<db_name>"

# create vector store client
vx = vecs.create_client(DB_CONNECTION)

docs = vx.get_or_create_collection(name="docs", dimension=1536)

docs.upsert(vectors=[
  ('79409372-7556-4ccc-ab8f-5786a6cfa4f7', [100, 200, 300], { url: '/hello-world' })
])

```

automatically creates the unstructured SQL table during the call to `get_or_create_collection`.

Note that when working with client libraries that emit SQL DDL, like `create table ...`, you should add that SQL to your migrations when moving to production to maintain a single source of truth for your database's schema.


## Hybrid

The structured metadata style is recommended when the fields being tracked are known in advance. If you have a combination of known and unknown metadata fields, you can accommodate the unknown fields by adding a `json`/`jsonb` column to the table. In that situation, known fields should continue to use dedicated columns for best query performance and throughput.

```sql
create table docs (
  id uuid primary key,
  embedding vector(3),
  content text,
  url string,
  meta jsonb
);

insert into docs
  (id, embedding, content, url, meta)
values
  (
    '79409372-7556-4ccc-ab8f-5786a6cfa4f7',
    array[0.1, 0.2, 0.3],
    'Hello world',
    '/hello-world',
    '{"key": "value"}'
  );
```


## Choosing the right model

Both approaches create a table where you can store your embeddings and some metadata. You should choose the best approach for your use-case. In summary:

*   Structured metadata is best when fields are known in advance or query patterns are predictable e.g. a production Supabase application
*   Unstructured metadata is best when fields are unknown/user-defined or when working with data interactively e.g. exploratory research

Both approaches are valid, and the one you should choose depends on your use-case.


# Python client

Manage unstructured vector stores in PostgreSQL.

Supabase provides a Python client called [`vecs`](https://github.com/supabase/vecs) for managing unstructured vector stores. This client provides a set of useful tools for creating and querying collections in Postgres using the [pgvector](/docs/guides/database/extensions/pgvector) extension.


## Quick start

Let's see how Vecs works using a local database. Make sure you have the Supabase CLI [installed](/docs/guides/cli#installation) on your machine.


### Initialize your project

Start a local Postgres instance in any folder using the `init` and `start` commands. Make sure you have Docker running!

```bash
# Initialize your project
supabase init

# Start Postgres
supabase start
```


### Create a collection

Inside a Python shell, run the following commands to create a new collection called "docs", with 3 dimensions.

```py
import vecs

# create vector store client
vx = vecs.create_client("postgresql://postgres:postgres@localhost:54322/postgres")

# create a collection of vectors with 3 dimensions
docs = vx.get_or_create_collection(name="docs", dimension=3)
```


### Add embeddings

Now we can insert some embeddings into our "docs" collection using the `upsert()` command:

```py
import vecs

# create vector store client
docs = vecs.get_or_create_collection(name="docs", dimension=3)

# a collection of vectors with 3 dimensions
vectors=[
  ("vec0", [0.1, 0.2, 0.3], {"year": 1973}),
  ("vec1", [0.7, 0.8, 0.9], {"year": 2012})
]

# insert our vectors
docs.upsert(vectors=vectors)
```


### Query the collection

You can now query the collection to retrieve a relevant match:

```py
import vecs

docs = vecs.get_or_create_collection(name="docs", dimension=3)

# query the collection filtering metadata for "year" = 2012
docs.query(
    data=[0.4,0.5,0.6],      # required
    limit=1,                         # number of records to return
    filters={"year": {"$eq": 2012}}, # metadata filters
)
```


## Deep dive

For a more in-depth guide on `vecs` collections, see [API](/docs/guides/ai/python/api).


## Resources

*   Official Vecs Documentation: https://supabase.github.io/vecs/api
*   Source Code: https://github.com/supabase/vecs


# Vector columns



Supabase offers a number of different ways to store and query vectors within Postgres. The SQL included in this guide is applicable for clients in all programming languages. If you are a Python user see your [Python client options](/docs/guides/ai/python-clients) after reading the `Learn` section.

Vectors in Supabase are enabled via [pgvector](https://github.com/pgvector/pgvector/), a Postgres extension for storing and querying vectors in Postgres. It can be used to store [embeddings](/docs/guides/ai/concepts#what-are-embeddings).


## Usage


### Enable the extension


### Create a table to store vectors

After enabling the `vector` extension, you will get access to a new data type called `vector`. The size of the vector (indicated in parenthesis) represents the number of dimensions stored in that vector.

```sql
create table documents (
  id serial primary key,
  title text not null,
  body text not null,
  embedding vector(384)
);
```

In the above SQL snippet, we create a `documents` table with a column called `embedding` (note this is just a regular Postgres column - you can name it whatever you like). We give the `embedding` column a `vector` data type with 384 dimensions. Change this to the number of dimensions produced by your embedding model. For example, if you are [generating embeddings](/docs/guides/ai/quickstarts/generate-text-embeddings) using the open source [`gte-small`](https://huggingface.co/Supabase/gte-small) model, you would set this number to 384 since that model produces 384 dimensions.


### Storing a vector / embedding

In this example we'll generate a vector using Transformers.js, then store it in the database using the Supabase JavaScript client.

```js
import { pipeline } from '@xenova/transformers'
const generateEmbedding = await pipeline('feature-extraction', 'Supabase/gte-small')

const title = 'First post!'
const body = 'Hello world!'

// Generate a vector using Transformers.js
const output = await generateEmbedding(body, {
  pooling: 'mean',
  normalize: true,
})

// Extract the embedding output
const embedding = Array.from(output.data)

// Store the vector in Postgres
const { data, error } = await supabase.from('documents').insert({
  title,
  body,
  embedding,
})
```

This example uses the JavaScript Supabase client, but you can modify it to work with any [supported language library](/docs#client-libraries).


### Querying a vector / embedding

Similarity search is the most common use case for vectors. `pgvector` support 3 new operators for computing distance:

| Operator | Description            |
| -------- | ---------------------- |
| `<->`    | Euclidean distance     |
| `<#>`    | negative inner product |
| `<=>`    | cosine distance        |

Choosing the right operator depends on your needs. Dot product tends to be the fastest if your vectors are normalized. For more information on how embeddings work and how they relate to each other, see [What are Embeddings?](/docs/guides/ai/concepts#what-are-embeddings).

Supabase client libraries like `supabase-js` connect to your Postgres instance via [PostgREST](/docs/guides/getting-started/architecture#postgrest-api). PostgREST does not currently support `pgvector` similarity operators, so we'll need to wrap our query in a Postgres function and call it via the `rpc()` method:

```sql
create or replace function match_documents (
  query_embedding vector(384),
  match_threshold float,
  match_count int
)
returns table (
  id bigint,
  title text,
  body text,
  similarity float
)
language sql stable
as $$
  select
    documents.id,
    documents.title,
    documents.body,
    1 - (documents.embedding <=> query_embedding) as similarity
  from documents
  where 1 - (documents.embedding <=> query_embedding) > match_threshold
  order by (documents.embedding <=> query_embedding) asc
  limit match_count;
$$;
```

This function takes a `query_embedding` argument and compares it to all other embeddings in the `documents` table. Each comparison returns a similarity score. If the similarity is greater than the `match_threshold` argument, it is returned. The number of rows returned is limited by the `match_count` argument.

Feel free to modify this method to fit the needs of your application. The `match_threshold` ensures that only documents that have a minimum similarity to the `query_embedding` are returned. Without this, you may end up returning documents that subjectively don't match. This value will vary for each application - you will need to perform your own testing to determine the threshold that makes sense for your app.

If you index your vector column, ensure that the `order by` sorts by the distance function directly (rather than sorting by the calculated `similarity` column, which may lead to the index being ignored and poor performance).

To execute the function from your client library, call `rpc()` with the name of your Postgres function:

```ts
const { data: documents } = await supabaseClient.rpc('match_documents', {
  query_embedding: embedding, // Pass the embedding you want to compare
  match_threshold: 0.78, // Choose an appropriate threshold for your data
  match_count: 10, // Choose the number of matches
})
```

In this example `embedding` would be another embedding you wish to compare against your table of pre-generated embedding documents. For example if you were building a search engine, every time the user submits their query you would first generate an embedding on the search query itself, then pass it into the above `rpc()` function to match.

Vectors and embeddings can be used for much more than search. Learn more about embeddings at [What are Embeddings?](/docs/guides/ai/concepts#what-are-embeddings).


### Indexes

Once your vector table starts to grow, you will likely want to add an index to speed up queries. See [Vector indexes](/docs/guides/ai/vector-indexes) to learn how vector indexes work and how to create them.


# Vector indexes



Once your vector table starts to grow, you will likely want to add an index to speed up queries. Without indexes, you'll be performing a sequential scan which can be a resource-intensive operation when you have many records.


## Choosing an index

Today `pgvector` supports two types of indexes:

*   [HNSW](/docs/guides/ai/vector-indexes/hnsw-indexes)
*   [IVFFlat](/docs/guides/ai/vector-indexes/ivf-indexes)

In general we recommend using [HNSW](/docs/guides/ai/vector-indexes/hnsw-indexes) because of its [performance](https://supabase.com/blog/increase-performance-pgvector-hnsw#hnsw-performance-1536-dimensions) and [robustness against changing data](/docs/guides/ai/vector-indexes/hnsw-indexes#when-should-you-create-hnsw-indexes).


## Distance operators

Indexes can be used to improve performance of nearest neighbor search using various distance measures. `pgvector` includes 3 distance operators:

| Operator | Description            | [**Operator class**](https://www.postgresql.org/docs/current/sql-createopclass.html) |
| -------- | ---------------------- | ------------------------------------------------------------------------------------ |
| `<->`    | Euclidean distance     | `vector_l2_ops`                                                                      |
| `<#>`    | negative inner product | `vector_ip_ops`                                                                      |
| `<=>`    | cosine distance        | `vector_cosine_ops`                                                                  |

Currently vectors with up to 2,000 dimensions can be indexed.


## Resources

Read more about indexing on `pgvector`'s [GitHub page](https://github.com/pgvector/pgvector#indexing).


# HNSW indexes



HNSW is an algorithm for approximate nearest neighbor search. It is a frequently used index type that can improve performance when querying highly-dimensional vectors, like those representing embeddings.


## Usage

The way you create an HNSW index depends on the distance operator you are using. `pgvector` includes 3 distance operators:

| Operator | Description            | [**Operator class**](https://www.postgresql.org/docs/current/sql-createopclass.html) |
| -------- | ---------------------- | ------------------------------------------------------------------------------------ |
| `<->`    | Euclidean distance     | `vector_l2_ops`                                                                      |
| `<#>`    | negative inner product | `vector_ip_ops`                                                                      |
| `<=>`    | cosine distance        | `vector_cosine_ops`                                                                  |

Use the following SQL commands to create an HNSW index for the operator(s) used in your queries.


### Euclidean L2 distance (`vector_l2_ops`)

```sql
create index on items using hnsw (column_name vector_l2_ops);
```


### Inner product (`vector_ip_ops`)

```sql
create index on items using hnsw (column_name vector_ip_ops);
```


### Cosine distance (`vector_cosine_ops`)

```sql
create index on items using hnsw (column_name vector_cosine_ops);
```

Currently vectors with up to 2,000 dimensions can be indexed.


## How does HNSW work?

HNSW uses proximity graphs (graphs connecting nodes based on distance between them) to approximate nearest-neighbor search. To understand HNSW, we can break it down into 2 parts:

*   **Hierarchical (H):** The algorithm operates over multiple layers
*   **Navigable Small World (NSW):** Each vector is a node within a graph and is connected to several other nodes


### Hierarchical

The hierarchical aspect of HNSW builds off of the idea of skip lists.

Skip lists are multi-layer linked lists. The bottom layer is a regular linked list connecting an ordered sequence of elements. Each new layer above removes some elements from the underlying layer (based on a fixed probability), producing a sparser subsequence that “skips” over elements.

When searching for an element, the algorithm begins at the top layer and traverses its linked list horizontally. If the target element is found, the algorithm stops and returns it. Otherwise if the next element in the list is greater than the target (or `NULL`), the algorithm drops down to the next layer below. Since each layer below is less sparse than the layer above (with the bottom layer connecting all elements), the target will eventually be found. Skip lists offer O(log n) average complexity for both search and insertion/deletion.


### Navigable Small World

A navigable small world (NSW) is a special type of proximity graph that also includes long-range connections between nodes. These long-range connections support the “small world” property of the graph, meaning almost every node can be reached from any other node within a few hops. Without these additional long-range connections, many hops would be required to reach a far-away node.

The “navigable” part of NSW specifically refers to the ability to logarithmically scale the greedy search algorithm on the graph, an algorithm that attempts to make only the locally optimal choice at each hop. Without this property, the graph may still be considered a small world with short paths between far-away nodes, but the greedy algorithm tends to miss them. Greedy search is ideal for NSW because it is quick to navigate and has low computational costs.


### **Hierarchical +** Navigable Small World

HNSW combines these two concepts. From the hierarchical perspective, the bottom layer consists of a NSW made up of short links between nodes. Each layer above “skips” elements and creates longer links between nodes further away from each other.

Just like skip lists, search starts at the top layer and works its way down until it finds the target element. However, instead of comparing a scalar value at each layer to determine whether or not to descend to the layer below, a multi-dimensional distance measure (such as Euclidean distance) is used.


## When should you create HNSW indexes?

HNSW should be your default choice when creating a vector index. Add the index when you don't need 100% accuracy and are willing to trade a small amount of accuracy for a lot of throughput.

Unlike IVFFlat indexes, you are safe to build an HNSW index immediately after the table is created. HNSW indexes are based on graphs which inherently are not affected by the same limitations as IVFFlat. As new data is added to the table, the index will be filled automatically and the index structure will remain optimal.


## Resources

Read more about indexing on `pgvector`'s [GitHub page](https://github.com/pgvector/pgvector#indexing).


# IVFFlat indexes



IVFFlat is a type of vector index for approximate nearest neighbor search. It is a frequently used index type that can improve performance when querying highly-dimensional vectors, like those representing embeddings.


## Choosing an index

Today `pgvector` supports two types of indexes:

*   [HNSW](/docs/guides/ai/vector-indexes/hnsw-indexes)
*   [IVFFlat](/docs/guides/ai/vector-indexes/ivf-indexes)

In general we recommend using [HNSW](/docs/guides/ai/vector-indexes/hnsw-indexes) because of its [performance](https://supabase.com/blog/increase-performance-pgvector-hnsw#hnsw-performance-1536-dimensions) and [robustness against changing data](/docs/guides/ai/vector-indexes/hnsw-indexes#when-should-you-create-hnsw-indexes). If you have a special use case that requires IVFFlat instead, keep reading.


## Usage

The way you create an IVFFlat index depends on the distance operator you are using. `pgvector` includes 3 distance operators:

| Operator | Description            | [**Operator class**](https://www.postgresql.org/docs/current/sql-createopclass.html) |
| -------- | ---------------------- | ------------------------------------------------------------------------------------ |
| `<->`    | Euclidean distance     | `vector_l2_ops`                                                                      |
| `<#>`    | negative inner product | `vector_ip_ops`                                                                      |
| `<=>`    | cosine distance        | `vector_cosine_ops`                                                                  |

Use the following SQL commands to create an IVFFlat index for the operator(s) used in your queries.


### Euclidean L2 distance (`vector_l2_ops`)

```sql
create index on items using ivfflat (column_name vector_l2_ops) with (lists = 100);
```


### Inner product (`vector_ip_ops`)

```sql
create index on items using ivfflat (column_name vector_ip_ops) with (lists = 100);
```


### Cosine distance (`vector_cosine_ops`)

```sql
create index on items using ivfflat (column_name vector_cosine_ops) with (lists = 100);
```

Currently vectors with up to 2,000 dimensions can be indexed.


## How does IVFFlat work?

IVF stands for 'inverted file indexes'. It works by clustering your vectors in order to reduce the similarity search scope. Rather than comparing a vector to every other vector, the vector is only compared against vectors within the same cell cluster (or nearby clusters, depending on your configuration).


### Inverted lists (cell clusters)

When you create the index, you choose the number of inverted lists (cell clusters). Increase this number to speed up queries, but at the expense of recall.

For example, to create an index with 100 lists on a column that uses the cosine operator:

```sql
create index on items using ivfflat (column_name vector_cosine_ops) with (lists = 100);
```

For more info on the different operators, see [Distance operations](#distance-operators).

For every query, you can set the number of probes (1 by default). The number of probes corresponds to the number of nearby cells to probe for a match. Increase this for better recall at the expense of speed.

To set the number of probes for the duration of the session run:

```sql
set ivfflat.probes = 10;
```

To set the number of probes only for the current transaction run:

```sql
begin;
set local ivfflat.probes = 10;
select ...
commit;
```

If the number of probes is the same as the number of lists, exact nearest neighbor search will be performed and the planner won't use the index.


### Approximate nearest neighbor

One important note with IVF indexes is that nearest neighbor search is approximate, since exact search on high dimensional data can't be indexed efficiently. This means that similarity results will change (slightly) after you add an index (trading recall for speed).


## When should you create IVFFlat indexes?

`pgvector` recommends building IVFFlat indexes only after the table has sufficient data, so that the internal IVFFlat cell clusters are based on your data's distribution. Anytime the distribution changes significantly, consider rebuilding indexes.


## Resources

Read more about indexing on `pgvector`'s [GitHub page](https://github.com/pgvector/pgvector#indexing).


# REST API



Supabase auto-generates an API directly from your database schema allowing you to connect to your database through a restful interface, directly from the browser.

The API is auto-generated from your database and is designed to get you building as fast as possible, without writing a single line of code.

You can use them directly from the browser (two-tier architecture), or as a complement to your own API server (three-tier architecture).


## Features \[#rest-api-overview]

Supabase provides a RESTful API using [PostgREST](https://postgrest.org/). This is a very thin API layer on top of Postgres.
It exposes everything you need from a CRUD API at the URL `https://<project_ref>.supabase.co/rest/v1/`.

The REST interface is automatically reflected from your database's schema and is:

*   **Instant and auto-generated.** As you update your database the changes are immediately accessible through your API.
*   **Self documenting.** Supabase generates documentation in the Dashboard which updates as you make database changes.
*   **Secure.** The API is configured to work with PostgreSQL's Row Level Security, provisioned behind an API gateway with key-auth enabled.
*   **Fast.** Our benchmarks for basic reads are more than 300% faster than Firebase. The API is a very thin layer on top of Postgres, which does most of the heavy lifting.
*   **Scalable.** The API can serve thousands of simultaneous requests, and works well for Serverless workloads.

The reflected API is designed to retain as much of Postgres' capability as possible including:

*   Basic CRUD operations (Create/Read/Update/Delete)
*   Arbitrarily deep relationships among tables/views, functions that return table types can also nest related tables/views.
*   Works with Postgres Views, Materialized Views and Foreign Tables
*   Works with Postgres Functions
*   User defined computed columns and computed relationships
*   The Postgres security model - including Row Level Security, Roles, and Grants.

The REST API resolves all requests to a single SQL statement leading to fast response times and high throughput.

Reference:

*   [Docs](https://postgrest.org/)
*   [Source Code](https://github.com/PostgREST/postgrest)


## API URL and keys

You can find the API URL and Keys in the [Dashboard](https://supabase.com/dashboard/project/_/settings/api).


# Understanding API Keys



Supabase provides two default keys when you create a project: an `anon` key, and a `service_role` key. You can find both keys in the [API Settings](https://supabase.com/dashboard/project/_/settings/api).

The data APIs are designed to work with Postgres Row Level Security (RLS). These keys both map to Postgres roles. You can find an `anon` user and a `service_role` user in the [Roles](http://supabase.com/dashboard/project/_/database/roles) section of the dashboard.

The keys are both long-lived JWTs. If you decode these keys, you will see that they contain the "role", an "issued date", and an "expiry date" ~10 years in the future.

```json
{
  "role": "anon",
  "iat": 1625137684,
  "exp": 1940713684
}
```


## The `anon` key

The `anon` key has very few privileges. You can use it in your [RLS policies](/docs/guides/database/postgres/row-level-security) to allow unauthenticated access. For example, this policy will allow unauthenticated access to the `profiles` table:

```sql
create policy "Allow public access" on profiles to anon for
select
  using (true);
```

And similarly for disallowing access:

```sql
create policy "Disallow public access" on profiles to anon for
select
  using (false);
```

If you are using [Supabase Auth](/docs/guides/auth/overview), then the `anon` role will automatically update to `authenticated` once a user is logged in:

```sql
create policy "Allow access to authenticated users" on profiles to authenticated for
select
  using (true);
```


## The `service_role` key

The "service\_role" is a predefined Postgres role with elevated privileges, designed to perform various administrative and service-related tasks. It can bypass Row Level Security, so it should only be used on a private server.

A common use case for the `service_role` key is running data analytics jobs on the backend. To support joins on user id, it is often useful to grant the service role read access to `auth.users` table.

```sql
grant
select
  on table auth.users to service_role;
```

We have [partnered with GitHub](https://github.blog/changelog/2022-03-28-supabase-is-now-a-github-secret-scanning-partner/) to scan for Supabase `service_role` keys pushed to public repositories.
If they detect any keys with service\_role privileges being pushed to GitHub, they will forward the API key to us, so that we can automatically revoke the detected secrets and notify you, protecting your data against malicious actors.


# How to do automatic retries with `supabase-js`

Learn how to add automatic retries to your Supabase API requests using `fetch-retry`.

The `fetch-retry` package allows you to add retry logic to `fetch` requests, making it a useful tool for enhancing the resilience of API calls in your Supabase applications. Here's a step-by-step guide on how to integrate `fetch-retry` with the `supabase-js` library.


## 1. Install dependencies

To get started, ensure you have both `supabase-js` and `fetch-retry` installed in your project:

```bash
npm install @supabase/supabase-js fetch-retry
```


## 2. Wrap the fetch function

The `fetch-retry` package works by wrapping the native `fetch` function. You can create a custom fetch instance with retry logic and pass it to the `supabase-js` client.

```javascript
import { createClient } from '@supabase/supabase-js'
import fetchRetry from 'fetch-retry'

// Wrap the global fetch with fetch-retry
const fetchWithRetry = fetchRetry(fetch)

// Create a Supabase client instance with the custom fetch
const supabase = createClient('https://your-supabase-url.supabase.co', 'your-anon-key', {
  global: {
    fetch: fetchWithRetry,
  },
})
```


## 3. Configure retry options

You can configure `fetch-retry` options to control retry behavior, such as the number of retries, retry delay, and which errors should trigger a retry.

Here is an example with custom retry options:

```javascript
const fetchWithRetry = fetchRetry(fetch, {
  retries: 3, // Number of retry attempts
  retryDelay: (attempt) => Math.min(1000 * 2 ** attempt, 30000), // Exponential backoff
  retryOn: [520], // Retry only on Cloudflare errors
})
```

In this example, the `retryDelay` function implements an exponential backoff strategy, and retries are triggered only for specific HTTP status codes.


## 4. Using the Supabase client

With `fetch-retry` integrated, you can use the Supabase client as usual. The retry logic will automatically apply to all network requests made by `supabase-js`.

```javascript
async function fetchData() {
  const { data, error } = await supabase.from('your_table').select('*')

  if (error) {
    console.error('Error fetching data:', error)
  } else {
    console.log('Fetched data:', data)
  }
}

fetchData()
```


## 5. Fine-Tuning retries for specific requests

If you need different retry logic for certain requests, you can use the `retryOn` with a custom function to inspect the URL or response and decide whether to retry the request.

```javascript
const fetchWithRetry = fetchRetry(fetch, {
  retryDelay: (attempt) => Math.min(1000 * 2 ** attempt, 30000),
  retryOn: (attempt, error, response) => {
    const shouldRetry
      = (attempt: number, error: Error | null, response: Response | null) =>
        attempt < 3
          && response
          && response.status == 520 // Cloudflare errors
          && response.url.includes('rpc/your_stored_procedure')

    if (shouldRetry(attempt, error, response)) {
      console.log(`Retrying request... Attempt #${attempt}`, response)
      return true
    }

    return false
  }
})

async function yourStoredProcedure() {
  const { data, error } = await supabase
    .rpc('your_stored_procedure', { param1: 'value1' });

  if (error) {
    console.log('Error executing RPC:', error);
  } else {
    console.log('Response:', data);
  }
}

yourStoredProcedure();
```

By using `retryOn` with a custom function, you can define specific conditions for retrying requests. In this example, the retry logic is applied only to requests targeting a specific stored procedure.


## Conclusion

Integrating `fetch-retry` with `supabase-js` is a straightforward way to add robustness to your Supabase API requests. By handling transient errors and implementing retry strategies, you can improve the reliability of your application while maintaining a seamless user experience.


# Creating API Routes



API routes are automatically created when you create Postgres Tables, Views, or Functions.


## Create a table

Let's create our first API route by creating a table called `todos` to store tasks.
This creates a corresponding route `todos` which can accept `GET`, `POST`, `PATCH`, & `DELETE` requests.


## API URL and keys

Every Supabase project has a unique API URL. Your API is secured behind an API gateway which requires an API Key for every request.

1.  Go to the [Settings](https://supabase.com/dashboard/project/_/settings/general) page in the Dashboard.
2.  Click **API** in the sidebar.
3.  Find your API `URL`, `anon`, and `service_role` keys on this page.

The REST API is accessible through the URL `https://<project_ref>.supabase.co/rest/v1`

Both of these routes require the `anon` key to be passed through an `apikey` header.


## Using the API

You can interact with your API directly via HTTP requests, or you can use the client libraries which we provide.

Let's see how to make a request to the `todos` table which we created in the first step,
using the API URL (`SUPABASE_URL`) and Key (`SUPABASE_ANON_KEY`) we provided:

JS Reference: [`select()`](/docs/reference/javascript/select),
[`insert()`](/docs/reference/javascript/insert),
[`update()`](/docs/reference/javascript/update),
[`upsert()`](/docs/reference/javascript/upsert),
[`delete()`](/docs/reference/javascript/delete),
[`rpc()`](/docs/reference/javascript/rpc) (call Postgres functions).


# Build an API route in less than 2 minutes.

Create your first API route by creating a table called `todos` to store tasks.

Let's create our first REST route which we can query using `cURL` or the browser.

We'll create a database table called `todos` for storing tasks. This creates a corresponding API route `/rest/v1/todos` which can accept `GET`, `POST`, `PATCH`, & `DELETE` requests.


## Bonus

There are several options for accessing your data:


### Browser

You can query the route in your browser, by appending the `anon` key as a query parameter:

`https://<PROJECT_REF>.supabase.co/rest/v1/todos?apikey=<ANON_KEY>`


### Client libraries

We provide a number of [Client Libraries](https://github.com/supabase/supabase#client-libraries).


# Auto-generated documentation



Supabase generates documentation in the [Dashboard](https://supabase.com/dashboard) which updates as you make database changes.

1.  Go to the [API](https://supabase.com/dashboard/project/_/api) page in the Dashboard.
2.  Select any table under **Tables and Views** in the sidebar.
3.  Switch between the JavaScript and the cURL docs using the tabs.


# Client Libraries



Supabase provides client libraries for the REST and Realtime APIs. Some libraries are officially supported, and some are contributed by the community.


## Official libraries

| `Language`            | `Source Code`                                                                                        | `Documentation`                                                     |
| --------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| Javascript/Typescript | [supabase-js](https://github.com/supabase/supabase-js)                                               | [Docs](https://supabase.com/docs/reference/javascript/introduction) |
| Dart/Flutter          | [supabase-flutter](https://github.com/supabase/supabase-flutter/tree/main/packages/supabase_flutter) | [Docs](https://supabase.com/docs/reference/dart/introduction)       |
| Swift                 | [supabase-swift](https://github.com/supabase/supabase-swift)                                         | [Docs](https://supabase.com/docs/reference/swift/introduction)      |
| Python                | [supabase-py](https://github.com/supabase/supabase-py)                                               | [Docs](https://supabase.com/docs/reference/python/initializing)     |


## Community libraries

| `Language`              | `Source Code`                                                                    | `Documentation`                                                 |
| ----------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| C#                      | [supabase-csharp](https://github.com/supabase-community/supabase-csharp)         | [Docs](https://supabase.com/docs/reference/csharp/introduction) |
| Go                      | [supabase-go](https://github.com/supabase-community/supabase-go)                 |                                                                 |
| Kotlin                  | [supabase-kt](https://github.com/supabase-community/supabase-kt)                 | [Docs](https://supabase.com/docs/reference/kotlin/introduction) |
| Ruby                    | [supabase-rb](https://github.com/supabase-community/supabase-rb)                 |                                                                 |
| Godot Engine (GDScript) | [supabase-gdscript](https://github.com/supabase-community/godot-engine.supabase) |                                                                 |


# Generating TypeScript Types

How to generate types for your API and Supabase libraries.

Supabase APIs are generated from your database, which means that we can use database introspection to generate type-safe API definitions.


## Generating types from project dashboard

Supabase allows you to generate and download TypeScript types directly from the [project dashboard](https://supabase.com/dashboard/project/_/api?page=tables-intro).


## Generating types using Supabase CLI

The Supabase CLI is a single binary Go application that provides everything you need to setup a local development environment.

You can [install the CLI](https://www.npmjs.com/package/supabase) via npm or other supported package managers. The minimum required version of the CLI is [v1.8.1](https://github.com/supabase/cli/releases).

```bash
npm i supabase@">=1.8.1" --save-dev
```

Login with your Personal Access Token:

```bash
npx supabase login
```

Before generating types, ensure you initialize your Supabase project:

```bash
npx supabase init
```

Generate types for your project to produce the `database.types.ts` file:

```bash
npx supabase gen types typescript --project-id "$PROJECT_REF" --schema public > database.types.ts
```

or in case of local development:

```bash
npx supabase gen types typescript --local > database.types.ts
```

These types are generated from your database schema. Given a table `public.movies`, the generated types will look like:

```sql
create table public.movies (
  id bigint generated always as identity primary key,
  name text not null,
  data jsonb null
);
```

```ts ./database.types.ts
export type Json = string | number | boolean | null | { [key: string]: Json | undefined } | Json[]

export interface Database {
  public: {
    Tables: {
      movies: {
        Row: {
          // the data expected from .select()
          id: number
          name: string
          data: Json | null
        }
        Insert: {
          // the data to be passed to .insert()
          id?: never // generated columns must not be supplied
          name: string // `not null` columns with no default must be supplied
          data?: Json | null // nullable columns can be omitted
        }
        Update: {
          // the data to be passed to .update()
          id?: never
          name?: string // `not null` columns are optional on .update()
          data?: Json | null
        }
      }
    }
  }
}
```


## Using TypeScript type definitions

You can supply the type definitions to `supabase-js` like so:

```ts ./index.tsx
import { createClient } from '@supabase/supabase-js'
import { Database } from './database.types'

const supabase = createClient<Database>(process.env.SUPABASE_URL, process.env.SUPABASE_ANON_KEY)
```


## Helper types for tables and joins

You can use the following helper types to make the generated TypeScript types easier to use.

Sometimes the generated types are not what you expect. For example, a view's column may show up as nullable when you expect it to be `not null`. Using [type-fest](https://github.com/sindresorhus/type-fest), you can override the types like so:

```ts ./database-generated.types.ts
export type Json = // ...

export interface Database {
  // ...
}
```

```ts ./database.types.ts
import { MergeDeep } from 'type-fest'
import { Database as DatabaseGenerated } from './database-generated.types'
export { Json } from './database-generated.types'

// Override the type for a specific column in a view:
export type Database = MergeDeep<
  DatabaseGenerated,
  {
    public: {
      Views: {
        movies_view: {
          Row: {
            // id is a primary key in public.movies, so it must be `not null`
            id: number
          }
        }
      }
    }
  }
>
```

You can also override the type of an individual successful response if needed:

```ts
// Partial type override allows you to only override some of the properties in your results
const { data } = await supabase.from('countries').select().overrideTypes<Array<{ id: string }>>()
// For a full replacement of the original return type use the `{ merge: false }` property as second argument
const { data } = await supabase
  .from('countries')
  .select()
  .overrideTypes<Array<{ id: string }>, { merge: false }>()
// Use it with `maybeSingle` or `single`
const { data } = await supabase.from('countries').select().single().overrideTypes<{ id: string }>()
```


### Type shorthands

The generated types provide shorthands for accessing tables and enums.

```ts ./index.ts
import { Database, Tables, Enums } from "./database.types.ts";

// Before 😕
let movie: Database['public']['Tables']['movies']['Row'] = // ...

// After 😍
let movie: Tables<'movies'>
```


### Response types for complex queries

`supabase-js` always returns a `data` object (for success), and an `error` object (for unsuccessful requests).

These helper types provide the result types from any query, including nested types for database joins.

Given the following schema with a relation between cities and countries:

```sql
create table countries (
  "id" serial primary key,
  "name" text
);

create table cities (
  "id" serial primary key,
  "name" text,
  "country_id" int references "countries"
);
```

We can get the nested `CountriesWithCities` type like this:

```ts
import { QueryResult, QueryData, QueryError } from '@supabase/supabase-js'

const countriesWithCitiesQuery = supabase.from('countries').select(`
  id,
  name,
  cities (
    id,
    name
  )
`)
type CountriesWithCities = QueryData<typeof countriesWithCitiesQuery>

const { data, error } = await countriesWithCitiesQuery
if (error) throw error
const countriesWithCities: CountriesWithCities = data
```


## Update types automatically with GitHub Actions

One way to keep your type definitions in sync with your database is to set up a GitHub action that runs on a schedule.

Add the following script to your `package.json` to run it using `npm run update-types`

```json
"update-types": "npx supabase gen types --lang=typescript --project-id \"$PROJECT_REF\" > database.types.ts"
```

Create a file `.github/workflows/update-types.yml` with the following snippet to define the action along with the environment variables. This script will commit new type changes to your repo every night.

```yaml
name: Update database types

on:
  schedule:
    # sets the action to run daily. You can modify this to run the action more or less frequently
    - cron: '0 0 * * *'

jobs:
  update:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    env:
      SUPABASE_ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
      PROJECT_REF: <your-project-id>
    steps:
      - uses: actions/checkout@v4
        with:
          persist-credentials: false
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm run update-types
      - name: check for file changes
        id: git_status
        run: |
          echo "status=$(git status -s)" >> $GITHUB_OUTPUT
      - name: Commit files
        if: ${{contains(steps.git_status.outputs.status, ' ')}}
        run: |
          git add database.types.ts
          git config --local user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git config --local user.name "github-actions[bot]"
          git commit -m "Update database types" -a
      - name: Push changes
        if: ${{contains(steps.git_status.outputs.status, ' ')}}
        uses: ad-m/github-push-action@master
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          branch: ${{ github.ref }}
```

Alternatively, you can use a community-supported GitHub action: [`generate-supabase-db-types-github-action`](https://github.com/lyqht/generate-supabase-db-types-github-action).


## Resources

*   [Generating Supabase types with GitHub Actions](https://blog.esteetey.dev/how-to-create-and-test-a-github-action-that-generates-types-from-supabase-database)


# Securing your API



The data APIs are designed to work with Postgres Row Level Security (RLS). If you use [Supabase Auth](/docs/guides/auth), you can restrict data based on the logged-in user.

To control access to your data, you can use [Policies](/docs/guides/auth#policies).


## Enabling row level security

Any table you create in the `public` schema will be accessible via the Supabase Data API.

To restrict access, enable Row Level Security (RLS) on all tables, views, and functions in the `public` schema. You can then write RLS policies to grant users access to specific database rows or functions based on their authentication token.

Any table created through the Supabase Dashboard will have RLS enabled by default. If you created the tables via the SQL editor or via another way, enable RLS like so:

With RLS enabled, you can create Policies that allow or disallow users to access and update data. We provide a detailed guide for creating Row Level Security Policies in our [Authorization documentation](/docs/guides/database/postgres/row-level-security).


## Disable the API or restrict to custom schema

If you don't use the Data API, or if you don't want to expose the `public` schema, you can either disable it entirely or change the automatically exposed schema to one of your choice. See **[Hardening the Data API](/docs/guides/database/hardening-data-api)** for instructions.


## Enforce additional rules on each request

Using Row Level Security policies may not always be adequate or sufficient to protect APIs.

Here are some common situations where additional protections are necessary:

*   Enforcing per-IP or per-user rate limits.
*   Checking custom or additional API keys before allowing further access.
*   Rejecting requests after exceeding a quota or requiring payment.
*   Disallowing direct access to certain tables, views or functions in the `public` schema.

You can build these cases in your application by creating a Postgres function that will read information from the request and perform additional checks, such as counting the number of requests received or checking that an API key is already registered in your database before serving the response.

Define a function like so:

```sql
create function public.check_request()
  returns void
  language plpgsql
  security definer
  as $$
begin
  -- your logic here
end;
$$;
```

And register it to run on every Data API request using:

```sql
alter role authenticator
  set pgrst.db_pre_request = 'public.check_request';
```

This configures the `public.check_request` function to run on every Data API request. To have the changes take effect, you should run:

```sql
notify pgrst, 'reload config';
```

Inside the function you can perform any additional checks on the request headers or JWT and raise an exception to prevent the request from completing. For example, this exception raises a HTTP 402 Payment Required response with a `hint` and additional `X-Powered-By` header:

```sql
raise sqlstate 'PGRST' using
  message = json_build_object(
    'code',    '123',
    'message', 'Payment Required',
    'details', 'Quota exceeded',
    'hint',    'Upgrade your plan')::text,
  detail = json_build_object(
    'status',  402,
    'headers', json_build_object(
      'X-Powered-By', 'Nerd Rage'))::text;
```

When raised within the `public.check_request` function, the resulting HTTP response will look like:

```http
HTTP/1.1 402 Payment Required
Content-Type: application/json; charset=utf-8
X-Powered-By: Nerd Rage

{
  "message": "Payment Required",
  "details": "Quota exceeded",
  "hint": "Upgrade your plan",
  "code": "123"
}
```

Use the [JSON operator functions](https://www.postgresql.org/docs/current/functions-json.html) to build rich and dynamic responses from exceptions.

If you use a custom HTTP status code like 419, you can supply the `status_text` key in the `detail` clause of the exception to describe the HTTP status.

If you're using PostgREST version 11 or lower ([find out your PostgREST version](/dashboard/project/_/settings/infrastructure)) a different and less powerful [syntax](https://postgrest.org/en/stable/references/errors.html#raise-errors-with-http-status-codes) needs to be used.


### Accessing request information

Like with RLS policies, you can access information about the request by using the `current_setting()` Postgres function. Here are some examples on how this works:

```sql
-- To get all the headers sent in the request
SELECT current_setting('request.headers', true)::json;

-- To get a single header, you can use JSON arrow operators
SELECT current_setting('request.headers', true)::json->>'user-agent';

-- Access Cookies
SELECT current_setting('request.cookies', true)::json;
```

| `current_setting()` | Example                                         | Description                          |
| ------------------- | ----------------------------------------------- | ------------------------------------ |
| `request.method`    | `GET`, `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE` | Request's method                     |
| `request.path`      | `table`                                         | Table's path                         |
| `request.path`      | `view`                                          | View's path                          |
| `request.path`      | `rpc/function`                                  | Functions's path                     |
| `request.headers`   | `{ "User-Agent": "...", ... }`                  | JSON object of the request's headers |
| `request.cookies`   | `{ "cookieA": "...", "cookieB": "..." }`        | JSON object of the request's cookies |
| `request.jwt`       | `{ "sub": "a7194ea3-...", ... }`                | JSON object of the JWT payload       |

To access the IP address of the client look up the [X-Forwarded-For header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For) in the `request.headers` setting. For example:

```sql
SELECT split_part(
  current_setting('request.headers', true)::json->>'x-forwarded-for',
  ',', 1); -- takes the client IP before the first comma (,)
```

Read more about [PostgREST's pre-request function](https://postgrest.org/en/stable/references/transactions.html#pre-request).


### Examples


# Converting SQL to JavaScript API



Many common SQL queries can be written using the JavaScript API, provided by the SDK to wrap Data API calls. Below are a few examples of conversions between SQL and JavaScript patterns.


## Select statement with basic clauses

Select a set of columns from a single table with where, order by, and limit clauses.

```sql
select first_name, last_name, team_id, age
from players
where age between 20 and 24 and team_id != 'STL'
order by last_name, first_name desc
limit 20;
```

```js
const { data, error } = await supabase
  .from('players')
  .select('first_name,last_name,team_id,age')
  .gte('age', 20)
  .lte('age', 24)
  .not('team_id', 'eq', 'STL')
  .order('last_name', { ascending: true }) // or just .order('last_name')
  .order('first_name', { ascending: false })
  .limit(20)
```


## Select statement with complex Boolean logic clause

Select all columns from a single table with a complex where clause: OR AND OR

```sql
select *
from players
where ((team_id = 'CHN' or team_id is null) and (age > 35 or age is null));
```

```js
const { data, error } = await supabase
  .from('players')
  .select() // or .select('*')
  .or('team_id.eq.CHN,team_id.is.null')
  .or('age.gt.35,age.is.null') // additional filters imply "AND"
```

Select all columns from a single table with a complex where clause: AND OR AND

```sql
select *
from players
where ((team_id = 'CHN' and age > 35) or (team_id != 'CHN' and age is not null));
```

```js
const { data, error } = await supabase
  .from('players')
  .select() // or .select('*')
  .or('and(team_id.eq.CHN,age.gt.35),and(team_id.neq.CHN,.not.age.is.null)')
```


## Resources

*   [Supabase - Get started for free](https://supabase.com)
*   [PostgREST Operators](https://postgrest.org/en/stable/api.html#operators)
*   [Supabase API: JavaScript select](/docs/reference/javascript/select)
*   [Supabase API: JavaScript modifiers](/docs/reference/javascript/using-modifiers)
*   [Supabase API: JavaScript filters](/docs/reference/javascript/using-filters)


# SQL to REST API Translator

Translate SQL queries to HTTP requests and Supabase client code

Sometimes it's challenging to translate SQL queries to the equivalent [PostgREST](https://postgrest.org/) request or Supabase client code. Use this tool to help with this translation.


# Using Custom Schemas



By default, your database has a `public` schema which is automatically exposed on data APIs.


## Creating custom schemas

You can create your own custom schema/s by running the following SQL, substituting `myschema` with the name you want to use for your schema:

```sql
CREATE SCHEMA myschema;
```


## Exposing custom schemas

You can expose custom database schemas - to do so you need to follow these steps:

1.  Go to [API settings](https://supabase.com/dashboard/project/_/settings/api) and add your custom schema to "Exposed schemas".
2.  Run the following SQL, substituting `myschema` with your schema name:

```sql
GRANT USAGE ON SCHEMA myschema TO anon, authenticated, service_role;
GRANT ALL ON ALL TABLES IN SCHEMA myschema TO anon, authenticated, service_role;
GRANT ALL ON ALL ROUTINES IN SCHEMA myschema TO anon, authenticated, service_role;
GRANT ALL ON ALL SEQUENCES IN SCHEMA myschema TO anon, authenticated, service_role;
ALTER DEFAULT PRIVILEGES FOR ROLE postgres IN SCHEMA myschema GRANT ALL ON TABLES TO anon, authenticated, service_role;
ALTER DEFAULT PRIVILEGES FOR ROLE postgres IN SCHEMA myschema GRANT ALL ON ROUTINES TO anon, authenticated, service_role;
ALTER DEFAULT PRIVILEGES FOR ROLE postgres IN SCHEMA myschema GRANT ALL ON SEQUENCES TO anon, authenticated, service_role;
```

Now you can access these schemas from data APIs:


# Auth

Use Supabase to authenticate and authorize your users.

Supabase Auth makes it easy to implement authentication and authorization in your app. We provide client SDKs and API endpoints to help you create and manage users.

Your users can use many popular Auth methods, including password, magic link, one-time password (OTP), social login, and single sign-on (SSO).


## About authentication and authorization

Authentication and authorization are the core responsibilities of any Auth system.

*   **Authentication** means checking that a user is who they say they are.
*   **Authorization** means checking what resources a user is allowed to access.

Supabase Auth uses [JSON Web Tokens (JWTs)](/docs/guides/auth/jwts) for authentication. Auth integrates with Supabase's database features, making it easy to use [Row Level Security (RLS)](/docs/guides/database/postgres/row-level-security) for authorization.


## The Supabase ecosystem

You can use Supabase Auth as a standalone product, but it's also built to integrate with the Supabase ecosystem.

Auth uses your project's Postgres database under the hood, storing user data and other Auth information in a special schema. You can connect this data to your own tables using triggers and foreign key references.

Auth also enables access control to your database's automatically generated [REST API](/docs/guides/api). When using Supabase SDKs, your data requests are automatically sent with the user's Auth Token. The Auth Token scopes database access on a row-by-row level when used along with [RLS policies](/docs/guides/database/postgres/row-level-security).


## Providers

Supabase Auth works with many popular Auth methods, including Social and Phone Auth using third-party providers. See the following sections for a list of supported third-party providers.


### Social Auth


### Phone Auth


## Pricing

Charges apply to Monthly Active Users (MAU), Monthly Active Third-Party Users (Third-Party MAU), and Monthly Active SSO Users (SSO MAU) and Advanced MFA Add-ons. For a detailed breakdown of how these charges are calculated, refer to the following pages:

*   [Pricing MAU](/docs/guides/platform/manage-your-usage/monthly-active-users)
*   [Pricing Third-Party MAU](/docs/guides/platform/manage-your-usage/monthly-active-users-third-party)
*   [Pricing SSO MAU](/docs/guides/platform/manage-your-usage/monthly-active-users-sso)
*   [Advanced MFA - Phone](/docs/guides/platform/manage-your-usage/advanced-mfa-phone)


# Auth architecture

The architecture behind Supabase Auth.

There are four major layers to Supabase Auth:

1.  [Client layer.](#client-layer) This can be one of the Supabase client SDKs, or manually made HTTP requests using the HTTP client of your choice.
2.  Kong API gateway. This is shared between all Supabase products.
3.  [Auth service](#auth-service) (formerly known as GoTrue).
4.  [Postgres database.](#postgres) This is shared between all Supabase products.


## Client layer

The client layer runs in your app. This could be running in many places, including:

*   Your frontend browser code
*   Your backend server code
*   Your native application

The client layer provides the functions that you use to sign in and manage users. We recommend using the Supabase client SDKs, which handle:

*   Configuration and authentication of HTTP calls to the Supabase Auth backend
*   Persistence, refresh, and removal of Auth Tokens in your app's storage medium
*   Integration with other Supabase products

But at its core, this layer manages the making of HTTP calls, so you could write your own client layer if you wanted to.

See the Client SDKs for more information:

*   [JavaScript](/docs/reference/javascript/introduction)
*   [Flutter](/docs/reference/dart/introduction)
*   [Swift](/docs/reference/swift/introduction)
*   [Python](/docs/reference/python/introduction)
*   [C#](/docs/reference/csharp/introduction)
*   [Kotlin](/docs/reference/kotlin/introduction)


## Auth service

The [Auth service](https://github.com/supabase/auth) is an Auth API server written and maintained by Supabase. It is a fork of the GoTrue project, originally created by Netlify.

When you deploy a new Supabase project, we deploy an instance of this server alongside your database, and inject your database with the required Auth schema.

The Auth service is responsible for:

*   Validating, issuing, and refreshing JWTs
*   Serving as the intermediary between your app and Auth information in the database
*   Communicating with external providers for Social Login and SSO


## Postgres

Supabase Auth uses the `auth` schema in your Postgres database to store user tables and other information. For security, this schema is not exposed on the auto-generated API.

You can connect Auth information to your own objects using [database triggers](/docs/guides/database/postgres/triggers) and [foreign keys](https://www.postgresql.org/docs/current/tutorial-fk.html). Make sure that any views you create for Auth data are adequately protected by [enabling RLS](/docs/guides/database/postgres/row-level-security) or [revoking grants](https://www.postgresql.org/docs/current/sql-revoke.html).


# Anonymous Sign-Ins

Create and use anonymous users to authenticate with Supabase

[Enable Anonymous Sign-Ins](/dashboard/project/_/settings/auth) to build apps which provide users an authenticated experience without requiring users to enter an email address, password, use an OAuth provider or provide any other PII (Personally Identifiable Information). Later, when ready, the user can link an authentication method to their account.

Anonymous sign-ins can be used to build:

*   E-commerce applications, such as shopping carts before check-out
*   Full-feature demos without collecting personal information
*   Temporary or throw-away accounts


## Sign in anonymously


## Convert an anonymous user to a permanent user

Converting an anonymous user to a permanent user requires [linking an identity](/docs/guides/auth/auth-identity-linking#manual-linking-beta) to the user. This requires you to [enable manual linking](/dashboard/project/_/settings/auth) in your Supabase project.


### Link an email / phone identity


### Link an OAuth identity


## Access control

An anonymous user assumes the `authenticated` role just like a permanent user. You can use row-level security (RLS) policies to differentiate between an anonymous user and a permanent user by checking for the `is_anonymous` claim in the JWT returned by `auth.jwt()`:

```sql
create policy "Only permanent users can post to the news feed"
on news_feed as restrictive for insert
to authenticated
with check ((select (auth.jwt()->>'is_anonymous')::boolean) is false );

create policy "Anonymous and permanent users can view the news feed"
on news_feed for select
to authenticated
using ( true );
```


## Resolving identity conflicts

Depending on your application requirements, data conflicts can arise when an anonymous user is converted to a permanent user. For example, in the context of an e-commerce application, an anonymous user would be allowed to add items to the shopping cart without signing up / signing in. When they decide to sign-in to an existing account, you will need to decide how you want to resolve data conflicts in the shopping cart:

1.  Overwrite the items in the cart with those in the existing account
2.  Overwrite the items in the cart with those from the anonymous user
3.  Merge the items in the cart together


### Linking an anonymous user to an existing account

In some cases, you may need to link an anonymous user to an existing account rather than creating a new permanent account. This process requires manual handling of potential conflicts. Here's a general approach:

```javascript
// 1. Sign in anonymously (assuming the user is already signed in anonymously)
const { data: anonData, error: anonError } = await supabase.auth.getSession()

// 2. Attempt to update the user with the existing email
const { data: updateData, error: updateError } = await supabase.auth.updateUser({
  email: 'valid.email@supabase.io',
})

// 3. Handle the error (since the email belongs to an existing user)
if (updateError) {
  console.log('This email belongs to an existing user. Please sign in to that account.')

  // 4. Sign in to the existing account
  const {
    data: { user: existingUser },
    error: signInError,
  } = await supabase.auth.signInWithPassword({
    email: 'valid.email@supabase.io',
    password: 'user_password',
  })

  if (existingUser) {
    // 5. Reassign entities tied to the anonymous user
    // This step will vary based on your specific use case and data model
    const { data: reassignData, error: reassignError } = await supabase
      .from('your_table')
      .update({ user_id: existingUser.id })
      .eq('user_id', anonData.session.user.id)

    // 6. Implement your chosen conflict resolution strategy
    // This could involve merging data, overwriting, or other custom logic
    await resolveDataConflicts(anonData.session.user.id, existingUser.id)
  }
}

// Helper function to resolve data conflicts (implement based on your strategy)
async function resolveDataConflicts(anonymousUserId, existingUserId) {
  // Implement your conflict resolution logic here
  // This could involve ignoring the anonymous user's metadata, overwriting the existing user's metadata, or merging the data of both the anonymous and existing user.
}
```


## Abuse prevention and rate limits

Since anonymous users are stored in your database, bad actors can abuse the endpoint to increase your database size drastically. It is strongly recommended to [enable invisible CAPTCHA or Cloudflare Turnstile](/docs/guides/auth/auth-captcha) to prevent abuse for anonymous sign-ins. An IP-based rate limit is enforced at 30 requests per hour which can be modified in your [dashboard](/dashboard/project/_/auth/rate-limits). You can refer to the full list of rate limits [here](/docs/guides/platform/going-into-prod#rate-limiting-resource-allocation--abuse-prevention).


## Automatic cleanup

Automatic cleanup of anonymous users is currently not available. Instead, you can delete anonymous users from your project by running the following SQL:

```sql
-- deletes anonymous users created more than 30 days ago
delete from auth.users
where is_anonymous is true and created_at < now() - interval '30 days';
```


## Resources

*   [Supabase - Get started for free](https://supabase.com)
*   [Supabase JS Client](https://github.com/supabase/supabase-js)
*   [Supabase Flutter Client](https://github.com/supabase/supabase-flutter)
*   [Supabase Kotlin Client](https://github.com/supabase-community/supabase-kt)


# Enable CAPTCHA Protection



Supabase provides you with the option of adding CAPTCHA to your sign-in, sign-up, and password reset forms. This keeps your website safe from bots and malicious scripts. Supabase authentication has support for [hCaptcha](https://www.hcaptcha.com/) and [Cloudflare Turnstile](https://www.cloudflare.com/products/turnstile/).


## Sign up for CAPTCHA


## Enable CAPTCHA protection for your Supabase project

Navigate to the **[Auth](https://supabase.com/dashboard/project/_/settings/auth)** section of your Project Settings in the Supabase Dashboard and find the **Enable CAPTCHA protection** toggle under Settings > Authentication > Bot and Abuse Protection > Enable CAPTCHA protection.

Select your CAPTCHA provider from the dropdown, enter your CAPTCHA **Secret key**, and click **Save**.


## Add the CAPTCHA frontend component

The frontend requires some changes to provide the CAPTCHA on-screen for the user. This example uses React and the corresponding CAPTCHA React component, but both CAPTCHA providers can be used with any JavaScript framework.

Run the application and you should now be provided with a CAPTCHA challenge.


# Passwordless email logins

Email logins using Magic Links or One-Time Passwords (OTPs)

Supabase Auth provides several passwordless login methods. Passwordless logins allow users to sign in without a password, by clicking a confirmation link or entering a verification code.

Passwordless login can:

*   Improve the user experience by not requiring users to create and remember a password
*   Increase security by reducing the risk of password-related security breaches
*   Reduce support burden of dealing with password resets and other password-related flows

Supabase Auth offers two passwordless login methods that use the user's email address:

*   [Magic Link](#with-magic-link)
*   [OTP](#with-otp)


## With Magic Link

Magic Links are a form of passwordless login where users click on a link sent to their email address to log in to their accounts. Magic Links only work with email addresses and are one-time use only.


### Enabling Magic Link

Email authentication methods, including Magic Links, are enabled by default.

Configure the Site URL and any additional redirect URLs. These are the only URLs that are allowed as redirect destinations after the user clicks a Magic Link. You can change the URLs on the [Auth Providers page](/dashboard/project/_/auth/providers) for hosted projects, or in the [configuration file](/docs/guides/cli/config#auth.additional_redirect_urls) for self-hosted projects.

By default, a user can only request a magic link once every  and they expire after .


### Signing in with Magic Link

Call the "sign in with OTP" method from the client library.

Though the method is labelled "OTP", it sends a Magic Link by default. The two methods differ only in the content of the confirmation email sent to the user.

If the user hasn't signed up yet, they are automatically signed up by default. To prevent this, set the `shouldCreateUser` option to `false`.

That's it for the implicit flow.

If you're using PKCE flow, edit the Magic Link [email template](/docs/guides/auth/auth-email-templates) to send a token hash:

```html
<h2>Magic Link</h2>

<p>Follow this link to login:</p>
<p><a href="{{ .SiteURL }}/auth/confirm?token_hash={{ .TokenHash }}&type=email">Log In</a></p>
```

At the `/auth/confirm` endpoint, exchange the hash for the session:

```js
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('url', 'anonKey')

// ---cut---
const { error } = await supabase.auth.verifyOtp({
  token_hash: 'hash',
  type: 'email',
})
```


## With OTP

Email one-time passwords (OTP) are a form of passwordless login where users key in a six digit code sent to their email address to log in to their accounts.


### Enabling email OTP

Email authentication methods, including Email OTPs, are enabled by default.

Email OTPs share an implementation with Magic Links. To send an OTP instead of a Magic Link, alter the **Magic Link** email template. For a hosted Supabase project, go to [Email Templates](/dashboard/project/_/auth/templates) in the Dashboard. For a self-hosted project or local development, see the [Email Templates guide](/docs/guides/auth/auth-email-templates).

Modify the template to include the `{{ .Token }}` variable, for example:

```html
<h2>One time login code</h2>

<p>Please enter this code: {{ .Token }}</p>
```

By default, a user can only request an OTP once every  and they expire after . This is configurable via `Auth > Providers > Email > Email OTP Expiration`. An expiry duration of more than 86400 seconds (one day) is disallowed to guard against brute force attacks. The longer an OTP remains valid, the more time an attacker has to attempt brute force attacks. If the OTP is valid for several days, an attacker might have more opportunities to guess the correct OTP through repeated attempts.


### Signing in with email OTP


#### Step 1: Send the user an OTP code

Get the user's email and call the "sign in with OTP" method from your client library.

If the user hasn't signed up yet, they are automatically signed up by default. To prevent this, set the `shouldCreateUser` option to `false`.

If the request is successful, you receive a response with `error: null` and a `data` object where both `user` and `session` are null. Let the user know to check their email inbox.

```json
{
  "data": {
    "user": null,
    "session": null
  },
  "error": null
}
```


#### Step 2: Verify the OTP to create a session

Provide an input field for the user to enter their one-time code.

Call the "verify OTP" method from your client library with the user's email address, the code, and a type of `email`:

If successful, the user is now logged in, and you receive a valid session that looks like:

```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJhdXRoZW50aWNhdGVkIiwiZXhwIjoxNjI3MjkxNTc3LCJzdWIiOiJmYTA2NTQ1Zi1kYmI1LTQxY2EtYjk1NC1kOGUyOTg4YzcxOTEiLCJlbWFpbCI6IiIsInBob25lIjoiNjU4NzUyMjAyOSIsImFwcF9tZXRhZGF0YSI6eyJwcm92aWRlciI6InBob25lIn0sInVzZXJfbWV0YWRhdGEiOnt9LCJyb2xlIjoiYXV0aGVudGljYXRlZCJ9.1BqRi0NbS_yr1f6hnr4q3s1ylMR3c1vkiJ4e_N55dhM",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "LSp8LglPPvf0DxGMSj-vaQ",
  "user": {...}
}
```


# Email Templates

Learn how to manage the email templates in Supabase.

You can customize the email messages used for the authentication flows. You can edit the following email templates:

*   Confirm signup
*   Invite user
*   Magic Link
*   Change Email Address
*   Reset Password


## Terminology

The templating system provides the following variables for use:

| Name                     | Description                                                                                                                                                                                                                                                                           |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `{{ .ConfirmationURL }}` | Contains the confirmation URL. For example, a signup confirmation URL would look like: `https://project-ref.supabase.co/auth/v1/verify?token={{ .TokenHash }}&type=email&redirect_to=https://example.com/path` .                                                                      |
| `{{ .Token }}`           | Contains a 6-digit One-Time-Password (OTP) that can be used instead of the `{{. ConfirmationURL }}` .                                                                                                                                                                                 |
| `{{ .TokenHash }}`       | Contains a hashed version of the `{{ .Token }}`. This is useful for constructing your own email link in the email template.                                                                                                                                                           |
| `{{ .SiteURL }}`         | Contains your application's Site URL. This can be configured in your project's [authentication settings](/dashboard/project/_/auth/url-configuration).                                                                                                                                |
| `{{ .RedirectTo }}`      | Contains the redirect URL passed when `signUp`, `signInWithOtp`, `signInWithOAuth`, `resetPasswordForEmail` or `inviteUserByEmail` is called. The redirect URL allow list can be configured in your project's [authentication settings](/dashboard/project/_/auth/url-configuration). |
| `{{ .Data }}`            | Contains metadata from `auth.users.user_metadata`. Use this to personalize the email message.                                                                                                                                                                                         |


## Editing email templates

On hosted Supabase projects, edit your email templates on the [Email Templates](/dashboard/project/_/auth/templates) page. On self-hosted projects or in local development, edit your [configuration files](/docs/guides/local-development/customizing-email-templates).


## Mobile deep linking

For mobile applications, you might need to link or redirect to a specific page within your app. See the [Mobile Deep Linking guide](/docs/guides/auth/native-mobile-deep-linking) to set this up.


## Limitations


### Email prefetching

Certain email providers may have spam detection or other security features that prefetch URL links from incoming emails (e.g. [Safe Links in Microsoft Defender for Office 365](https://learn.microsoft.com/en-us/microsoft-365/security/office-365-security/safe-links-about?view=o365-worldwide)).
In this scenario, the `{{ .ConfirmationURL }}` sent will be consumed instantly which leads to a "Token has expired or is invalid" error.
To guard against this:

*   Use an email OTP instead by including `{{ .Token }}` in the email template.
*   Create your own custom email link to redirect the user to a page where they can click on a button to confirm the action.
    For example, you can include the following in your email template:

    ```html
    <a href="{{ .SiteURL }}/confirm-signup?confirmation_url={{ .ConfirmationURL }}"
      >Confirm your signup
    </a>
    ```

    The user should be brought to a page on your site where they can confirm the action by clicking a button.
    The button should contain the actual confirmation link which can be obtained from parsing the `confirmation_url={{ .ConfirmationURL }}` query parameter in the URL.


### Email tracking

If you are using an external email provider that enables "email tracking", the links inside the Supabase email templates will be overwritten and won't perform as expected. We recommend disabling email tracking to ensure email links are not overwritten.


### Redirecting the user to a server-side endpoint

If you intend to use [Server-side rendering](/docs/guides/auth/server-side-rendering), you might want the email link to redirect the user to a server-side endpoint to check if they are authenticated before returning the page. However, the default email link will redirect the user after verification to the redirect URL with the session in the query fragments. Since the session is returned in the query fragments by default, you won't be able to access it on the server-side.

You can customize the email link in the email template to redirect the user to a server-side endpoint successfully. For example:

```html
<a
  href="https://api.example.com/v1/authenticate?token_hash={{ .TokenHash }}&type=invite&redirect_to={{ .RedirectTo }}"
  >Accept the invite
</a>
```

When the user clicks on the link, the request will hit `https://api.example.com/v1/authenticate` and you can grab the `token_hash`, `type` and `redirect_to` query parameters from the URL. Then, you can call the [`verifyOtp`](/docs/reference/javascript/auth-verifyotp) method to get back an authenticated session before redirecting the user back to the client. Since the `verifyOtp` method makes a `POST` request to Supabase Auth to verify the user, the session will be returned in the response body, which can be read by the server. For example:

```ts
import { createClient, type EmailOtpType } from '@supabase/supabase-js'
const supabase = createClient('https://your-project-id.supabase.co', 'your-anon-key')

// ---cut---
const { token_hash, type } = Object.fromEntries(new URLSearchParams(window.location.search))
const {
  data: { session },
  error,
} = await supabase.auth.verifyOtp({ token_hash, type: type as EmailOtpType })

// subsequently redirect the user back to the client using the redirect_to param
// ...
```


## Customization

Supabase Auth makes use of [Go Templates](https://pkg.go.dev/text/template). This means it is possible to conditionally render information based on template properties.


### Send different email to early access users

Send a different email to users who signed up via an early access domain (`https://www.earlyaccess.trial.com`).

    {{ if eq .Data.Domain "https://www.example.com" }}
    <h1>Welcome to Our Database Service!</h1>
      <p>Dear Developer,</p>
      <p>Welcome to Billy, the scalable developer platform!</p>
      <p>Best Regards,<br>
    Billy Team</p>
    {{ else if eq .Data.Domain "https://www.earlyaccess.trial.com" }}
    <h1>Welcome to Our Database Service!</h1>
      <p>Dear Developer,</p>
      <p>Welcome Billy, the scalable developer platform!</p>
      <p> As an early access member, you have access to select features like Point To Space Restoration.</p>
      <p>Best Regards,<br>
    Billy Team</p>
    {{ end }}


# Auth Helpers



Working with server-side frameworks is slightly different to client-side frameworks. In this section we cover the various ways of handling server-side authentication and demonstrate how to use the Supabase helper-libraries to make the process more seamless.


## Status

The Auth Helpers are `deprecated`. Use the new `@supabase/ssr` package for Server Side Authentication. Use the [migration doc](/docs/guides/auth/server-side/migrating-to-ssr-from-auth-helpers) to learn more.


## Additional links

*   [Source code](https://github.com/supabase/auth-helpers)
*   [Known bugs and issues](https://github.com/supabase/auth-helpers/issues)


# Auth UI



Auth UI is a pre-built React component for authenticating users.
It supports custom themes and extensible styles to match your brand and aesthetic.


## Set up Auth UI

Install the latest version of [supabase-js](/docs/reference/javascript) and the Auth UI package:

```bash
npm install @supabase/supabase-js @supabase/auth-ui-react @supabase/auth-ui-shared
```


### Import the Auth component

Pass `supabaseClient` from `@supabase/supabase-js` as a prop to the component.

```js /src/index.js
import { createClient } from '@supabase/supabase-js'
import { Auth } from '@supabase/auth-ui-react'

const supabase = createClient('<INSERT PROJECT URL>', '<INSERT PROJECT ANON API KEY>')

const App = () => <Auth supabaseClient={supabase} />
```

This renders the Auth component without any styling.
We recommend using one of the predefined themes to style the UI.
Import the theme you want to use and pass it to the `appearance.theme` prop.

```js
import { Auth } from '@supabase/auth-ui-react'
import {
  // Import predefined theme
  ThemeSupa,
} from '@supabase/auth-ui-shared'

const supabase = createClient(
  '<INSERT PROJECT URL>',
  '<INSERT PROJECT ANON API KEY>'
)

const App = () => (
  <Auth
    supabaseClient={supabase}
    {/* Apply predefined theme */}
    appearance={{ theme: ThemeSupa }}
  />
)
```


### Social providers

The Auth component also supports login with [official social providers](../../auth#providers).

```js
import { createClient } from '@supabase/supabase-js'
import { Auth } from '@supabase/auth-ui-react'
import { ThemeSupa } from '@supabase/auth-ui-shared'

const supabase = createClient('<INSERT PROJECT URL>', '<INSERT PROJECT ANON API KEY>')

const App = () => (
  <Auth
    supabaseClient={supabase}
    appearance={{ theme: ThemeSupa }}
    providers={['google', 'facebook', 'twitter']}
  />
)
```


### Options

Options are available via `queryParams`:

```jsx
<Auth
  supabaseClient={supabase}
  providers={['google']}
  queryParams={{
    access_type: 'offline',
    prompt: 'consent',
    hd: 'domain.com',
  }}
  onlyThirdPartyProviders
/>
```


### Provider scopes

Provider Scopes can be requested through `providerScope`;

```jsx
<Auth
  supabaseClient={supabase}
  providers={['google']}
  queryParams={{
    access_type: 'offline',
    prompt: 'consent',
    hd: 'domain.com',
  }}
  providerScopes={{
    google: 'https://www.googleapis.com/auth/calendar.readonly',
  }}
/>
```


### Supported views

The Auth component is currently shipped with the following views:

*   [Email Login](../auth-email)
*   [Magic Link login](../auth-magic-link)
*   [Social Login](../social-login)
*   Update password
*   Forgotten password

We are planning on adding more views in the future. Follow along on that [repo](https://github.com/supabase/auth-ui).


## Customization

There are several ways to customize Auth UI:

*   Use one of the [predefined themes](#predefined-themes) that comes with Auth UI
*   Extend a theme by [overriding the variable tokens](#override-themes) in a theme
*   [Create your own theme](#create-theme)
*   [Use your own CSS classes](#custom-css-classes)
*   [Use inline styles](#custom-inline-styles)
*   [Use your own labels](#custom-labels)


### Predefined themes

Auth UI comes with several themes to customize the appearance. Each predefined theme comes with at least two variations, a `default` variation, and a `dark` variation. You can switch between these themes using the `theme` prop. Import the theme you want to use and pass it to the `appearance.theme` prop.

```js
import { createClient } from '@supabase/supabase-js'
import { Auth } from '@supabase/auth-ui-react'
import { ThemeSupa } from '@supabase/auth-ui-shared'

const supabase = createClient(
  '<INSERT PROJECT URL>',
  '<INSERT PROJECT ANON API KEY>'
)

const App = () => (
  <Auth
    supabaseClient={supabase}
    {/* Apply predefined theme */}
    appearance={{ theme: ThemeSupa }}
  />
)
```


### Switch theme variations

Auth UI comes with two theme variations: `default` and `dark`. You can switch between these themes with the `theme` prop.

```js
import { createClient } from '@supabase/supabase-js'
import { Auth } from '@supabase/auth-ui-react'
import { ThemeSupa } from '@supabase/auth-ui-shared'

const supabase = createClient(
  '<INSERT PROJECT URL>',
  '<INSERT PROJECT ANON API KEY>'
)

const App = () => (
  <Auth
    supabaseClient={supabase}
    appearance={{ theme: ThemeSupa }}
    {/* Set theme to dark */}
    theme="dark"
  />
)
```

If you don't pass a value to `theme` it uses the `"default"` theme. You can pass `"dark"` to the theme prop to switch to the `dark` theme. If your theme has other variations, use the name of the variation in this prop.


### Override themes

Auth UI themes can be overridden using variable tokens. See the [list of variable tokens](https://github.com/supabase/auth-ui/blob/main/packages/shared/src/theming/Themes.ts).

```js
import { createClient } from '@supabase/supabase-js'
import { Auth } from '@supabase/auth-ui-react'
import { ThemeSupa } from '@supabase/auth-ui-shared'

const supabase = createClient('<INSERT PROJECT URL>', '<INSERT PROJECT ANON API KEY>')

const App = () => (
  <Auth
    supabaseClient={supabase}
    appearance={{
      theme: ThemeSupa,
      variables: {
        default: {
          colors: {
            brand: 'red',
            brandAccent: 'darkred',
          },
        },
      },
    }}
  />
)
```

If you created your own theme, you may not need to override any of them.


### Create your own theme \[#create-theme]

You can create your own theme by following the same structure within a `appearance.theme` property.
See the list of [tokens within a theme](https://github.com/supabase/auth-ui/blob/main/packages/shared/src/theming/Themes.ts).

```js /src/index.js
import { createClient } from '@supabase/supabase-js'
import { Auth } from '@supabase/auth-ui-react'

const supabase = createClient('<INSERT PROJECT URL>', '<INSERT PROJECT ANON API KEY>')

const customTheme = {
  default: {
    colors: {
      brand: 'hsl(153 60.0% 53.0%)',
      brandAccent: 'hsl(154 54.8% 45.1%)',
      brandButtonText: 'white',
      // ..
    },
  },
  dark: {
    colors: {
      brandButtonText: 'white',
      defaultButtonBackground: '#2e2e2e',
      defaultButtonBackgroundHover: '#3e3e3e',
      //..
    },
  },
  // You can also add more theme variations with different names.
  evenDarker: {
    colors: {
      brandButtonText: 'white',
      defaultButtonBackground: '#1e1e1e',
      defaultButtonBackgroundHover: '#2e2e2e',
      //..
    },
  },
}

const App = () => (
  <Auth
    supabaseClient={supabase}
    theme="default" // can also be "dark" or "evenDarker"
    appearance={{ theme: customTheme }}
  />
)
```

You can switch between different variations of your theme with the ["theme" prop](#switch-theme-variations).


### Custom CSS classes \[#custom-css-classes]

You can use custom CSS classes for the following elements:
`"button"`, `"container"`, `"anchor"`, `"divider"`, `"label"`, `"input"`, `"loader"`, `"message"`.

```js /src/index.js
import { createClient } from '@supabase/supabase-js'
import { Auth } from '@supabase/auth-ui-react'

const supabase = createClient('<INSERT PROJECT URL>', '<INSERT PROJECT ANON API KEY>')

const App = () => (
  <Auth
    supabaseClient={supabase}
    appearance={{
      // If you want to extend the default styles instead of overriding it, set this to true
      extend: false,
      // Your custom classes
      className: {
        anchor: 'my-awesome-anchor',
        button: 'my-awesome-button',
        //..
      },
    }}
  />
)
```


### Custom inline CSS \[#custom-inline-styles]

You can use custom CSS inline styles for the following elements:
`"button"`, `"container"`, `"anchor"`, `"divider"`, `"label"`, `"input"`, `"loader"`, `"message"`.

```js /src/index.js
import { createClient } from '@supabase/supabase-js'
import { Auth } from '@supabase/auth-ui-react'

const supabase = createClient('<INSERT PROJECT URL>', '<INSERT PROJECT ANON API KEY>')

const App = () => (
  <Auth
    supabaseClient={supabase}
    appearance={{
      style: {
        button: { background: 'red', color: 'white' },
        anchor: { color: 'blue' },
        //..
      },
    }}
  />
)
```


### Custom labels \[#custom-labels]

You can use custom labels with `localization.variables` like so:

```js
import { createClient } from '@supabase/supabase-js'
import { Auth } from '@supabase/auth-ui-react'

const supabase = createClient('<INSERT PROJECT URL>', '<INSERT PROJECT ANON API KEY>')

const App = () => (
  <Auth
    supabaseClient={supabase}
    localization={{
      variables: {
        sign_in: {
          email_label: 'Your email address',
          password_label: 'Your strong password',
        },
      },
    }}
  />
)
```

A full list of the available variables is below:


### Hiding links \[#hiding-links]

You can hide links by setting the `showLinks` prop to `false`

```js
import { createClient } from '@supabase/supabase-js'
import { Auth } from '@supabase/auth-ui-react'

const supabase = createClient('<INSERT PROJECT URL>', '<INSERT PROJECT ANON API KEY>')

const App = () => <Auth supabaseClient={supabase} showLinks={false} />
```

Setting `showLinks` to `false` will hide the following links:

*   Don't have an account? Sign up
*   Already have an account? Sign in
*   Send a magic link email
*   Forgot your password?


### Sign in and sign up views

Add `sign_in` or `sign_up` views with the `view` prop:

    <Auth
      supabaseClient={supabase}
      view="sign_up"
    />


# Flutter Auth UI



Flutter Auth UI is a Flutter package containing pre-built widgets for authenticating users.
It is unstyled and can match your brand and aesthetic.

![Flutter Auth UI](https://raw.githubusercontent.com/supabase-community/flutter-auth-ui/main/screenshots/supabase_auth_ui.png)


## Add Flutter Auth UI

Add the latest version of the package [supabase-auth-ui](https://pub.dev/packages/supabase_auth_ui) to pubspec.yaml:

```bash
flutter pub add supabase_auth_ui
```


### Initialize the Flutter Auth package

```dart
import 'package:flutter/material.dart';
import 'package:supabase_auth_ui/supabase_auth_ui.dart';

void main() async {
  await Supabase.initialize(
    url: dotenv.get('SUPABASE_URL'),
    anonKey: dotenv.get('SUPABASE_ANON_KEY'),
  );

  runApp(const MyApp());
}
```


### Email Auth

Use a `SupaEmailAuth` widget to create an email and password signin and signup form. It also contains a button to toggle to display a forgot password form.

You can pass `metadataFields` to add additional fields to the form to pass as metadata to Supabase.

```dart
SupaEmailAuth(
  redirectTo: kIsWeb ? null : 'io.mydomain.myapp://callback',
  onSignInComplete: (response) {},
  onSignUpComplete: (response) {},
  metadataFields: [
    MetaDataField(
    prefixIcon: const Icon(Icons.person),
    label: 'Username',
    key: 'username',
    validator: (val) {
            if (val == null || val.isEmpty) {
            return 'Please enter something';
            }
            return null;
          },
        ),
    ],
)
```


### Magic link Auth

Use `SupaMagicAuth` widget to create a magic link signIn form.

```dart
SupaMagicAuth(
  redirectUrl: kIsWeb ? null : 'io.mydomain.myapp://callback',
  onSuccess: (Session response) {},
  onError: (error) {},
)
```


### Reset password

Use `SupaResetPassword` to create a password reset form.

```dart
SupaResetPassword(
  accessToken: supabase.auth.currentSession?.accessToken,
  onSuccess: (UserResponse response) {},
  onError: (error) {},
)
```


### Phone Auth

Use `SupaPhoneAuth` to create a phone authentication form.

```dart
SupaPhoneAuth(
  authAction: SupaAuthAction.signUp,
  onSuccess: (AuthResponse response) {},
),
```


### Social Auth

The package supports login with [official social providers](../../auth#providers).

Use `SupaSocialsAuth` to create list of social login buttons.

```dart
SupaSocialsAuth(
  socialProviders: [
    OAuthProvider.apple,
    OAuthProvider.google,
  ],
  colored: true,
  redirectUrl: kIsWeb
    ? null
    : 'io.mydomain.myapp://callback',
  onSuccess: (Session response) {},
  onError: (error) {},
)
```


### Theming

This package uses plain Flutter components allowing you to control the appearance of the components using your own theme.


# Supabase Auth with Next.js Pages Directory





# Supabase Auth with the Next.js App Router





# Supabase Auth with Remix





# Supabase Auth with SvelteKit





# Auth Hooks

Use HTTP or Postgres Functions to customize your authentication flow

## What is a hook

A hook is an endpoint that allows you to alter the default Supabase Auth flow at specific execution points. Developers can use hooks to add custom behavior that's not supported natively.

Hooks help you:

*   Track the origin of user signups by adding metadata
*   Improve security by adding additional checks to password and multi-factor authentication
*   Support legacy systems by integrating with identity credentials from external authentication systems
*   Add additional custom claims to your JWT
*   Send authentication emails or SMS messages through a custom provider

The following hooks are available:

| Hook                                                                                     | Available on Plan    |
| ---------------------------------------------------------------------------------------- | -------------------- |
| [Custom Access Token](/docs/guides/auth/auth-hooks/custom-access-token-hook)             | Free, Pro            |
| [Send SMS](/docs/guides/auth/auth-hooks/send-sms-hook)                                   | Free, Pro            |
| [Send Email](/docs/guides/auth/auth-hooks/send-email-hook)                               | Free, Pro            |
| [MFA Verification Attempt](/docs/guides/auth/auth-hooks/mfa-verification-hook)           | Teams and Enterprise |
| [Password Verification Attempt](/docs/guides/auth/auth-hooks/password-verification-hook) | Teams and Enterprise |

Supabase supports 2 ways to [configure a hook](/dashboard/project/_/auth/hooks) in your project:


## Security model

Sign the payload and grant permissions selectively in order to guard the integrity of the payload.


## Using Hooks


### Developing

Let us develop a Hook locally and then deploy it to the cloud. As a recap, here’s a list of available Hooks

| Hook                          | Suggested Function Name         | When it is called                                  | What it Does                                                                                              |
| ----------------------------- | ------------------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| Send SMS                      | `send_sms`                      | Each time an SMS is sent                           | Allows you to customize message content and SMS Provider                                                  |
| Send Email                    | `send_email`                    | Each time an Email is sent                         | Allows you to customize message content and Email Provider                                                |
| Custom Access Token           | `custom_access_token`           | Each time a new JWT is created                     | Returns the claims you wish to be present in the JWT.                                                     |
| MFA Verification Attempt      | `mfa_verification_attempt`      | Each time a user tries to verify an MFA factor.    | Returns a decision on whether to reject the attempt and future ones, or to allow the user to keep trying. |
| Password Verification Attempt | `password_verification_attempt` | Each time a user tries to sign in with a password. | Return a decision whether to allow the user to reject the attempt, or to allow the user to keep trying.   |

Edit `config.toml` to set up the Auth Hook locally.


### Deploying

In the dashboard, navigate to [`Authentication > Hooks`](/dashboard/project/_/auth/hooks) and select the appropriate function type (SQL or HTTP) from the dropdown menu.


### Error handling

You should return an error when facing a runtime error. Runtime errors are specific to your application and arise from specific business rules rather than programmer errors.

Runtime errors could happen when:

*   The user does not have appropriate permissions
*   The event payload received does not have required claims.
*   The user has performed an action which violates a business rule.
*   The email or phone provider used in the webhook returned an error.

Outside of runtime errors, both HTTP Hooks and Postgres Hooks return timeout errors. Postgres Hooks have  seconds to complete processing while HTTP Hooks should complete in  seconds. Both HTTP Hooks and Postgres Hooks are run in a transaction do limit the duration of execution to avoid delays in authentication process.


## Available Hooks

Each Hook description contains an example JSON Schema which you can use in conjunction with [JSON Schema Faker](https://json-schema-faker.js.org/) in order to generate a mock payload. For HTTP Hooks, you can also use [the Standard Webhooks Testing Tool](https://www.standardwebhooks.com/simulate) to simulate a request.


# Custom Access Token Hook

Customize the access token issued by Supabase Auth

The custom access token hook runs before a token is issued and allows you to add additional claims based on the authentication method used.

Claims returned must conform to our specification. Supabase Auth will check for these claims after the hook is run and return an error if they are not present.

These are the fields currently available on an access token:

Required Claims: `iss`, `aud`, `exp`, `iat`, `sub`, `role`, `aal`, `session_id`
Optional Claims: `jti`, `nbf`, `app_metadata`, `user_metadata`, `amr`, `email`, `phone`

**Inputs**

| Field                   | Type     | Description                                                                                                                                                                                                                           |
| ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user_id`               | `string` | Unique identifier for the user attempting to sign in.                                                                                                                                                                                 |
| `claims`                | `object` | Claims which are included in the access token.                                                                                                                                                                                        |
| `authentication_method` | `string` | The authentication method used to request the access token. Possible values include: `oauth`, `password`, `otp`, `totp`, `recovery`, `invite`, `sso/saml`, `magiclink`, `email/signup`, `email_change`, `token_refresh`, `anonymous`. |

**Outputs**

Return these only if your hook processed the input without errors.

| Field    | Type     | Description                                     |
| -------- | -------- | ----------------------------------------------- |
| `claims` | `object` | The updated claims after the hook has been run. |


# MFA Verification Hook



You can add additional checks to the [Supabase MFA implementation](/docs/guides/auth/auth-mfa) with hooks. For example, you can:

*   Limit the number of verification attempts performed over a period of time.
*   Sign out users who have too many invalid verification attempts.
*   Count, rate limit, or ban sign-ins.

**Inputs**

Supabase Auth will send a payload containing these fields to your hook:

| Field         | Type      | Description                                                                                                                       |
| ------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `factor_id`   | `string`  | Unique identifier for the MFA factor being verified                                                                               |
| `factor_type` | `string`  | `totp` or `phone`                                                                                                                 |
| `user_id`     | `string`  | Unique identifier for the user                                                                                                    |
| `valid`       | `boolean` | Whether the verification attempt was valid. For TOTP, this means that the six digit code was correct (true) or incorrect (false). |

**Outputs**

Return this if your hook processed the input without errors.

| Field      | Type     | Description                                                                                                                                                                                                           |
| ---------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `decision` | `string` | The decision on whether to allow authentication to move forward. Use `reject` to deny the verification attempt and log the user out of all active sessions. Use `continue` to use the default Supabase Auth behavior. |
| `message`  | `string` | The message to show the user if the decision was `reject`.                                                                                                                                                            |

```json
{
  "decision": "reject",
  "message": "You have exceeded maximum number of MFA attempts."
}
```


# Password Verification Hook



Your company wishes to increase security beyond the requirements of the default password implementation in order to fulfill security or compliance requirements. You plan to track the status of a password sign-in attempt and take action via an email or a restriction on logins where necessary.

As this hook runs on unauthenticated requests, malicious users can abuse the hook by calling it multiple times. Pay extra care when using the hook as you can unintentionally block legitimate users from accessing your application.

Check if a password is valid prior to taking any additional action to ensure the user is legitimate. Where possible, send an email or notification instead of blocking the user.

**Inputs**

| Field     | Type      | Description                                                                                     |
| --------- | --------- | ----------------------------------------------------------------------------------------------- |
| `user_id` | `string`  | Unique identifier for the user attempting to sign in. Correlate this to the `auth.users` table. |
| `valid`   | `boolean` | Whether the password verification attempt was valid.                                            |

**Outputs**

Return these only if your hook processed the input without errors.

| Field                | Type      | Description                                                                                                                                                                                                           |
| -------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `decision`           | `string`  | The decision on whether to allow authentication to move forward. Use `reject` to deny the verification attempt and log the user out of all active sessions. Use `continue` to use the default Supabase Auth behavior. |
| `message`            | `string`  | The message to show the user if the decision was `reject`.                                                                                                                                                            |
| `should_logout_user` | `boolean` | Whether to log out the user if a `reject` decision is issued. Has no effect when a `continue` decision is issued.                                                                                                     |

```json
{
  "decision": "reject",
  "message": "You have exceeded maximum number of password sign-in attempts.",
  "should_logout_user": "false"
}
```


# Send Email Hook

Use a custom email provider to send authentication messages

The Send Email Hook runs before an email is sent and allows for flexibility around email sending. You can use this hook to configure a back-up email provider or add internationalization to your emails.


## Email sending behavior

Email sending depends on two settings: Email Provider and Auth Hook status.

| Email Provider | Auth Hook | Result                                                               |
| -------------- | --------- | -------------------------------------------------------------------- |
| Enabled        | Enabled   | Auth Hook handles email sending (SMTP not used)                      |
| Enabled        | Disabled  | SMTP handles email sending (custom if configured, default otherwise) |
| Disabled       | Enabled   | Email Signups Disabled                                               |
| Disabled       | Disabled  | Email Signups Disabled                                               |

**Inputs**

| Field   | Type                                              | Description                                                                        |
| ------- | ------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `user`  | [`User`](/docs/guides/auth/users#the-user-object) | The user attempting to sign in.                                                    |
| `email` | `object`                                          | Metadata specific to the email sending process. Includes the OTP and `token_hash`. |

**Outputs**

*   No outputs are required. An empty response with a status code of 200 is taken as a successful response.


# Send SMS Hook

Use a custom SMS provider to send authentication messages

Runs before a message is sent. Use the hook to:

*   Use a regional SMS Provider
*   Use alternate messaging channels such as WhatsApp
*   Adjust the message body to include platform specific fields such as the [`AppHash`](https://developers.google.com/identity/sms-retriever/overview)

**Inputs**

| Field  | Type                                              | Description                                                     |
| ------ | ------------------------------------------------- | --------------------------------------------------------------- |
| `user` | [`User`](/docs/guides/auth/users#the-user-object) | The user attempting to sign in.                                 |
| `sms`  | `object`                                          | Metadata specific to the SMS sending process. Includes the OTP. |

**Outputs**

*   No outputs are required. An empty response with a status code of 200 is taken as a successful response.


# Identity Linking

Manage the identities associated with your user

## Identity linking strategies

Currently, Supabase Auth supports 2 strategies to link an identity to a user:

1.  [Automatic Linking](#automatic-linking)
2.  [Manual Linking](#manual-linking-beta)


### Automatic linking

Supabase Auth automatically links identities with the same email address to a single user. This helps to improve the user experience when multiple OAuth login options are presented since the user does not need to remember which OAuth account they used to sign up with. When a new user signs in with OAuth, Supabase Auth will attempt to look for an existing user that uses the same email address. If a match is found, the new identity is linked to the user.

In order for automatic linking to correctly identify the user for linking, Supabase Auth needs to ensure that all user emails are unique. It would also be an insecure practice to automatically link an identity to a user with an unverified email address since that could lead to pre-account takeover attacks. To prevent this from happening, when a new identity can be linked to an existing user, Supabase Auth will remove any other unconfirmed identities linked to an existing user.

Users that signed up with [SAML SSO](/docs/guides/auth/sso/auth-sso-saml) will not be considered as targets for automatic linking.


### Manual linking (beta)

In the example above, the user will be redirected to Google to complete the OAuth2.0 flow. Once the OAuth2.0 flow has completed successfully, the user will be redirected back to the application and the Google identity will be linked to the user. You can enable manual linking from your project's authentication [configuration options](/dashboard/project/_/settings/auth) or by setting the environment variable `GOTRUE_SECURITY_MANUAL_LINKING_ENABLED: true` when self-hosting.


## Unlink an identity


## Frequently asked questions


### How to add email/password login to an OAuth account?

Call the `updateUser({ password: 'validpassword'})` to add email with password authentication to an account created with an OAuth provider (Google, GitHub, etc.).


### Can you sign up with email if already using OAuth?

If you try to create an email account after previously signing up with OAuth using the same email, you'll receive an obfuscated user response with no verification email sent. This prevents user enumeration attacks.


# Multi-Factor Authentication



Multi-factor authentication (MFA), sometimes called two-factor authentication (2FA), adds an additional layer of security to your application by verifying their identity through additional verification steps.

It is considered a best practice to use MFA for your applications.

Users with weak passwords or compromised social login accounts are prone to malicious account takeovers. These can be prevented with MFA because they require the user to provide proof of both of these:

*   Something they know.
    Password, or access to a social-login account.
*   Something they have.
    Access to an authenticator app (a.k.a. TOTP) or a mobile phone.


## Overview

Supabase Auth implements MFA via two methods: App Authenticator, which makes use of a Time based-one Time Password, and phone messaging, which makes use of a code generated by Supabase Auth.

Applications using MFA require two important flows:

1.  **Enrollment flow.**
    This lets users set up and control MFA in your app.
2.  **Authentication flow.**
    This lets users sign in using any factors after the conventional login step.

Supabase Auth provides:

*   **Enrollment API** - build rich user interfaces for adding and removing factors.
*   **Challenge and Verify APIs** - securely verify that the user has access to a factor.
*   **List Factors API** - build rich user interfaces for signing in with additional factors.

You can control access to the Enrollment API as well as the Challenge and Verify APIs via the Supabase Dashboard. A setting of `Verification Disabled` will disable both the challenge API and the verification API.

These sets of APIs let you control the MFA experience that works for you. You can create flows where MFA is optional, mandatory for all, or only specific groups of users.

Once users have enrolled or signed-in with a factor, Supabase Auth adds additional metadata to the user's access token (JWT) that your application can use to allow or deny access.

This information is represented by an [Authenticator Assurance Level](https://pages.nist.gov/800-63-3-Implementation-Resources/63B/AAL/), a standard measure about the assurance of the user's identity Supabase Auth has for that particular session. There are two levels recognized today:

1.  **Assurance Level 1: `aal1`**
    Means that the user's identity was verified using a conventional login method
    such as email+password, magic link, one-time password, phone auth or social
    login.
2.  **Assurance Level 2: `aal2`**
    Means that the user's identity was additionally verified using at least one
    second factor, such as a TOTP code or One-Time Password code.

This assurance level is encoded in the `aal` claim in the JWT associated with the user. By decoding this value you can create custom authorization rules in your frontend, backend, and database that will enforce the MFA policy that works for your application. JWTs without an `aal` claim are at the `aal1` level.


## Adding to your app

Adding MFA to your app involves these four steps:

1.  **Add enrollment flow.**
    You need to provide a UI within your app that your users will be able to set-up
    MFA in. You can add this right after sign-up, or as part of a separate flow in
    the settings portion of your app.
2.  **Add unenroll flow.**
    You need to support a UI through which users can see existing devices and unenroll
    devices which are no longer relevant.
3.  **Add challenge step to login.**
    If a user has set-up MFA, your app's login flow needs to present a challenge
    screen to the user asking them to prove they have access to the additional
    factor.
4.  **Enforce rules for MFA logins.**
    Once your users have a way to enroll and log in with MFA, you need to enforce
    authorization rules across your app: on the frontend, backend, API servers or
    Row-Level Security policies.

The enrollment flow and the challenge steps differ by factor and are covered on a separate page. Visit the [Phone](/docs/guides/auth/auth-mfa/phone) or [App Authenticator](/docs/guides/auth/auth-mfa/totp) pages to see how to add the flows for the respective factors. You can combine both flows and allow for use of both Phone and App Authenticator Factors.


### Add unenroll flow

The unenroll process is the same for both Phone and TOTP factors.

An unenroll flow provides a UI for users to manage and unenroll factors linked to their accounts. Most applications do so via a factor management page where users can view and unlink selected factors.

When a user unenrolls a factor, call `supabase.auth.mfa.unenroll()` with the ID of the factor. For example, call:

```js
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('https://your-project-id.supabase.co', 'your-anon-key')

// ---cut---
supabase.auth.mfa.unenroll({ factorId: 'd30fd651-184e-4748-a928-0a4b9be1d429' })
```

to unenroll a factor with ID `d30fd651-184e-4748-a928-0a4b9be1d429`.


### Enforce rules for MFA logins

Adding MFA to your app's UI does not in-and-of-itself offer a higher level of security to your users. You also need to enforce the MFA rules in your application's database, APIs, and server-side rendering.

Depending on your application's needs, there are three ways you can choose to enforce MFA.

1.  **Enforce for all users (new and existing).**
    Any user account will have to enroll MFA to continue using your app.
    The application will not allow access without going through MFA first.
2.  **Enforce for new users only.**
    Only new users will be forced to enroll MFA, while old users will be encouraged
    to do so.
    The application will not allow access for new users without going through MFA
    first.
3.  **Enforce only for users that have opted-in.**
    Users that want MFA can enroll in it and the application will not allow access
    without going through MFA first.


#### Example: React

Below is an example that creates a new `UnenrollMFA` component that illustrates the important pieces of the MFA enrollment flow. Note that users can only unenroll a factor after completing the enrollment flow and obtaining an `aal2` JWT claim. Here are some points of note:

*   When the component appears on screen, the `supabase.auth.mfa.listFactors()` endpoint
    fetches all existing factors together with their details.
*   The existing factors for a user are displayed in a table.
*   Once the user has selected a factor to unenroll, they can type in the `factorId` and click **Unenroll**
    which creates a confirmation modal.

```tsx
/**
 * UnenrollMFA shows a simple table with the list of factors together with a button to unenroll.
 * When a user types in the factorId of the factor that they wish to unenroll and clicks unenroll
 * the corresponding factor will be unenrolled.
 */
export function UnenrollMFA() {
  const [factorId, setFactorId] = useState('')
  const [factors, setFactors] = useState([])
  const [error, setError] = useState('') // holds an error message

  useEffect(() => {
    ;(async () => {
      const { data, error } = await supabase.auth.mfa.listFactors()
      if (error) {
        throw error
      }

      setFactors([...data.totp, ...data.phone])
    })()
  }, [])

  return (
    <>
      {error && <div className="error">{error}</div>}
      <tbody>
        <tr>
          <td>Factor ID</td>
          <td>Friendly Name</td>
          <td>Factor Status</td>
          <td>Phone Number</td>
        </tr>
        {factors.map((factor) => (
          <tr>
            <td>{factor.id}</td>
            <td>{factor.friendly_name}</td>
            <td>{factor.factor_type}</td>
            <td>{factor.status}</td>
            <td>{factor.phone}</td>
          </tr>
        ))}
      </tbody>
      <input type="text" value={verifyCode} onChange={(e) => setFactorId(e.target.value.trim())} />
      <button onClick={() => supabase.auth.mfa.unenroll({ factorId })}>Unenroll</button>
    </>
  )
}
```


#### Database

Your app should sufficiently deny or allow access to tables or rows based on the user's current and possible authenticator levels.


##### Enforce for all users (new and existing)

If your app falls under this case, this is a template Row Level Security policy you can apply to all your tables:

```sql
create policy "Policy name."
  on table_name
  as restrictive
  to authenticated
  using ((select auth.jwt()->>'aal') = 'aal2');
```

*   Here the policy will not accept any JWTs with an `aal` claim other than
    `aal2`, which is the highest authenticator assurance level.
*   **Using `as restrictive` ensures this policy will restrict all commands on the
    table regardless of other policies!**


##### Enforce for new users only

If your app falls under this case, the rules get more complex. User accounts created past a certain timestamp must have a `aal2` level to access the database.

```sql
create policy "Policy name."
  on table_name
  as restrictive -- very important!
  to authenticated
  using
    (array[(select auth.jwt()->>'aal')] <@ (
       select
         case
           when created_at >= '2022-12-12T00:00:00Z' then array['aal2']
           else array['aal1', 'aal2']
         end as aal
       from auth.users
       where (select auth.uid()) = id));
```

*   The policy will accept both `aal1` and `aal2` for users with a `created_at`
    timestamp prior to 12th December 2022 at 00:00 UTC, but will only accept
    `aal2` for all other timestamps.
*   The `<@` operator is PostgreSQL's ["contained in"
    operator.](https://www.postgresql.org/docs/current/functions-array.html)
*   **Using `as restrictive` ensures this policy will restrict all commands on the
    table regardless of other policies!**


##### Enforce only for users that have opted-in

Users that have enrolled MFA on their account are expecting that your
application only works for them if they've gone through MFA.

```sql
create policy "Policy name."
  on table_name
  as restrictive -- very important!
  to authenticated
  using (
    array[(select auth.jwt()->>'aal')] <@ (
      select
          case
            when count(id) > 0 then array['aal2']
            else array['aal1', 'aal2']
          end as aal
        from auth.mfa_factors
        where ((select auth.uid()) = user_id) and status = 'verified'
    ));
```

*   The policy will only accept only `aal2` when the user has at least one MFA
    factor verified.
*   Otherwise, it will accept both `aal1` and `aal2`.
*   The `<@` operator is PostgreSQL's ["contained in"
    operator.](https://www.postgresql.org/docs/current/functions-array.html)
*   **Using `as restrictive` ensures this policy will restrict all commands on the
    table regardless of other policies!**


### Server-Side Rendering

It is possible to enforce MFA on the Server-Side Rendering level. However, this can be tricky do to well.

You can use the `supabase.auth.mfa.getAuthenticatorAssuranceLevel()` and `supabase.auth.mfa.listFactors()` APIs to identify the AAL level of the session and any factors that are enabled for a user, similar to how you would use these on the browser.

However, encountering a different AAL level on the server may not actually be a security problem. Consider these likely scenarios:

1.  User signed-in with a conventional method but closed their tab on the MFA
    flow.
2.  User forgot a tab open for a very long time. (This happens more often than
    you might imagine.)
3.  User has lost their authenticator device and is confused about the next
    steps.

We thus recommend you redirect users to a page where they can authenticate using their additional factor, instead of rendering a HTTP 401 Unauthorized or HTTP 403 Forbidden content.


### APIs

If your application uses the Supabase Database, Storage or Edge Functions, just using Row Level Security policies will give you sufficient protection. In the event that you have other APIs that you wish to protect, follow these general guidelines:

1.  **Use a good JWT verification and parsing library for your language.**
    This will let you securely parse JWTs and extract their claims.
2.  **Retrieve the `aal` claim from the JWT and compare its value according to
    your needs.**
    If you've encountered an AAL level that can be increased, ask the user to
    continue the login process instead of logging them out.
3.  **Use the `https://<project-ref>.supabase.co/rest/v1/auth/factors` REST
    endpoint to identify if the user has enrolled any MFA factors.**
    Only `verified` factors should be acted upon.


## Frequently asked questions


# Multi-Factor Authentication (Phone)



## How does phone multi-factor-authentication work?

Phone multi-factor authentication involves a shared code generated by Supabase Auth and the end user. The code is delivered via a messaging channel, such as SMS or WhatsApp, and the user uses the code to authenticate to Supabase Auth.

The phone messaging configuration for MFA is shared with [phone auth login](/docs/guides/auth/phone-login). The same provider configuration that is used for phone login is used for MFA. You can also use the [Send SMS Hook](/docs/guides/auth/auth-hooks/send-sms-hook) if you need to use an MFA (Phone) messaging provider different from what is supported natively.

Below is a flow chart illustrating how the Enrollment and Verify APIs work in the context of MFA (Phone).


### Add enrollment flow

An enrollment flow provides a UI for users to set up additional authentication factors. Most applications add the enrollment flow in two places within their app:

1.  Right after login or sign up.
    This allows users quickly set up Multi Factor Authentication (MFA) post login or account creation. Where possible, encourage all users to set up MFA. Many applications offer this as an opt-in step in an
    effort to reduce onboarding friction.
2.  From within a settings page.
    Allows users to set up, disable or modify their MFA settings.

As far as possible, maintain a generic flow that you can reuse in both cases with minor modifications.

Enrolling a factor for use with MFA takes three steps for phone MFA:

1.  Call `supabase.auth.mfa.enroll()`.
2.  Calling the `supabase.auth.mfa.challenge()` API. This sends a code via SMS or WhatsApp and prepares Supabase Auth to accept a verification code from the user.
3.  Calling the `supabase.auth.mfa.verify()` API. `supabase.auth.mfa.challenge()` returns a challenge ID.
    This verifies that the code issued by Supabase Auth matches the code input by the user. If the verification succeeds, the factor
    immediately becomes active for the user account. If not, you should repeat
    steps 2 and 3.


#### Example: React

Below is an example that creates a new `EnrollMFA` component that illustrates the important pieces of the MFA enrollment flow.

*   When the component appears on screen, the `supabase.auth.mfa.enroll()` API is
    called once to start the process of enrolling a new factor for the current
    user.
*   A challenge is created using the `supabase.auth.mfa.challenge()` API and the
    code from the user is submitted for verification using the
    `supabase.auth.mfa.verify()` challenge.
*   `onEnabled` is a callback that notifies the other components that enrollment
    has completed.
*   `onCancelled` is a callback that notifies the other components that the user
    has clicked the `Cancel` button.

```tsx
export function EnrollMFA({
  onEnrolled,
  onCancelled,
}: {
  onEnrolled: () => void
  onCancelled: () => void
}) {
  const [phoneNumber, setPhoneNumber] = useState('')
  const [factorId, setFactorId] = useState('')
  const [verifyCode, setVerifyCode] = useState('')
  const [error, setError] = useState('')
  const [challengeId, setChallengeId] = useState('')

  const onEnableClicked = () => {
    setError('')
    ;(async () => {
      const verify = await auth.mfa.verify({
        factorId,
        challengeId,
        code: verifyCode,
      })
      if (verify.error) {
        setError(verify.error.message)
        throw verify.error
      }

      onEnrolled()
    })()
  }
  const onEnrollClicked = async () => {
    setError('')
    try {
      const factor = await auth.mfa.enroll({
        phone: phoneNumber,
        factorType: 'phone',
      })
      if (factor.error) {
        setError(factor.error.message)
        throw factor.error
      }

      setFactorId(factor.data.id)
    } catch (error) {
      setError('Failed to Enroll the Factor.')
    }
  }

  const onSendOTPClicked = async () => {
    setError('')
    try {
      const challenge = await auth.mfa.challenge({ factorId })
      if (challenge.error) {
        setError(challenge.error.message)
        throw challenge.error
      }

      setChallengeId(challenge.data.id)
    } catch (error) {
      setError('Failed to resend the code.')
    }
  }

  return (
    <>
      {error && <div className="error">{error}</div>}
      <input
        type="text"
        placeholder="Phone Number"
        value={phoneNumber}
        onChange={(e) => setPhoneNumber(e.target.value.trim())}
      />
      <input
        type="text"
        placeholder="Verification Code"
        value={verifyCode}
        onChange={(e) => setVerifyCode(e.target.value.trim())}
      />
      <input type="button" value="Enroll" onClick={onEnrollClicked} />
      <input type="button" value="Submit Code" onClick={onEnableClicked} />
      <input type="button" value="Send OTP Code" onClick={onSendOTPClicked} />
      <input type="button" value="Cancel" onClick={onCancelled} />
    </>
  )
}
```


### Add a challenge step to login

Once a user has logged in via their first factor (email+password, magic link, one time password, social login etc.) you need to perform a check if any additional factors need to be verified.

This can be done by using the `supabase.auth.mfa.getAuthenticatorAssuranceLevel()` API. When the user signs in and is redirected back to your app, you should call this method to extract the user's current and next authenticator assurance level (AAL).

Therefore if you receive a `currentLevel` which is `aal1` but a `nextLevel` of `aal2`, the user should be given the option to go through MFA.

Below is a table that explains the combined meaning.

| Current Level | Next Level | Meaning                                                  |
| ------------: | :--------- | :------------------------------------------------------- |
|        `aal1` | `aal1`     | User does not have MFA enrolled.                         |
|        `aal1` | `aal2`     | User has an MFA factor enrolled but has not verified it. |
|        `aal2` | `aal2`     | User has verified their MFA factor.                      |
|        `aal2` | `aal1`     | User has disabled their MFA factor. (Stale JWT.)         |


#### Example: React

Adding the challenge step to login depends heavily on the architecture of your app. However, a fairly common way to structure React apps is to have a large component (often named `App`) which contains most of the authenticated application logic.

This example will wrap this component with logic that will show an MFA challenge screen if necessary, before showing the full application. This is illustrated in the `AppWithMFA` example below.

```tsx
function AppWithMFA() {
  const [readyToShow, setReadyToShow] = useState(false)
  const [showMFAScreen, setShowMFAScreen] = useState(false)

  useEffect(() => {
    ;(async () => {
      try {
        const { data, error } = await supabase.auth.mfa.getAuthenticatorAssuranceLevel()
        if (error) {
          throw error
        }

        console.log(data)

        if (data.nextLevel === 'aal2' && data.nextLevel !== data.currentLevel) {
          setShowMFAScreen(true)
        }
      } finally {
        setReadyToShow(true)
      }
    })()
  }, [])

  if (readyToShow) {
    if (showMFAScreen) {
      return <AuthMFA />
    }

    return <App />
  }

  return <></>
}
```

*   `supabase.auth.mfa.getAuthenticatorAssuranceLevel()` does return a promise.
    Don't worry, this is a very fast method (microseconds) as it rarely uses the
    network.
*   `readyToShow` only makes sure the AAL check completes before showing any
    application UI to the user.
*   If the current level can be upgraded to the next one, the MFA screen is
    shown.
*   Once the challenge is successful, the `App` component is finally rendered on
    screen.

Below is the component that implements the challenge and verify logic.

```tsx
function AuthMFA() {
  const [verifyCode, setVerifyCode] = useState('')
  const [error, setError] = useState('')
  const [factorId, setFactorId] = useState('')
  const [challengeId, setChallengeId] = useState('')
  const [phoneNumber, setPhoneNumber] = useState('')

  const startChallenge = async () => {
    setError('')
    try {
      const factors = await supabase.auth.mfa.listFactors()
      if (factors.error) {
        throw factors.error
      }

      const phoneFactor = factors.data.phone[0]

      if (!phoneFactor) {
        throw new Error('No phone factors found!')
      }

      const factorId = phoneFactor.id
      setFactorId(factorId)
      setPhoneNumber(phoneFactor.phone)

      const challenge = await supabase.auth.mfa.challenge({ factorId })
      if (challenge.error) {
        setError(challenge.error.message)
        throw challenge.error
      }

      setChallengeId(challenge.data.id)
    } catch (error) {
      setError(error.message)
    }
  }

  const verifyCode = async () => {
    setError('')
    try {
      const verify = await supabase.auth.mfa.verify({
        factorId,
        challengeId,
        code: verifyCode,
      })
      if (verify.error) {
        setError(verify.error.message)
        throw verify.error
      }
    } catch (error) {
      setError(error.message)
    }
  }

  return (
    <>
      <div>Please enter the code sent to your phone.</div>
      {phoneNumber && <div>Phone number: {phoneNumber}</div>}
      {error && <div className="error">{error}</div>}
      <input
        type="text"
        value={verifyCode}
        onChange={(e) => setVerifyCode(e.target.value.trim())}
      />
      {!challengeId ? (
        <input type="button" value="Start Challenge" onClick={startChallenge} />
      ) : (
        <input type="button" value="Verify Code" onClick={verifyCode} />
      )}
    </>
  )
}
```

*   You can extract the available MFA factors for the user by calling
    `supabase.auth.mfa.listFactors()`. Don't worry this method is also very quick
    and rarely uses the network.
*   If `listFactors()` returns more than one factor (or of a different type) you
    should present the user with a choice. For simplicity this is not shown in
    the example.
*   Phone numbers are unique per user. Users can only have one verified phone factor with a given phone number.
    Attempting to enroll a new phone factor alongside an existing verified factor with the same number will result in an error.
*   Each time the user presses the "Submit" button a new challenge is created for
    the chosen factor (in this case the first one)
*   On successful verification, the client library will refresh the session in
    the background automatically and finally call the `onSuccess` callback, which
    will show the authenticated `App` component on screen.


### Security configuration

Each code is valid for up to 5 minutes, after which a new one can be sent. Successive codes remain valid until expiry. When possible choose the longest code length acceptable to your use case, at a minimum of 6. This can be configured in the [Authentication Settings](/dashboard/project/_/settings/auth).

Be aware that Phone MFA is vulnerable to SIM swap attacks where an attacker will call a mobile provider and ask to port the target's phone number to a new SIM card and then use the said SIM card to intercept an MFA code. Evaluate the your application's tolerance for such an attack. You can read more about SIM swapping attacks [here](https://en.wikipedia.org/wiki/SIM_swap_scam)


## Pricing

For a detailed breakdown of how charges are calculated, refer to [Manage Advanced MFA Phone usage](/docs/guides/platform/manage-your-usage/advanced-mfa-phone).


# Multi-Factor Authentication (TOTP)



## How does app authenticator multi-factor authentication work?

App Authenticator (TOTP) multi-factor authentication involves a timed one-time password generated from an authenticator app in the control of users. It uses a QR Code which to transmit a shared secret used to generate a One Time Password. A user can scan a QR code with their phone to capture a shared secret required for subsequent authentication.

The use of a QR code was [initially introduced by Google Authenticator](https://github.com/google/google-authenticator/wiki/Key-Uri-Format) but is now universally accepted by all authenticator apps. The QR code has an alternate representation in URI form following the `otpauth` scheme such as: `otpauth://totp/supabase:alice@supabase.com?secret=<secret>&issuer=supabase` which a user can manually input in cases where there is difficulty rendering a QR Code.

Below is a flow chart illustrating how the Enrollment, Challenge, and Verify APIs work in the context of MFA (TOTP).

[TOTP MFA API](/docs/reference/javascript/auth-mfa-api) is free to use and is enabled on all Supabase projects by default.


### Add enrollment flow

An enrollment flow provides a UI for users to set up additional authentication factors. Most applications add the enrollment flow in two places within their app:

1.  Right after login or sign up.
    This lets users quickly set up MFA immediately after they log in or create an
    account. We recommend encouraging all users to set up MFA if that makes sense
    for your application. Many applications offer this as an opt-in step in an
    effort to reduce onboarding friction.
2.  From within a settings page.
    Allows users to set up, disable or modify their MFA settings.

Enrolling a factor for use with MFA takes three steps:

1.  Call `supabase.auth.mfa.enroll()`.
    This method returns a QR code and a secret. Display the QR
    code to the user and ask them to scan it with their authenticator application.
    If they are unable to scan the QR code, show the secret in plain text which
    they can type or paste into their authenticator app.
2.  Calling the `supabase.auth.mfa.challenge()` API.
    This prepares Supabase Auth to accept a verification code from the user
    and returns a challenge ID. In the case of Phone MFA this step also sends the verification code to the user.
3.  Calling the `supabase.auth.mfa.verify()` API.
    This verifies that the user has indeed added the secret from step (1) into
    their app and is working correctly. If the verification succeeds, the factor
    immediately becomes active for the user account. If not, you should repeat
    steps 2 and 3.


#### Example: React

Below is an example that creates a new `EnrollMFA` component that illustrates the important pieces of the MFA enrollment flow.

*   When the component appears on screen, the `supabase.auth.mfa.enroll()` API is
    called once to start the process of enrolling a new factor for the current
    user.
*   This API returns a QR code in the SVG format, which is shown on screen using
    a normal `<img>` tag by encoding the SVG as a data URL.
*   Once the user has scanned the QR code with their authenticator app, they
    should enter the verification code within the `verifyCode` input field and
    click on `Enable`.
*   A challenge is created using the `supabase.auth.mfa.challenge()` API and the
    code from the user is submitted for verification using the
    `supabase.auth.mfa.verify()` challenge.
*   `onEnabled` is a callback that notifies the other components that enrollment
    has completed.
*   `onCancelled` is a callback that notifies the other components that the user
    has clicked the `Cancel` button.

```tsx
/**
 * EnrollMFA shows a simple enrollment dialog. When shown on screen it calls
 * the `enroll` API. Each time a user clicks the Enable button it calls the
 * `challenge` and `verify` APIs to check if the code provided by the user is
 * valid.
 * When enrollment is successful, it calls `onEnrolled`. When the user clicks
 * Cancel the `onCancelled` callback is called.
 */
export function EnrollMFA({
  onEnrolled,
  onCancelled,
}: {
  onEnrolled: () => void
  onCancelled: () => void
}) {
  const [factorId, setFactorId] = useState('')
  const [qr, setQR] = useState('') // holds the QR code image SVG
  const [verifyCode, setVerifyCode] = useState('') // contains the code entered by the user
  const [error, setError] = useState('') // holds an error message

  const onEnableClicked = () => {
    setError('')
    ;(async () => {
      const challenge = await supabase.auth.mfa.challenge({ factorId })
      if (challenge.error) {
        setError(challenge.error.message)
        throw challenge.error
      }

      const challengeId = challenge.data.id

      const verify = await supabase.auth.mfa.verify({
        factorId,
        challengeId,
        code: verifyCode,
      })
      if (verify.error) {
        setError(verify.error.message)
        throw verify.error
      }

      onEnrolled()
    })()
  }

  useEffect(() => {
    ;(async () => {
      const { data, error } = await supabase.auth.mfa.enroll({
        factorType: 'totp',
      })
      if (error) {
        throw error
      }

      setFactorId(data.id)

      // Supabase Auth returns an SVG QR code which you can convert into a data
      // URL that you can place in an <img> tag.
      setQR(data.totp.qr_code)
    })()
  }, [])

  return (
    <>
      {error && <div className="error">{error}</div>}
      <img src={qr} />
      <input
        type="text"
        value={verifyCode}
        onChange={(e) => setVerifyCode(e.target.value.trim())}
      />
      <input type="button" value="Enable" onClick={onEnableClicked} />
      <input type="button" value="Cancel" onClick={onCancelled} />
    </>
  )
}
```


### Add a challenge step to login

Once a user has logged in via their first factor (email+password, magic link, one time password, social login etc.) you need to perform a check if any additional factors need to be verified.

This can be done by using the `supabase.auth.mfa.getAuthenticatorAssuranceLevel()` API. When the user signs in and is redirected back to your app, you should call this method to extract the user's current and next authenticator assurance level (AAL).

Therefore if you receive a `currentLevel` which is `aal1` but a `nextLevel` of `aal2`, the user should be given the option to go through MFA.

Below is a table that explains the combined meaning.

| Current Level | Next Level | Meaning                                                  |
| ------------: | :--------- | :------------------------------------------------------- |
|        `aal1` | `aal1`     | User does not have MFA enrolled.                         |
|        `aal1` | `aal2`     | User has an MFA factor enrolled but has not verified it. |
|        `aal2` | `aal2`     | User has verified their MFA factor.                      |
|        `aal2` | `aal1`     | User has disabled their MFA factor. (Stale JWT.)         |


#### Example: React

Adding the challenge step to login depends heavily on the architecture of your app. However, a fairly common way to structure React apps is to have a large component (often named `App`) which contains most of the authenticated application logic.

This example will wrap this component with logic that will show an MFA challenge screen if necessary, before showing the full application. This is illustrated in the `AppWithMFA` example below.

```tsx
function AppWithMFA() {
  const [readyToShow, setReadyToShow] = useState(false)
  const [showMFAScreen, setShowMFAScreen] = useState(false)

  useEffect(() => {
    ;(async () => {
      try {
        const { data, error } = await supabase.auth.mfa.getAuthenticatorAssuranceLevel()
        if (error) {
          throw error
        }

        console.log(data)

        if (data.nextLevel === 'aal2' && data.nextLevel !== data.currentLevel) {
          setShowMFAScreen(true)
        }
      } finally {
        setReadyToShow(true)
      }
    })()
  }, [])

  if (readyToShow) {
    if (showMFAScreen) {
      return <AuthMFA />
    }

    return <App />
  }

  return <></>
}
```

*   `supabase.auth.mfa.getAuthenticatorAssuranceLevel()` does return a promise.
    Don't worry, this is a very fast method (microseconds) as it rarely uses the
    network.
*   `readyToShow` only makes sure the AAL check completes before showing any
    application UI to the user.
*   If the current level can be upgraded to the next one, the MFA screen is
    shown.
*   Once the challenge is successful, the `App` component is finally rendered on
    screen.

Below is the component that implements the challenge and verify logic.

```tsx
function AuthMFA() {
  const [verifyCode, setVerifyCode] = useState('')
  const [error, setError] = useState('')

  const onSubmitClicked = () => {
    setError('')
    ;(async () => {
      const factors = await supabase.auth.mfa.listFactors()
      if (factors.error) {
        throw factors.error
      }

      const totpFactor = factors.data.totp[0]

      if (!totpFactor) {
        throw new Error('No TOTP factors found!')
      }

      const factorId = totpFactor.id

      const challenge = await supabase.auth.mfa.challenge({ factorId })
      if (challenge.error) {
        setError(challenge.error.message)
        throw challenge.error
      }

      const challengeId = challenge.data.id

      const verify = await supabase.auth.mfa.verify({
        factorId,
        challengeId,
        code: verifyCode,
      })
      if (verify.error) {
        setError(verify.error.message)
        throw verify.error
      }
    })()
  }

  return (
    <>
      <div>Please enter the code from your authenticator app.</div>
      {error && <div className="error">{error}</div>}
      <input
        type="text"
        value={verifyCode}
        onChange={(e) => setVerifyCode(e.target.value.trim())}
      />
      <input type="button" value="Submit" onClick={onSubmitClicked} />
    </>
  )
}
```

*   You can extract the available MFA factors for the user by calling
    `supabase.auth.mfa.listFactors()`. Don't worry this method is also very quick
    and rarely uses the network.
*   If `listFactors()` returns more than one factor (or of a different type) you
    should present the user with a choice. For simplicity this is not shown in
    the example.
*   Each time the user presses the "Submit" button a new challenge is created for
    the chosen factor (in this case the first one) and it is immediately
    verified. Any errors are displayed to the user.
*   On successful verification, the client library will refresh the session in
    the background automatically and finally call the `onSuccess` callback, which
    will show the authenticated `App` component on screen.


## Frequently asked questions


# Send emails with custom SMTP



If you're using Supabase Auth with the following configuration:

*   Email and password accounts
*   Passwordless accounts using one-time passwords or links sent over email (OTP, magic link, invites)
*   Email-based user invitations from the [Users page](/dashboard/project/_/auth/users) or from the Auth admin APIs
*   Social login with email confirmation

You will need to set up a custom SMTP server to handle the delivery of messages to your users.

To get you started and let you explore and set up email message templates for your application, Supabase provides a simple SMTP server for all projects. This server imposes a few important restrictions and is not meant for production use.

**Send messages only to pre-authorized addresses.**

Unless you configure a custom SMTP server for your project, Supabase Auth will refuse to deliver messages to addresses that are not part of the project's team. You can manage this in the [Team tab](/dashboard/org/_/team) of the organization's settings.

For example, if your project's organization has these member accounts `person-a@example.com`, `person-b@example.com` and `person-c@example.com` then Supabase Auth will only send messages to these addresses. All other addresses will fail with the error message *Email address not authorized.*

**Significant rate-limits that can change over time.**

To maintain the health and reputation of the default SMTP sending service, the number of messages your project can send is limited and can change without notice. Currently this value is set to  messages per hour.

**No SLA guarantee on message delivery or uptime for the default SMTP service.**

The default SMTP service is provided as best-effort only and intended for the following non-production use cases:

*   Exploring and getting started with Supabase Auth
*   Setting up and testing email templates with the members of the project's team
*   Building toy projects, demos or any non-mission-critical application

We urge all customers to set up custom SMTP server for all other use cases.


## How to set up a custom SMTP server?

Supabase Auth works with any email sending service that supports the SMTP protocol. First you will need to choose a service, create an account (if you already do not have one) and obtain the SMTP server settings and credentials for your account. These include: the SMTP server host, port, user and password. You will also need to choose a default From address, usually something like `no-reply@example.com`.

A non-exhaustive list of services that work with Supabase Auth is:

*   [Resend](https://resend.com/docs/send-with-supabase-smtp)
*   [AWS SES](https://docs.aws.amazon.com/ses/latest/dg/send-email-smtp.html)
*   [Postmark](https://postmarkapp.com/developer/user-guide/send-email-with-smtp)
*   [Twilio SendGrid](https://www.twilio.com/docs/sendgrid/for-developers/sending-email/getting-started-smtp)
*   [ZeptoMail](https://www.zoho.com/zeptomail/help/smtp-home.html)
*   [Brevo](https://help.brevo.com/hc/en-us/articles/7924908994450-Send-transactional-emails-using-Brevo-SMTP)

Once you've set up your account with an email sending service, head to the [Authentication settings page](/dashboard/project/_/settings/auth) to enable and configure custom SMTP.

Once you save these settings, your project's Auth server will send messages to all addresses. To protect the reputation of your newly set up service a low rate-limit of 30 messages per hour is imposed. To adjust this to an acceptable value for your use case head to the [Rate Limits configuration page](/dashboard/project/_/auth/rate-limits).


## Dealing with abuse: How to maintain the sending reputation of your SMTP server?

As you make your application known to the public and it grows in popularity, you can expect to see a few types of abuse that can negatively impact the reputation of your sending domain.

A common source of abuse is bots or attackers signing up users to your application.

They use lists of known email addresses to sign up users to your project with pre-determined passwords. These can vary in scale and intensity: sometimes the bots slowly send sign up requests over many months, or they send a lot of requests at once.

Usually the goal for this behavior is:

*   To negatively affect your email sending reputation, after which they might ask for a ransom promising to stop the behavior.
*   To cause a short-term or even long-term Denial of Service attack on your service, by preventing new account creation, signins with magic links or one-time passwords, or to severely impact important security flows in your application (such as reset password or forgot password).
*   To force you to reduce the security posture of your project, such as by disabling email confirmations. At that point, they may target specific or a broad number of users by creating an account in their name. Then they can use social engineering techniques to trick them to use your application in such a way that both attacker and victim have access to the same account.

Mitigation strategies:

*   [Configure CAPTCHA protection](/docs/guides/auth/auth-captcha) for your project, which is the most effective way to control bots in this scenario. You can use CAPTCHA services which provide invisible challenges where real users won't be asked to solve puzzles most of the time.
*   Prefer social login (OAuth) or SSO with SAML instead of email-based authentication flows in your apps.
*   Prefer passwordless authentication (one-time password) as this limits the attacker's value to gain from this behavior.
*   Do not disable email confirmations under pressure.


### Additional best practices

**Set up and maintain DKIM, DMARC and SPF configurations.**

Work with your email sending service to configure [DKIM, DMARC and SPF](https://www.cloudflare.com/learning/email-security/dmarc-dkim-spf/) for your sending domain. This will significantly increase the deliverability of your messages.

**Set up a custom domain.**

Authentication messages often contain links to your project's Auth server. [Setting up a custom domain](/docs/guides/platform/custom-domains) will reduce the likelihood of your messages being picked up as spam due to another Supabase project's bad reputation.

**Don't mix Auth emails with marketing emails.**

Use separate services for Auth and marketing messages. If the reputation of one falls, it won't affect your whole application or operation.

This includes:

*   Use a separate sending domain for authentication -- `auth.example.com` and a separate domain for marketing `marketing.example.com`.
*   Use a separate From address -- `no-reply@auth.example.com` vs `no-reply@marketing.example.com`.

**Have another SMTP service set up on stand-by.**

In case the primary SMTP service you're using is experiencing difficulty, or your account is under threat of being blocked due to spam, you have another service to quickly turn to.

**Use consistent branding and focused content.**

Make sure you've separated out authentication messages from marketing messages.

*   Don't include promotional content as part of authentication messages.
*   Avoid talking about what your application is inside authentication messages. This can be picked up by automated spam filters which will classify the message as marketing and increase its chances of being regarded as spam. This problem is especially apparent if your project is related to: Web3, Blockchain, AI, NFTs, Gambling, Pornography.
*   Avoid taglines or other short-form marketing material in authentication messages.
*   Reduce the number of links and call-to-actions in authentication messages.
*   Change the authentication messages templates infrequently. Prefer a single big change over multiple smaller changes.
*   Avoid A/B testing content in authentication messages.
*   Use a separate base template (HTML) from your marketing messages.
*   Avoid the use of email signatures in authentication messages. If you do, make sure the signatures are different in style and content from your marketing messages.
*   Use short and to-the-point subject lines. Avoid or reduce the number of emojis in subjects.
*   Reduce the number of images placed in authentication messages.
*   Avoid including user-provided data such as names, usernames, email addresses or salutations in authentication messages. If you do, make sure they are sanitized.

**Prepare for large surges ahead of time.**

If you are planning on having a large surge of users coming at a specific time, work with your email sending service to adjust the rate limits and their expectations accordingly. Most email sending services dislike spikes in the number of messages being sent, and this may affect your sending reputation.

Consider implementing additional protections for such events:

*   Build a queuing or waitlist system instead of allowing direct sign-up, which will help you control the number of messages being sent from the email sending service.
*   Disable email-based sign ups for the event and use social login only. Alternatively you can deprioritize the email-based sign-up flows for the event by hiding them in the UI or making them harder to reach.

**Use the Send Email Auth Hook for more control.**

If you need more control over the sending process, instead of using a SMTP server you can use the [Send Email Auth Hook](/docs/guides/auth/auth-hooks/send-email-hook). This can be useful in advanced scenarios such as:

*   You want to use React or a different email templating engine.
*   You want to use an email sending service that does not provide an SMTP service, or the non-SMTP API is more powerful.
*   You want to queue up messages instead of sending them immediately, in an effort to smooth out spikes in email sending or do additional filtering (avoid repetitive messages).
*   You want to use multiple email sending services to increase reliability (if primary service is unavailable, use backup service automatically).
*   You want to use different email sending services based on the email address or user data (e.g. service A for users in the USA, service B for users in the EU, service C for users in China).
*   You want to add or include additional email headers in messages, for tracking or other reasons.
*   You want to add attachments to the messages (generally not recommended).
*   You want to add [S/MIME signatures](https://en.wikipedia.org/wiki/S/MIME) to messages.
*   You want to use an email server not open to the Internet, such as some corporate or government mail servers.

**Increase the duration of user sessions.**

Having short lived [user sessions](/docs/guides/auth/sessions) can be problematic for email sending, as it forces active users to sign-in frequently, increasing the number of messages needed to be sent. Consider increasing the maximum duration of user sessions. If you do see an unnecessary increase in logins without a clear cause, check your frontend application for bugs.

If you are using a [SSR](/docs/guides/auth/server-side) framework on the frontend and are seeing an increased number of user logins without a clear cause, check your set up. Make sure to keep the `@supabase/ssr` package up to date and closely follow the guides we publish. Make sure that the middleware components of your SSR frontend works as intended and matches the guides we've published. Sometimes a misplaced `return` or conditional can cause early session termination.


# Error Codes

Learn about the Auth error codes and how to resolve them

## Auth error codes

Supabase Auth can return various errors when using its API. This guide explains how to handle these errors effectively across different programming languages.


## Error types

Supabase Auth errors are generally categorized into two main types:

*   API Errors: Originate from the Supabase Auth API.
*   Client Errors: Originate from the client library's state.

Client errors differ by language so do refer to the appropriate section below:


## HTTP status codes

Below are the most common HTTP status codes you might encounter, along with their meanings in the context of Supabase Auth:


### [403 Forbidden](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403)

Sent out in rare situations where a certain Auth feature is not available for the user, and you as the developer are not checking a precondition whether that API is available for the user.


### [422 Unprocessable Entity](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422)

Sent out when the API request is accepted, but cannot be processed because the user or Auth server is in a state where it cannot satisfy the request.


### [429 Too Many Requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429)

Sent out when rate-limits are breached for an API. You should handle this status code often, especially in functions that authenticate a user.


### [500 Internal Server Error](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500)

Indicate that the Auth server's service is degraded. Most often it points to issues in your database setup such as a misbehaving trigger on a schema, function, view or other database object.


### [501 Not Implemented](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/501)

Sent out when a feature is not enabled on the Auth server, and you are trying to use an API which requires it.


## Auth error codes table

The following table provides a comprehensive list of error codes you may encounter when working with Supabase Auth. Each error code is associated with a specific issue and includes a description to help you understand and resolve the problem efficiently.


## Best practices for error handling

*   Always use `error.code` and `error.name` to identify errors, not string matching on error messages.
*   Avoid relying solely on HTTP status codes, as they may change unexpectedly.


# Enterprise Single Sign-On



Supabase Auth supports building enterprise applications that require Single Sign-On (SSO) authentication [with SAML 2.0](/docs/guides/auth/sso/auth-sso-saml).


# Single Sign-On with SAML 2.0 for Projects



Supabase Auth supports enterprise-level Single Sign-On (SSO) for any identity providers compatible with the SAML 2.0 protocol. This is a non-exclusive list of supported identity providers:

*   Google Workspaces (formerly known as G Suite)
*   Okta, Auth0
*   Microsoft Active Directory, Azure Active Directory, Microsoft Entra
*   PingIdentity
*   OneLogin

If you're having issues with identity provider software not on this list, [open a support ticket](https://supabase.com/dashboard/support/new).


## Prerequisites

This guide requires the use of the [Supabase CLI](/docs/guides/cli). Make sure you're using version v1.46.4 or higher. You can use `supabase -v` to see the currently installed version.
You can use the `supabase sso` [subcommands](/docs/reference/cli/supabase-sso) to manage your project's configuration.

SAML 2.0 support is disabled by default on Supabase projects. You can configure this on the [Auth Providers](https://supabase.com/dashboard/project/_/auth/providers) page on your project.

Note that SAML 2.0 support is offered on plans Pro and above. Check the [Pricing](https://supabase.com/pricing) page for more information.


## Terminology

The number of SAML and SSO acronyms can often be overwhelming. Here's a glossary which you can refer back to at any time:

*   **Identity Provider**, **IdP**, or **IDP**
    An identity provider is a service that manages user accounts at a company or organization. It can verify the identity of a user and exchange that information with your Supabase project and other applications. It acts as a single source of truth for user identities and access rights. Commonly used identity providers are: Microsoft Active Directory (Azure AD, Microsoft Entra), Okta, Google Workspaces (G Suite), PingIdentity, OneLogin, and many others. There are also self-hosted and on-prem versions of identity providers, and sometimes they are accessible only by having access to a company VPN or being in a specific building.
*   **Service Provider**, **SP**
    This is the software that is asking for user information from an identity provider. In Supabase, this is your project's Auth server.
*   **Assertion**
    An assertion is a statement issued by an identity provider that contains information about a user.
*   **`EntityID`**
    A globally unique ID (usually a URL) that identifies an Identity Provider or Service Provider across the world.
*   **`NameID`**
    A unique ID (usually an email address) that identifies a user at an Identity Provider.
*   **Metadata**
    An XML document that describes the features and configuration of an Identity Provider or Service Provider. It can be as a standalone document or as a URL. Usually (but not always) the `EntityID` is the URL at which you can access the Metadata.
*   **Certificate**
    Supabase Auth (the Service Provider) trusts assertions from an Identity Provider based on the signature attached to the assertion. The signature is verified according to the certificate present in the Metadata.
*   **Assertion Consumer Service (ACS) URL**
    This is one of the most important SAML URLs. It is the URL where Supabase Auth will accept assertions from an identity provider. Basically, once the identity provider verifies the user's identity it will redirect to this URL and the redirect request will contain the assertion.
*   **Binding (Redirect, POST, or Artifact)**
    This is a description of the way an identity provider communicates with Supabase Auth. When using the Redirect binding, the communication occurs using HTTP 301 redirects. When it's `POST`, it's using `POST` requests sent with `<form>` elements on a page. When using Artifact, it's using a more secure exchange over a Redirect or `POST`.
*   **`RelayState`**
    State used by Supabase Auth to hold information about a request to verify the identity of a user.


## Important SAML 2.0 information

Below is information about your project's SAML 2.0 configuration which you can share with the company or organization that you're trying to on-board.

| Name                        | Value                                                                   |
| --------------------------- | ----------------------------------------------------------------------- |
| `EntityID`                  | `https://<project>.supabase.co/auth/v1/sso/saml/metadata`               |
| Metadata URL                | `https://<project>.supabase.co/auth/v1/sso/saml/metadata`               |
| Metadata URL(download) | `https://<project>.supabase.co/auth/v1/sso/saml/metadata?download=true` |
| ACS URL                     | `https://<project>.supabase.co/auth/v1/sso/saml/acs`                    |
| SLO URL                     | `https://<project>.supabase.co/auth/v1/sso/slo`                         |
| `NameID`                    | Required `emailAddress` or `persistent`                                 |

Note that SLO (Single Logout) is not supported at this time with Supabase Auth as it is a rarely supported feature by identity providers. However, the URL is registered and advertised for when this does become available. SLO is a best-effort service, so we recommend considering [Session Timebox or Session Inactivity Timeout](/docs/guides/auth/sessions#limiting-session-lifetime-and-number-of-allowed-sessions-per-user) instead to force your end-users to authenticate regularly.

Append `?download=true` to the Metadata URL to download the Metadata XML file. This is useful in cases where the identity provider requires a file.

Alternatively, you can use the `supabase sso info --project-ref <your-project>` [command](/docs/reference/cli/supabase-sso-info) to get setup information for your project.


### User accounts and identities

User accounts and identities created via SSO differ from regular (email, phone, password, social login...) accounts in these ways:

*   **No automatic linking.**
    Each user account verified using a SSO identity provider will not be automatically linked to existing user accounts in the system. That is, if a user `valid.email@supabase.io` had signed up with a password, and then uses their company SSO login with your project, there will be two `valid.email@supabase.io` user accounts in the system.
*   **Emails are not necessarily unique.**
    Given the behavior with no automatic linking, email addresses are no longer a unique identifier for a user account. Always use the user's UUID to correctly reference user accounts.
*   **Sessions may have a maximum duration.**
    Depending on the configuration of the identity provider, a login session established with SSO may forcibly log out a user after a certain period of time.


### Row Level Security

You can use information about the SSO identity provider in Row Level Security policies.

Here are some commonly used statements to extract SSO related information from the user's JWT:

*   `auth.jwt()#>>'{amr,0,method}'`
    Returns the name of the last method used to verify the identity of this user. With SAML SSO this is `sso/saml`.
*   `auth.jwt()#>>'{amr,0,provider}'`
    Returns the UUID of the SSO identity provider used by the user to sign-in.
*   `auth.jwt()#>>'{user_metadata,iss}'`
    Returns the identity provider's SAML 2.0 `EntityID`

A common use case with SSO is to use the UUID of the identity provider as the identifier for the organization the user belongs to -- frequently known as a tenant. By associating the identity provider's UUID with your tenants, you can use restrictive RLS policies to scope down actions and data that a user is able to access.

For example, let's say you have a table like:

```sql
create table organization_settings (
  -- the organization's unique ID
  id uuid not null primary key,
  -- the organization's SSO identity provider
  sso_provider_id uuid unique,
  -- name of the organization
  name text,
  -- billing plan (paid, Free, Enterprise)
  billing_plan text
);
```

You can use the information present in the user's JWT to scope down which rows from this table the user can see, without doing any additional user management:

```sql
CREATE POLICY "View organization settings."
  ON organization_settings
  AS RESTRICTIVE
  USING (
    sso_provider_id = (select auth.jwt()#>>'{amr,0,provider}')
  );
```


## Managing SAML 2.0 connections

Once you've enabled SAML 2.0 support on your project via the [Auth Providers](https://supabase.com/dashboard/project/_/auth/providers) page in the dashboard, you can use the [Supabase CLI](/docs/reference/cli/supabase-sso) to add, update, remove and view information about identity providers.


### Add a connection

To establish a connection to a SAML 2.0 Identity Provider (IdP) you will need:

*   A SAML 2.0 Metadata XML file, or a SAML 2.0 Metadata URL pointing to an XML file
*   (Optional) Email domains that the organization's IdP uses
*   (Optional) Attribute mappings between the user properties of the IdP and the claims stored by Supabase Auth

You should obtain the SAML 2.0 Metadata XML file or URL from the organization whose IdP you wish to connect. Most SAML 2.0 Identity Providers support the Metadata URL standard, and we recommend using a URL if this is available.

Commonly used SAML 2.0 Identity Providers that support Metadata URLs:

*   Okta
*   Azure AD (Microsoft Entra)
*   PingIdentity

Commonly used SAML 2.0 Identity Providers that only support Metadata XML files:

*   Google Workspaces (G Suite)
*   Any self-hosted or on-prem identity provider behind a VPN

Once you've obtained the SAML 2.0 Metadata XML file or URL you can [establish a connection](/docs/reference/cli/supabase-sso-add) with your project's Supabase Auth server by running:

```bash
supabase sso add --type saml --project-ref <your-project> \
  --metadata-url 'https://company.com/idp/saml/metadata' \
  --domains company.com
```

If you wish to use a Metadata XML file instead, you can use:

```bash
supabase sso add --type saml --project-ref <your-project> \
  --metadata-file /path/to/saml/metadata.xml \
  --domains company.com
```

This command will register a new identity provider with your project's Auth server. When successful, you will see the details of the provider such as it's SAML information and registered domains.

Note that only persons with write access to the project can register, update or remove identity providers.

Once you've added an identity provider, users who have access to it can sign in to your application. With SAML 2.0 there are two ways that users can sign in to your project:

*   By signing-in from your application's user interface, commonly known as **SP (Service Provider) Initiated Flow**
*   By clicking on an icon in the application menu on the company intranet or identity provider page, commonly known as **Identity Provider Initiated (IdP) Flow**

To initiate a sign-in request from your application's user interface (i.e. the SP Initiated Flow), you can use:


### Understanding attribute mappings

When a user signs in using the SAML 2.0 Single Sign-On protocol, an XML document called the SAML Assertion is exchanged between the identity provider and Supabase Auth.

This assertion contains information about the user's identity and other authentication information, such as:

*   Unique ID of the user (called `NameID` in SAML)
*   Email address
*   Name of the user
*   Department or organization
*   Other attributes present in the users directory managed by the identity provider

With exception of the unique user ID, SAML does not require any other attributes in the assertion. Identity providers can be configured so that only select user information is shared with your project.

Your project can be configured to recognize these attributes and map them into your project's database using a JSON structure. This process is called attribute mapping, and varies according to the configuration of the identity provider.

For example, the following JSON structure configures attribute mapping for the `email` and `first_name` user identity properties.

```json
{
  "keys": {
    "email": {
      "name": "mail"
    },
    "first_name": {
      "name": "givenName"
    }
  }
}
```

When creating or updating an identity provider with the [Supabase CLI](/docs/guides/cli) you can include this JSON as a file with the `--attribute-mapping-file /path/to/attribute/mapping.json` flag.

For example, to change the attribute mappings to an existing provider you can use:

```bash
supabase sso update <provider-uuid> --project-ref <your-project> \
  --attribute-mapping-file /path/to/attribute/mapping.json
```

Given a SAML 2.0 assertion that includes these attributes:

```xml
<saml:AttributeStatement>
  <!-- will be mapped to the email key -->
  <saml:Attribute
    Name="mail"
    NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"
    >
    <saml:AttributeValue xsi:type="xs:string">
      valid.email@supabase.io
    </saml:AttributeValue>
  </saml:Attribute>

  <!-- will be mapped to the first_name key -->
  <saml:Attribute
    Name="givenName"
    NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"
    >
    <saml:AttributeValue xsi:type="xs:string">
      Jane Doe
    </saml:AttributeValue>
  </saml:Attribute>
</saml:AttributeStatement>
```

Will result in the following claims in the user's identity in the database and JWT:

```json
{
  "email": "valid.email@supabase.io",
  "custom_claims": {
    "first_name": "Jane Doe"
  }
}
```

Supabase Auth does not require specifying attribute mappings if you only need access to the user's email. It will attempt to find an email attribute specified in the assertion. All other properties will not be automatically included, and it is those you need to map.

At this time it is not possible to have users without an email address, so SAML assertions without one will be rejected.

Most SAML 2.0 identity providers use Lightweight Directory Access Protocol (LDAP) attribute names. However, due to their variability and complexity operators of identity providers are able to customize both the `Name` and attribute value that is sent to Supabase Auth in an assertion. Refer to the identity provider's documentation and contact the operator for details on what attributes are mapped for your project.

**Accessing the stored attributes**

The stored attributes, once mapped, show up in the access token (a JWT) of the user. If you need to look these values up in the database, you can find them in the `auth.identities` table under the `identity_data` JSON column. Identities created for SSO providers have `sso:<uuid-of-provider>` in the `provider` column, while `id` contains the unique `NameID` of the user account.

Furthermore, you can find the same identity data under `raw_app_meta_data` inside `auth.users`.


### Remove a connection

Once a connection to an identity provider is established, you can [remove it](/docs/reference/cli/supabase-sso-remove) by running:

```bash
supabase sso remove <provider-id> --project-ref <your-project>
```

If successful, the details of the removed identity provider will be shown. All user accounts from that identity provider will be immediately logged out. User information will remain in the system, but it will no longer be possible for any of those accounts to be accessed in the future, even if you add the connection again.

If you need to reassign those user accounts to another identity provider, [open a support ticket](https://supabase.com/dashboard/support/new).
A [list of all](/docs/reference/cli/supabase-sso-list) registered identity providers can be displayed by running:

```bash
supabase sso list --project-ref <your-project>
```


### Update a connection

You may wish to update settings about a connection to a SAML 2.0 identity provider.

Commonly this is necessary when:

*   Cryptographic keys are rotated or have expired
*   Metadata URL has changed, but is the same identity provider
*   Other SAML 2.0 Metadata attributes have changed, but it is still the same identity provider
*   You are updating the domains or attribute mapping

You can use this command to [update](/docs/reference/cli/supabase-sso-update) the configuration of an identity provider:

```bash
supabase sso update <provider-id> --project-ref <your-project>
```

Use `--help` to see all available flags.

It is not possible to change the unique SAML identifier of the identity provider, known as `EntityID`. Everything else can be updated. If the SAML `EntityID` of your identity provider has changed, it is regarded as a new identity provider and you will have to register it like a new connection.


### Retrieving information about a connection

You can always obtain a [list](/docs/reference/cli/supabase-sso-list) of all registered providers using:

```bash
supabase sso list --project-ref <your-project>
```

This list will only include basic information about each provider. To see [all of the information](/docs/reference/cli/supabase-sso-show) about a provider you can use:

```bash
supabase sso show <provider-id> --project-ref <your-project>
```

You can use the `-o json` flag to output the information as JSON, should you need to. Other formats may be supported, use `--help` to see all available options.


## Pricing

For a detailed breakdown of how charges are calculated, refer to [Manage Monthly Active SSO Users usage](/docs/guides/platform/manage-your-usage/monthly-active-users-sso).


## Frequently asked questions


### Publishing your application to an identity provider's marketplace

Many cloud-based identity providers offer a marketplace where you can register your application for easy on-boarding with customers. When you use Supabase Auth's SAML 2.0 support you can register your project in any one of these marketplaces.

Refer to the relevant documentation for each cloud-based identity provider on how you can do this. Some common marketplaces are:

*   [Okta Integration Network](https://developer.okta.com/docs/guides/build-sso-integration/saml2/main/)
*   [Azure Active Directory App Gallery](https://learn.microsoft.com/en-us/azure/active-directory-b2c/publish-app-to-azure-ad-app-gallery)
*   [Google Workspaces Pre-integrated SAML apps catalog](https://support.google.com/a/table/9217027)


### Why do some users get: SAML assertion does not contain email address?

Identity providers do not have to send back and email address for the user, though they often do. Supabase Auth requires that an email address is present.

The following list of commonly used SAML attribute names is inspected, in order of appearance, to discover the email address in the assertion:

*   `urn:oid:0.9.2342.19200300.100.1.3`
*   `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`
*   `http://schemas.xmlsoap.org/claims/EmailAddress`
*   `mail`
*   `email`

Finally if there is no such attribute, it will use the SAML `NameID` value but only if the format is advertised as `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`.

Should you run into this problem, it is most likely a misconfiguration issue **on the identity provider side.** Instruct your contact at the company to map the user's email address to one of the above listed attribute names, typically `email`.


### Accessing the private key used for SAML in your project

At this time it is not possible to extract the RSA private key used by your project's Supabase Auth server. This is done to keep the private key as secure as possible, given that SAML does not offer an easy way to rotate keys without disrupting service. (Use a SAML 2.0 Metadata URL whenever possible for this reason!)

If you really need access to the key, [open a support ticket](https://supabase.com/dashboard/support/new) and we'll try to support you as best as possible.


### Is multi-tenant SSO with SAML supported?

Yes, Supabase supports multi-tenant Single Sign-On (SSO) using SAML 2.0. While the dashboard displays only one SAML field, you can set up multiple SAML connections using the Supabase CLI.
Each connection is assigned a unique `sso_provider_id`, which is included in the user's JWT and can be used in Row Level Security (RLS) policies. You can configure custom attribute mappings for each connection to include tenant-specific information, such as roles.
This setup allows you to implement multi-tenant SSO for multiple clients or organizations within a single application. For example, if you have an app with multiple clients using different Azure Active Directories, you can create separate SAML connections for each and use the `sso_provider_id` to manage access and apply appropriate security policies.


### Is multi-subdomain SSO with SAML supported?

Yes, also referred to as [cross-origin authentication within the same site](https://web.dev/articles/same-site-same-origin). To redirect to a URL other than the [Site URL](https://supabase.com/docs/guides/auth/redirect-urls), following the SAML response from the IdP, the `redirectTo` option can be added to [`signInWithSSO`](https://supabase.com/docs/reference/javascript/auth-signinwithsso).

```ts
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('https://your-project.supabase.co', 'your-anon-key')

// ---cut---
const { data, error } = await supabase.auth.signInWithSSO({
  domain: 'company.com',
  options: {
    redirectTo: `https://app.company.com/callback`,
  },
})
```

When redirecting to a URL other than the Site URL, a `/callback` endpoint is necessary to process the auth code from the IdP and exchange it for a session. This assumes the [Supabase SSR client](https://supabase.com/docs/guides/auth/server-side/creating-a-client) has already been configured.


# General configuration

General configuration options for Supabase Auth

This section covers the [general configuration options](/dashboard/project/_/settings/auth) for Supabase Auth. If you are looking for another type of configuration, you may be interested in one of the following sections:

*   [Provider-specific configuration](/dashboard/project/_/auth/providers)
*   [Rate limits](/dashboard/project/_/auth/rate-limits)
*   [Email Templates](/dashboard/project/_/auth/templates)
*   [Redirect URLs](/dashboard/project/_/auth/url-configuration)
*   [Auth Hooks](/dashboard/project/_/auth/hooks)

Supabase Auth provides these [general configuration options](/dashboard/project/_/settings/auth) to control user access to your application:

*   **Allow new users to sign up**: Users will be able to sign up. If this config is disabled, only existing users can sign in.

*   **Confirm Email**: Users will need to confirm their email address before signing in for the first time.

    *   Having **Confirm Email** disabled assumes that the user's email does not need to be verified in order to login and implicitly confirms the user's email in the database.
    *   This option can be found in the email provider under the provider-specific configuration.

*   **Allow anonymous sign-ins**: Allow anonymous users to be created.

*   **Allow manual linking**: Allow users to link their accounts manually.


# Identities



An identity is an authentication method associated with a user. Supabase Auth supports the following types of identity:

*   Email
*   Phone
*   OAuth
*   SAML

A user can have more than one identity. Anonymous users have no identity until they link an identity to their user.


## The user identity object

The user identity object contains the following attributes:

| Attributes      | Type     | Description                                                                                                                                                                                                                              |
| --------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| provider\_id     | `string` | The provider id returned by the provider. If the provider is an OAuth provider, the id refers to the user's account with the OAuth provider. If the provider is `email` or `phone`, the id is the user's id from the `auth.users` table. |
| user\_id         | `string` | The user's id that the identity is linked to.                                                                                                                                                                                            |
| identity\_data   | `object` | The identity metadata. For OAuth and SAML identities, this contains information about the user from the provider.                                                                                                                        |
| id              | `string` | The unique id of the identity.                                                                                                                                                                                                           |
| provider        | `string` | The provider name.                                                                                                                                                                                                                       |
| email           | `string` | The email is a generated column that references the optional email property in the identity\_data                                                                                                                                         |
| created\_at      | `string` | The timestamp that the identity was created.                                                                                                                                                                                             |
| last\_sign\_in\_at | `string` | The timestamp that the identity was last used to sign in.                                                                                                                                                                                |
| updated\_at      | `string` | The timestamp that the identity was last updated.                                                                                                                                                                                        |


# JWTs

JSON Web Tokens

A [JSON Web Token](https://jwt.io/introduction) is a type of data structure, represented as a string, that usually contains identity and authorization information about a user. It encodes information about its lifetime and is signed with a cryptographic key to make it tamper-resistant.

Supabase Access Tokens are JWTs. The JWT is sent along with every request to Supabase services. By verifying the token and inspecting the included claims, you can allow or deny access to resources. [Row Level Security](/docs/guides/database/postgres/row-level-security) policies are based on the information present in JWTs.


## Encoding and signing JWTs

JWTs are encoded and signed as follows.

The JSON object starts out looking something like this:

```js
{
  "sub": "0001",
  "name": "Sam Vimes",
  "iat": 1516239022,
  "exp": 1518239022
}
```

`sub` is the "subject", which is usually the UUID of the user. `name` is self-explanatory, and `iat` is the Unix timestamp at which the token was created. Many JWTs will also have an `exp`, which is the date at which the token is set to expire and can no longer be used. These are some of the standard fields you may find in a JWT, but you can pretty much store whatever you want in there, for example:

```js
{
  "sub": "0002",
  "name": "Věra Hrabánková",
  "iat": 1516239022,
  "exp": 1518239022,
  "theme": {
      "primary" : "#D80C14",
      "secondary" : "#FFFFFF"
  }
}
```

Just note that the more data you store in your token, the longer the encoded string will be.

When we want to send the JWT to the user, we first encode the data using an algorithm such as `HS256`. There are many libraries (and several different algorithms) that can be used to do this encoding/decoding, such as [`jsonwebtoken`](https://www.npmjs.com/package/jsonwebtoken). The signing is as simple as:

```js
// from https://replit.com/@awalias/jsonwebtokens#index.js
let token = jwt.sign({ name: 'Sam Vimes' }, 'some-secret')
```

And the resulting string will look like this:

```js
eyJhbGciOiJIUzI1NiJ9
  .eyJzdWIiOiIwMDAxIiwibmFtZSI6IlNhbSBWaW1lcyIsImlhdCI6MTUxNjIzOTAyMiwiZXhwIjoxNTE4MjM5MDIyfQ
  .zMcHjKlkGhuVsiPIkyAkB2rjXzyzJsMMgpvEGvGtjvA
```

You will notice that the string is actually made up of three components:

The first segment `eyJhbGciOiJIUzI1NiJ9` is known as the "header", and when decoded just tells us which algorithm was used to do the encoding:

```js
{
  "alg": "HS256"
}
```

The second segment  contains our original payload:

```js
{
  "sub": "0001",
  "name": "Sam Vimes",
  "iat": 1516239022,
  "exp": 1518239022
}
```

The last segment `zMcHjKlkGhuVsiPIkyAkB2rjXzyzJsMMgpvEGvGtjvA` is the signature itself, which is the part used by the website or service provider to verify that a token sent by some user is legitimate. It is produced in the first instance by running the cryptographic function HS256 on the following input:

```js
HMACSHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload)
  <jwt_secret>
)
```

You can test out minting your own tokens on <https://jwt.io>.

It is important to note that anyone who possesses the `jwt_secret` here can create new tokens, and also verify existing ones. More advanced JWT algorithms use two secrets: one for the creation of tokens, and a separate one to verify the validity of signed tokens.

You might wonder why JWTs are so popular all of a sudden. The answer is that with the mass adoption of microservice architecture, we were in a situation where several distinct microservices (APIs, websites, servers, etc.) want to validate that a user is who they say they are, or are in other words a "logged-in" user. Traditional session tokens are no use here, since they would require each microservice to either maintain a record of currently valid session tokens or to query a central database each time a user wants to access a resource in order to check the validity of the session token – very inefficient indeed. JWT-based auth in this sense is decentralized, since anyone with the `jwt_secret` can verify a token without needing access to a centralized database.

Note: One downside of JWTs is that they are not easily voidable, unlike session tokens. If a JWT is leaked to a malicious actor, they will be able to redeem it anywhere until the expiry date is reached – unless of course the system owner updates the `jwt_secret` (which will of course invalidate *everyone's* existing tokens).


## JWTs in Supabase

In Supabase we issue JWTs for three different purposes:

1.  `anon key`: This key is used to bypass the Supabase API gateway and can be used in your client-side code.
2.  `service role key`: This key has super admin rights and can bypass your Row Level Security. Do not put it in your client-side code. Keep it private.
3.  `user specific jwts`: These are tokens we issue to users who log into your project/service/website. It's the modern equivalent of a session token, and can be used by a user to access content or permissions specific to them.

The first token here, the `anon key` token, is for developers to send along with their API requests whenever they want to interact with their Supabase database.

Let's say you want to read the names of all the rows in a table `colors`. We would make a request like:

```bash
curl 'https://xscduanzzfseqszwzhcy.supabase.co/rest/v1/colors?select=name' \
-H "apikey: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiYW5vbiIsImlhdCI6MTYxNDIwNTE3NCwiZXhwIjoxOTI5NzgxMTc0fQ.-NBR1WnZyQGpRLdXJfgfpszoZ0EeE6KHatJsDPLIX8c"
```

If we put this token into https://jwt.io, we see it decodes to:

```js
{
  "role": "anon",
  "iss": "supabase",
  "iat": 1614205174,
  "exp": 1929781174
}
```

This JWT is signed by a `jwt_secret` specific to the developer's Supabase token (you can find this secret alongside this encoded "anon key" on your Dashboard under Settings > API page) and is required to get past the Supabase API gateway and access the developer's project.

The idea with this particular key is that it's safe to put into your client, meaning it's okay if your end users see this key – but *only* if you first enable Row Level Security.

The second key, `service role key`, should only ever be used on one of your own servers or environments, and should never be shared with end users. You might use this token to do things like make batch inserts of data.

The `user access token` is the JWT issued when you call for example:

```js
supabase.auth.signIn({
  email: 'valid.email@supabase.io',
  password: 'They_Live_1988!',
})
```

This token should be passed in addition to the `apikey` header as an `Authorization Bearer` header like:

```bash
curl 'https://xscduanzzfseqszwzhcy.supabase.co/rest/v1/colors?select=name' \
-H "apikey: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiYW5vbiIsImlhdCI6MTYxNDIwNTE3NCwiZXhwIjoxOTI5NzgxMTc0fQ.-NBR1WnZyQGpRLdXJfgfpszoZ0EeE6KHatJsDPLIX8c" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJhdXRoZW50aWNhdGVkIiwiZXhwIjoxNjE1ODI0Mzg4LCJzdWIiOiIwMzM0NzQ0YS1mMmEyLTRhYmEtOGM4YS02ZTc0OGY2MmExNzIiLCJlbWFpbCI6InNvbWVvbmVAZW1haWwuY29tIiwiYXBwX21ldGFkYXRhIjp7InByb3ZpZGVyIjoiZW1haWwifSwidXNlcl9tZXRhZGF0YSI6bnVsbCwicm9sZSI6ImF1dGhlbnRpY2F0ZWQifQ.I-_oSsJamtinGxniPETBf-ezAUwDW2sY9bJIThvdX9s"
```

You'll notice that this token is quite a bit longer, since it contains information specific to the user such as:

```js
{
  "aud": "authenticated",
  "exp": 1615824388,
  "sub": "0334744a-f2a2-4aba-8c8a-6e748f62a172",
  "email": "valid.email@supabase.io",
  "app_metadata": {
    "provider": "email"
  },
  "user_metadata": null,
  "role": "authenticated"
}
```

If using the service role key, you'll need to pass it into both the `apikey` and `authorization` headers (again, only do this from a secure environment such as your own server):

```bash
curl "$YOUR_PROJECT_URL/rest/v1/colors?select=name" \
 -H "apikey: $YOUR_SERVICE_ROLE_KEY" \
 -H "authorization: Bearer $YOUR_SERVICE_ROLE_KEY"
```

Now that you understand what JWTs are and where they're used in Supabase, you can explore how to use them in combination with Row Level Security to start restricting access to certain tables, rows, and columns in your Postgres database.


## Resources

*   JWT debugger: https://jwt.io/


# User Management

View, delete, and export user information.

You can view your users on the [Users page](/dashboard/project/_/auth/users) of the Dashboard. You can also view the contents of the Auth schema in the [Table Editor](/dashboard/project/_/editor).


## Accessing user data via API

For security, the Auth schema is not exposed in the auto-generated API. If you want to access users data via the API, you can create your own user tables in the `public` schema.

Make sure to protect the table by enabling [Row Level Security](/docs/guides/database/postgres/row-level-security). Reference the `auth.users` table to ensure data integrity. Specify `on delete cascade` in the reference. For example, a `public.profiles` table might look like this:

```sql
create table public.profiles (
  id uuid not null references auth.users on delete cascade,
  first_name text,
  last_name text,

  primary key (id)
);

alter table public.profiles enable row level security;
```

To update your `public.profiles` table every time a user signs up, set up a trigger. If the trigger fails, it could block signups, so test your code thoroughly.

```sql
-- inserts a row into public.profiles
create function public.handle_new_user()
returns trigger
language plpgsql
security definer set search_path = ''
as $$
begin
  insert into public.profiles (id, first_name, last_name)
  values (new.id, new.raw_user_meta_data ->> 'first_name', new.raw_user_meta_data ->> 'last_name');
  return new;
end;
$$;

-- trigger the function every time a user is created
create trigger on_auth_user_created
  after insert on auth.users
  for each row execute procedure public.handle_new_user();
```


## Adding and retrieving user metadata

You can assign metadata to users on sign up:

User metadata is stored on the `raw_user_meta_data` column of the `auth.users` table. To view the metadata:


## Deleting users

You may delete users directly or via the management console at Authentication > Users. Note that deleting a user from the `auth.users` table does not automatically sign out a user. As Supabase makes use of JSON Web Tokens (JWT), a user's JWT will remain "valid" until it has expired. Should you wish to immediately revoke access for a user, do consider making use of a Row Level Security policy as described below.


## Exporting users

As Supabase is built on top of Postgres, you can query the `auth.users` and `auth.identities` table via the `SQL Editor` tab to extract all users:

```sql
select * from auth.users;
```

You can then export the results as CSV.


# Native Mobile Deep Linking

Set up Deep Linking for mobile applications.

Many Auth methods involve a redirect to your app. For example:

*   Signup confirmation emails, Magic Link signins, and password reset emails contain a link that redirects to your app.
*   In OAuth signins, an automatic redirect occurs to your app.

With Deep Linking, you can configure this redirect to open a specific page. This is necessary if, for example, you need to display a form for [password reset](/docs/guides/auth/passwords#resetting-a-users-password-forgot-password), or to manually exchange a token hash.


## Setting up deep linking


# Password security

Help your users to protect their password security

A password is more secure if it is harder to guess or brute-force. In theory, a password is harder to guess if it is longer. It is also harder to guess if it uses a larger set of characters (for example, digits, lowercase and uppercase letters, and symbols).

This table shows the *minimum* number of guesses that need to be tried to access a user's account:

| Required characters                          | Length | Guesses          |
| -------------------------------------------- | ------ | ---------------- |
| Digits only                                  | 8      | ~ 2 |
| Digits and letters                           | 8      | ~ 2 |
| Digits, lower and uppercase letters          | 8      | ~ 2 |
| Digits, lower and uppercase letters, symbols | 8      | ~ 2 |

In reality though, passwords are not always generated at random. They often contain variations of names, words, dates, and common phrases. Malicious actors can use these properties to guess a password in fewer attempts.

There are hundreds of millions (and growing!) known passwords out there. Malicious actors can use these lists of leaked passwords to automate login attempts (known as credential stuffing) and steal or access sensitive user data.


## Password strength and leaked password protection

To help protect your users, Supabase Auth allows you fine-grained control over the strength of the passwords used on your project. You can configure these in your project's [Auth settings](/dashboard/project/_/auth/providers?provider=Email):

*   Set a large minimum password length. Anything less than 8 characters is not recommended.
*   Set the required characters that must appear at least once in a user's password. Use the strongest option of requiring digits, lowercase and uppercase letters, and symbols.
*   Prevent the use of leaked passwords. Supabase Auth uses the open-source [HaveIBeenPwned.org Pwned Passwords API](https://haveibeenpwned.com/Passwords) to reject passwords that have been leaked and are known by malicious actors.


## Additional recommendations

In addition to choosing suitable password strength settings and preventing the use of leaked passwords, consider asking your users to:

*   Use a password manager to store and generate passwords.
*   Avoid password reuse across websites and apps.
*   Avoid using personal information in passwords.
*   Use [Multi-Factor Authentication](/docs/guides/auth/auth-mfa).


## Frequently asked questions


### How are passwords stored?

Supabase Auth uses [bcrypt](https://en.wikipedia.org/wiki/Bcrypt), a strong password hashing function, to store hashes of users' passwords. Only hashed passwords are stored. You cannot impersonate a user with the password hash. Each hash is accompanied by a randomly generated salt parameter for extra security.

The hash is stored in the `encrypted_password` column of the `auth.users` table. The column's name is a misnomer (cryptographic hashing is not encryption), but is kept for backward compatibility.


### How will strengthened password requirements affect current users?

Existing users can still sign in with their current password even if it doesn't meet the new, strengthened password requirements. However, if their password falls short of these updated standards, they will encounter a `WeakPasswordError` during the `signInWithPassword` process, explaining why it's considered weak. This change is also applicable to new users and existing users changing their passwords, ensuring everyone adheres to the enhanced security standards.


# Password-based Auth

Allow users to sign in with a password connected to their email or phone number.

Users often expect to sign in to your site with a password. Supabase Auth helps you implement password-based auth safely, using secure configuration options and best practices for storing and verifying passwords.

Users can associate a password with their identity using their [email address](#with-email) or a [phone number](#with-phone).


## With email


### Enabling email and password-based authentication

Email authentication is enabled by default.

You can configure whether users need to verify their email to sign in. On hosted Supabase projects, this is true by default. On self-hosted projects or in local development, this is false by default.

Change this setting on the [Auth Providers page](/dashboard/project/_/auth/providers) for hosted projects, or in the [configuration file](/docs/guides/cli/config#auth.email.enable_confirmations) for self-hosted projects.


### Signing up with an email and password

There are two possible flows for email signup: [implicit flow](/docs/guides/auth/sessions#implicit-flow) and [PKCE flow](/docs/guides/auth/sessions#pkce-flow). If you're using SSR, you're using the PKCE flow. If you're using client-only code, the default flow depends upon the client library. The implicit flow is the default in JavaScript and Dart, and the PKCE flow is the default in Swift.

The instructions in this section assume that email confirmations are enabled.


### Signing in with an email and password


### Resetting a password


### Email sending

The signup confirmation and password reset flows require an SMTP server to send emails.

The Supabase platform comes with a default email-sending service for you to try out. The service has a rate limit of  emails per hour, and availability is on a best-effort basis. For production use, you should consider configuring a custom SMTP server.

See the [Custom SMTP guide](/docs/guides/auth/auth-smtp) for instructions.


#### Local development with Inbucket

You can test email flows on your local machine. The Supabase CLI automatically captures emails sent locally by using [Inbucket](https://github.com/inbucket/inbucket).

In your terminal, run `supabase status` to get the Inbucket URL. Go to this URL in your browser, and follow the instructions to find your emails.


## With phone

You can use a user's mobile phone number as an identifier, instead of an email address, when they sign up with a password.

This practice is usually discouraged because phone networks recycle mobile phone numbers. Anyone receiving a recycled phone number gets access to the original user's account. To mitigate this risk, [implement MFA](/docs/guides/auth/auth-mfa).


### Enabling phone and password-based authentication

Enable phone authentication on the [Auth Providers page](/dashboard/project/_/auth/providers) for hosted Supabase projects.

For self-hosted projects or local development, use the [configuration file](/docs/guides/cli/config#auth.sms.enable_signup). See the configuration variables namespaced under `auth.sms`.

If you want users to confirm their phone number on signup, you need to set up an SMS provider. Each provider has its own configuration. Supported providers include MessageBird, Twilio, Vonage, and TextLocal (community-supported).


### Signing up with a phone number and password

To sign up the user, call [`signUp()`](/docs/reference/javascript/auth-signup) with their phone number and password:

If you have phone verification turned on, the user receives an SMS with a 6-digit pin that you must verify within 60 seconds:


### Signing in a with a phone number and password

Call the function to sign in with the user's phone number and password:


# Phone Login



Phone Login is a method of authentication that allows users to log in to a website or application without using a password. The user authenticates through a one-time password (OTP) sent via a channel (SMS or WhatsApp).

Users can also log in with their phones using Native Mobile Login with the built-in identity provider. For Native Mobile Login with Android and iOS, see the [Social Login guides](/docs/guides/auth/social-login).

Phone OTP login can:

*   Improve the user experience by not requiring users to create and remember a password
*   Increase security by reducing the risk of password-related security breaches
*   Reduce support burden of dealing with password resets and other password-related flows


## Enabling phone login

Enable phone authentication on the [Auth Providers page](/dashboard/project/_/auth/providers) for hosted Supabase projects.

For self-hosted projects or local development, use the [configuration file](/docs/guides/cli/config#auth.sms.enable_signup). See the configuration variables namespaced under `auth.sms`.

You also need to set up an SMS provider. Each provider has its own configuration. Supported providers include MessageBird, Twilio, Vonage, and TextLocal (community-supported).

By default, a user can only request an OTP once every  and they expire after .


## Signing in with phone OTP

With OTP, a user can sign in without setting a password on their account. They need to verify their phone number each time they sign in.

The user receives an SMS with a 6-digit pin that you must verify within 60 seconds.


## Verifying a phone OTP

To verify the one-time password (OTP) sent to the user's phone number, call [`verifyOtp()`](/docs/reference/javascript/auth-verifyotp) with the phone number and OTP:

If successful the user will now be logged in and you should receive a valid session like:

```json
{
  "access_token": "<ACCESS_TOKEN>",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "<REFRESH_TOKEN>"
}
```

The access token can be sent in the Authorization header as a Bearer token for any CRUD operations on supabase-js. See our guide on [Row Level Security](/docs/guides/auth#row-level-security) for more info on restricting access on a user basis.


## Updating a phone number

To update a user's phone number, the user must be logged in. Call [`updateUser()`](/docs/reference/javascript/auth-updateuser) with their phone number:

The user receives an SMS with a 6-digit pin that you must [verify](#verifying-a-phone-otp) within 60 seconds.
Use the `phone_change` type when calling `verifyOTP` to update a user’s phone number.


# Use Supabase Auth with Next.js

Learn how to configure Supabase Auth for the Next.js App Router.

## Learn more

*   [Setting up Server-Side Auth for Next.js](https://supabase.com/docs/guides/auth/server-side/nextjs) for a Next.js deep dive
*   [Supabase Auth docs](https://supabase.com/docs/guides/auth#authentication) for more Supabase authentication methods


# Use Supabase Auth with React Native

Learn how to use Supabase Auth with React Native



# Use Supabase Auth with React

Learn how to use Supabase Auth with React.js.



# Rate limits

Rate limits protect your services from abuse

Supabase Auth enforces rate limits on endpoints to prevent abuse. Some rate limits are [customizable](/dashboard/project/_/auth/rate-limits).


# Redirect URLs

Set up redirect urls with Supabase Auth.

## Overview

When using [passwordless sign-ins](/docs/reference/javascript/auth-signinwithotp) or [third-party providers](/docs/reference/javascript/auth-signinwithoauth#sign-in-using-a-third-party-provider-with-redirect), the Supabase client library methods provide a `redirectTo` parameter to specify where to redirect the user to after authentication. By default, the user will be redirected to the [`SITE_URL`](/docs/guides/auth/redirect-urls) but you can modify the `SITE_URL` or add additional redirect URLs to the allow list. Once you've added necessary URLs to the allow list, you can specify the URL you want the user to be redirected to in the `redirectTo` parameter.

To edit the allow list, go to the [URL Configuration](/dashboard/project/_/auth/url-configuration) page. In local development or self-hosted projects, use the [configuration file](/docs/guides/cli/config#auth.additional_redirect_urls).


## Use wildcards in redirect URLs

Supabase allows you to specify wildcards when adding redirect URLs to the [allow list](https://supabase.com/dashboard/project/_/auth/url-configuration). You can use wildcard match patterns to support preview URLs from providers like Netlify and Vercel.

| Wildcard                 | Description                                                                                                                                |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `*`                      | matches any sequence of non-separator characters                                                                                           |
| `**`                     | matches any sequence of characters                                                                                                         |
| `?`                      | matches any single non-separator character                                                                                                 |
| `c`                      | matches character c (c != `*`, `**`, `?`, `\`, `[`, `{`, `}`)                                                                              |
| `\c`                     | matches character c                                                                                                                        |
| `[!{ character-range }]` | matches any sequence of characters not in the `{ character-range }`. For example, `[!a-z]` will not match any characters ranging from a-z. |

The separator characters in a URL are defined as `.` and `/`. Use [this tool](https://www.digitalocean.com/community/tools/glob?comments=true\&glob=http%3A%2F%2Flocalhost%3A3000%2F%2A%2A\&matches=false\&tests=http%3A%2F%2Flocalhost%3A3000\&tests=http%3A%2F%2Flocalhost%3A3000%2F\&tests=http%3A%2F%2Flocalhost%3A3000%2F%3Ftest%3Dtest\&tests=http%3A%2F%2Flocalhost%3A3000%2Ftest-test%3Ftest%3Dtest\&tests=http%3A%2F%2Flocalhost%3A3000%2Ftest%2Ftest%3Ftest%3Dtest) to test your patterns.


### Redirect URL examples with wildcards

| Redirect URL                   | Description                                                                                                                                                        |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `http://localhost:3000/*`      | matches `http://localhost:3000/foo`, `http://localhost:3000/bar` but not `http://localhost:3000/foo/bar` or `http://localhost:3000/foo/` (note the trailing slash) |
| `http://localhost:3000/**`     | matches `http://localhost:3000/foo`, `http://localhost:3000/bar` and `http://localhost:3000/foo/bar`                                                               |
| `http://localhost:3000/?`      | matches `http://localhost:3000/a` but not `http://localhost:3000/foo`                                                                                              |
| `http://localhost:3000/[!a-z]` | matches `http://localhost:3000/1` but not `http://localhost:3000/a`                                                                                                |


## Netlify preview URLs

For deployments with Netlify, set the `SITE_URL` to your official site URL. Add the following additional redirect URLs for local development and deployment previews:

*   `http://localhost:3000/**`
*   `https://**--my_org.netlify.app/**`


## Vercel preview URLs

For deployments with Vercel, set the `SITE_URL` to your official site URL. Add the following additional redirect URLs for local development and deployment previews:

*   `http://localhost:3000/**`
*   `https://*-<team-or-account-slug>.vercel.app/**`

Vercel provides an environment variable for the URL of the deployment called `NEXT_PUBLIC_VERCEL_URL`. See the [Vercel docs](https://vercel.com/docs/concepts/projects/environment-variables#system-environment-variables) for more details. You can use this variable to dynamically redirect depending on the environment. You should also set the value of the environment variable called NEXT\_PUBLIC\_SITE\_URL, this should be set to your site URL in production environment to ensure that redirects function correctly.

```js
const getURL = () => {
  let url =
    process?.env?.NEXT_PUBLIC_SITE_URL ?? // Set this to your site URL in production env.
    process?.env?.NEXT_PUBLIC_VERCEL_URL ?? // Automatically set by Vercel.
    'http://localhost:3000/'
  // Make sure to include `https://` when not localhost.
  url = url.startsWith('http') ? url : `https://${url}`
  // Make sure to include a trailing `/`.
  url = url.endsWith('/') ? url : `${url}/`
  return url
}

const { data, error } = await supabase.auth.signInWithOAuth({
  provider: 'github',
  options: {
    redirectTo: getURL(),
  },
})
```


## Email templates when using `redirectTo`

When using a `redirectTo` option, you may need to replace the `{{ .SiteURL }}` with `{{ .RedirectTo }}` in your email templates. See the [Email Templates guide](/docs/guides/auth/auth-email-templates) for more information.

For example, change the following:

```html
<!-- Old -->
<a href="{{ .SiteURL }}/auth/confirm?token_hash={{ .TokenHash }}&type=email">Confirm your mail</a>

<!-- New -->
<a href="{{ .RedirectTo }}/auth/confirm?token_hash={{ .TokenHash }}&type=email"
  >Confirm your mail</a
>
```


## Mobile deep linking URIs

For mobile applications you can use deep linking URIs. For example, for your `SITE_URL` you can specify something like `com.supabase://login-callback/` and for additional redirect URLs something like `com.supabase.staging://login-callback/` if needed.

Read more about deep linking and find code examples for different frameworks [here](/docs/guides/auth/native-mobile-deep-linking).


## Error handling

When authentication fails, the user will still be redirected to the redirect URL provided. However, the error details will be returned as query fragments in the URL. You can parse these query fragments and show a custom error message to the user. For example:

```js
const params = new URLSearchParams(window.location.hash.slice())

if (params.get('error_code').startsWith('4')) {
  // show error message if error is a 4xx error
  window.alert(params.get('error_description'))
}
```


# Server-Side Rendering

How SSR works with Supabase Auth.

SSR frameworks move rendering and data fetches to the server, to reduce client bundle size and execution time.

Supabase Auth is fully compatible with SSR. You need to make a few changes to the configuration of your Supabase client, to store the user session in cookies instead of local storage. After setting up your Supabase client, follow the instructions for any flow in the How-To guides.


## `@supabase/ssr`

We have developed an [`@supabase/ssr`](https://www.npmjs.com/package/@supabase/ssr) package to make setting up the Supabase client as simple as possible. This package is currently in beta. Adoption is recommended but be aware that the API is still unstable and may have breaking changes in the future.


## Framework quickstarts


# Advanced guide

Details about SSR Auth flows and implementation for advanced users.

When a user authenticates with Supabase Auth, two pieces of information are issued by the server:

1.  **Access token** in the form of a JWT.
2.  **Refresh token** which is a randomly generated string.

The default behavior if you're not using SSR is to store this information in local storage. Local storage isn't accessible by the server, so for SSR, the tokens instead need to be stored in a secure cookie. The cookie can then be passed back and forth between your app code in the client and your app code in the server.

If you're not using SSR, you might also be using the [implicit flow](/docs/guides/auth/sessions/implicit-flow) to get the access and refresh tokens. The server can't access the tokens in this flow, so for SSR, you should change to the [PKCE flow](/docs/guides/auth/sessions/pkce-flow). You can change the flow type when initiating your Supabase client if your client library provides this option.


## How it works

In the PKCE flow, a redirect is made to your app, with an Auth Code contained in the URL. When you exchange this code using `exchangeCodeForSession`, you receive the session information, which contains the access and refresh tokens.

To maintain the session, these tokens must be stored in a storage medium securely shared between client and server, which is traditionally cookies. Whenever the session is refreshed, the auth and refresh tokens in the shared storage medium must be updated. Supabase client libraries provide a customizable `storage` option when a client is initiated, allowing you to change where tokens are stored.

For an implementation example, see the [@supabase/ssr](https://github.com/supabase/auth-helpers/blob/main/packages/ssr/src/index.ts) package.


## Frequently asked questions


### No session on the server side with Next.js route prefetching?

When you use route prefetching in Next.js using `<Link href="/...">` components or the `Router.push()` APIs can send server-side requests before the browser processes the access and refresh tokens. This means that those requests may not have any cookies set and your server code will render unauthenticated content.

To improve experience for your users, we recommend redirecting users to one specific page after sign-in that does not include any route prefetching from Next.js. Once the Supabase client library running in the browser has obtained the access and refresh tokens from the URL fragment, you can send users to any pages that use prefetching.


### How do I make the cookies `HttpOnly`?

This is not necessary. Both the access token and refresh token are designed to be passed around to different components in your application. The browser-based side of your application needs access to the refresh token to properly maintain a browser session anyway.


### My server is getting invalid refresh token errors. What's going on?

It is likely that the refresh token sent from the browser to your server is stale. Make sure the `onAuthStateChange` listener callback is free of bugs and is registered relatively early in your application's lifetime

When you receive this error on the server-side, try to defer rendering to the browser where the client library can access an up-to-date refresh token and present the user with a better experience.


### Should I set a shorter `Max-Age` parameter on the cookies?

The `Max-Age` or `Expires` cookie parameters only control whether the browser sends the value to the server. Since a refresh token represents the long-lived authentication session of the user on that browser, setting a short `Max-Age` or `Expires` parameter on the cookies only results in a degraded user experience.

The only way to ensure that a user has logged out or their session has ended is to get the user's details with `getUser()`.


### What should I use for the `SameSite` property?

Make sure you [understand the behavior of the property in different situations](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite) as some properties can degrade the user experience.

A good default is to use `Lax` which sends cookies when users are navigating to your site. Cookies typically require the `Secure` attribute, which only sends them over HTTPS. However, this can be a problem when developing on `localhost`.


### Can I use server-side rendering with a CDN or cache?

Yes, but you need to be careful to include at least the refresh token cookie value in the cache key. Otherwise you may be accidentally serving pages with data belonging to different users!

Also be sure you set proper cache control headers. We recommend invalidating cache keys every hour or less.


### Which authentication flows have PKCE support?

At present, PKCE is supported on the Magic Link, OAuth, Sign Up, and Password Recovery routes. These correspond to the `signInWithOtp`, `signInWithOAuth`, `signUp`, and `resetPasswordForEmail` methods on the Supabase client library. When using PKCE with Phone and Email OTPs, there is no behavior change with respect to the implicit flow - an access token will be returned in the body when a request is successful.


# Creating a Supabase client for SSR

Configure your Supabase client to use cookies

To use Server-Side Rendering (SSR) with Supabase, you need to configure your Supabase client to use cookies. The `@supabase/ssr` package helps you do this for JavaScript/TypeScript applications.


## Install

Install the `@supabase/ssr` and `@supabase/supabase-js` packages:


## Set environment variables

In your environment variables file, set your Supabase URL and Supabase Anon Key:


## Create a client

You'll need some one-time setup code to configure your Supabase client to use cookies. Once your utility code is set up, you can use your new `createClient` utility functions to get a properly configured Supabase client.

Use the browser client in code that runs on the browser, and the server client in code that runs on the server.


## Next steps

*   Implement [Authentication using Email and Password](/docs/guides/auth/server-side/email-based-auth-with-pkce-flow-for-ssr)
*   Implement [Authentication using OAuth](/docs/guides/auth/server-side/oauth-with-pkce-flow-for-ssr)
*   [Learn more about SSR](/docs/guides/auth/server-side-rendering)


# Migrating to the SSR package from Auth Helpers



The new `ssr` package takes the core concepts of the Auth Helpers and makes them available to any server language or framework. This page will guide you through migrating from the Auth Helpers package to `ssr`.


### Replacing Supabase packages

```bash
npm install @supabase/ssr
```


### Creating a client

The new `ssr` package exports two functions for creating a Supabase client. The `createBrowserClient` function is used in the client, and the `createServerClient` function is used in the server.

Check out the [Creating a client](/docs/guides/auth/server-side/creating-a-client) page for examples of creating a client in your framework.


## Next steps

*   Implement [Authentication using Email and Password](/docs/guides/auth/server-side/email-based-auth-with-pkce-flow-for-ssr)
*   Implement [Authentication using OAuth](/docs/guides/auth/server-side/oauth-with-pkce-flow-for-ssr)
*   [Learn more about SSR](/docs/guides/auth/server-side-rendering)


# Setting up Server-Side Auth for Next.js



Next.js comes in two flavors: the [App Router](https://nextjs.org/docs/app) and the [Pages Router](https://nextjs.org/docs/pages). You can set up Server-Side Auth with either strategy. You can even use both in the same application.


# Setting up Server-Side Auth for SvelteKit



Set up Server-Side Auth to use cookie-based authentication with SvelteKit.


# User sessions



Supabase Auth provides fine-grained control over your user's sessions.

Some security sensitive applications, or those that need to be SOC 2, HIPAA, PCI-DSS or ISO27000 compliant will require some sort of additional session controls to enforce timeouts or provide additional security guarantees. Supabase Auth makes it easy to build compliant applications.


## What is a session?

A session is created when a user signs in. By default, it lasts indefinitely and a user can have an unlimited number of active sessions on as many devices.

A session is represented by the Supabase Auth access token in the form of a JWT, and a refresh token which is a unique string.

Access tokens are designed to be short lived, usually between 5 minutes and 1 hour while refresh tokens never expire but can only be used once. You can exchange a refresh token only once to get a new access and refresh token pair.

This process is called **refreshing the session.**

A session terminates, depending on configuration, when:

*   The user clicks sign out.
*   The user changes their password or performs a security sensitive action.
*   It times out due to inactivity.
*   It reaches its maximum lifetime.
*   A user signs in on another device.


## Access token (JWT) claims

Every access token contains a `session_id` claim, a UUID, uniquely identifying the session of the user. You can correlate this ID with the primary key of the `auth.sessions` table.


## Initiating a session

A session is initiated when a user signs in. The session is stored in the `auth.sessions` table, and your app should receive the access and refresh tokens.

There are two flows for initiating a session and receiving the tokens:

*   [Implicit flow](/docs/guides/auth/sessions/implicit-flow)
*   [PKCE flow](/docs/guides/auth/sessions/pkce-flow)


## Limiting session lifetime and number of allowed sessions per user

Supabase Auth can be configured to limit the lifetime of a user's session. By default, all sessions are active until the user signs out or performs some other action that terminates a session.

In some applications, it's useful or required for security to ensure that users authenticate often, or that sessions are not left active on devices for too long.

There are three ways to limit the lifetime of a session:

*   Time-boxed sessions, which terminate after a fixed amount of time.
*   Set an inactivity timeout, which terminates sessions that haven't been refreshed within the timeout duration.
*   Enforce a single-session per user, which only keeps the most recently active session.

To make sure that users are required to re-authenticate periodically, you can set a positive value for the **Time-box user sessions** option in the [Auth settings](/dashboard/project/_/settings/auth) for your project.

To make sure that sessions expire after a period of inactivity, you can set a positive duration for the **Inactivity timeout** option in the [Auth settings](/dashboard/project/_/settings/auth).

You can also enforce only one active session per user per device or browser. When this is enabled, the session from the most recent sign in will remain active, while the rest are terminated. Enable this via the *Single session per user* option in the [Auth settings](/dashboard/project/_/settings/auth).

Sessions are not proactively destroyed when you change these settings, but rather the check is enforced whenever a session is refreshed next. This can confuse developers because the actual duration of a session is the configured timeout plus the JWT expiration time. For single session per user, the effect will only be noticed at intervals of the JWT expiration time. Make sure you adjust this setting depending on your needs. We do not recommend going below 5 minutes for the JWT expiration time.

Otherwise sessions are progressively deleted from the database 24 hours after they expire, which prevents you from causing a high load on your project by accident and allows you some freedom to undo changes without adversely affecting all users.


## Frequently asked questions


### What are recommended values for access token (JWT) expiration?

Most applications should use the default expiration time of 1 hour. This can be customized in your project's [Auth settings](/dashboard/project/_/settings/auth) in the Advanced Settings section.

Setting a value over 1 hour is generally discouraged for security reasons, but it may make sense in certain situations.

Values below 5 minutes, and especially below 2 minutes, should not be used in most situations because:

*   The shorter the expiration time, the more frequently refresh tokens are used, which increases the load on the Auth server.
*   Time is not absolute. Servers can often be off sync for tens of seconds, but user devices like laptops, desktops or mobile devices can sometimes be off by minutes or even hours. Having too short expiration time can cause difficult-to-debug errors due to clock skew.
*   Supabase's client libraries always try to refresh the session ahead of time, which won't be possible if the expiration time is too short.
*   Access tokens should generally be valid for at least as long as the longest running request in your application. This helps you avoid issues where the access token becomes invalid midway through processing.


### What is refresh token reuse detection and what does it protect from?

As your users continue using your app, refresh tokens are being constantly exchanged for new access tokens.

The general rule is that a refresh token can only be used once. However, strictly enforcing this can cause certain issues to arise. There are two exceptions to this design to prevent the early and unexpected termination of user's sessions:

*   A refresh token can be used more than once within a defined reuse interval. By default this is 10 seconds and we do not recommend changing this value. This exception is granted for legitimate situations such as:
    *   Using server-side rendering where the same refresh token needs to be reused on the server and soon after on the client
    *   To allow some leeway for bugs or issues with serializing access to the refresh token request
*   If the parent of the currently active refresh token for the user's session is being used, the active token will be returned. This exception solves an important and often common situation:
    *   All clients such as browsers, mobile or desktop apps, and even some servers are inherently unreliable due to network issues. A request does not indicate that they received a response or even processed the response they received.
    *   If a refresh token is revoked after being used only once, and the response wasn't received and processed by the client, when the client comes back online, it will attempt to use the refresh token that was already used. Since this might happen outside of the reuse interval, it can cause sudden and unexpected session termination.

Should the reuse attempt not fall under these two exceptions, the whole session is regarded as terminated and all refresh tokens belonging to it are marked as revoked. You can disable this behavior in the Advanced Settings of the [Auth settings](/dashboard/project/_/settings/auth) page, though it is generally not recommended.

The purpose of this mechanism is to guard against potential security issues where a refresh token could have been stolen from the user, for example by exposing it accidentally in logs that leak (like logging cookies, request bodies or URL params) or via vulnerable third-party servers. It does not guard against the case where a user's session is stolen from their device.


### What are the benefits of using access and refresh tokens instead of traditional sessions?

Traditionally user sessions were implemented by using a unique string stored in cookies that identified the authorization that the user had on a specific browser. Applications would use this unique string to constantly fetch the attached user information on every API call.

This approach has some tradeoffs compared to using a JWT-based approach:

*   If the authentication server or its database crashes or is unavailable for even a few seconds, the whole application goes down. Scheduling maintenance or dealing with transient errors becomes very challenging.
*   A failing authentication server can cause a chain of failures across other systems and APIs, paralyzing the whole application system.
*   All requests that require authentication has to be routed through the authentication, which adds an additional latency overhead to all requests.

Supabase Auth prefers a JWT-based approach using access and refresh tokens because session information is encoded within the short-lived access token, enabling transfer across APIs and systems without dependence on a central server's availability or performance. This approach enhances an application's tolerance to transient failures or performance issues. Furthermore, proactively refreshing the access token allows the application to function reliably even during significant outages.

It's better for cost optimization and scaling as well, as the authentication system's servers and database only handle traffic for this use case.


### How to ensure an access token (JWT) cannot be used after a user signs out

Most applications rarely need such strong guarantees. Consider adjusting the JWT expiry time to an acceptable value. If this is still necessary, you should try to use this validation logic only for the most sensitive actions within your application.

When a user signs out, the sessions affected by the logout are removed from the database entirely. You can check that the `session_id` claim in the JWT corresponds to a row in the `auth.sessions` table. If such a row does not exist, it means that the user has logged out.

Note that sessions are not proactively terminated when their maximum lifetime (time-box) or inactivity timeout are reached. These sessions are cleaned up progressively 24 hours after reaching that status. This allows you to tweak the values or roll back changes without causing unintended user friction.


### Using HTTP-only cookies to store access and refresh tokens

This is possible, but only for apps that use the traditional server-only web app approach where all of the application logic is implemented on the server and it returns rendered HTML only.

If your app uses any client side JavaScript to build a rich user experience, using HTTP-Only cookies is not feasible since only your server will be able to read and refresh the session of the user. The browser will not have access to the access and refresh tokens.

Because of this, the Supabase JavaScript libraries provide only limited support. You can override the `storage` option when creating the Supabase client **on the server** to store the values in cookies or your preferred storage choice, for example:

```typescript
import { createClient } from '@supabase/supabase-js'

const supabase = createClient('SUPABASE_URL', 'SUPABASE_ANON_KEY', {
  auth: {
    storage: {
      getItem: () => {
        return Promise.resolve('FETCHED_COOKIE')
      },
      setItem: () => {},
      removeItem: () => {},
    },
  },
})
```

The `customStorageObject` should implement the `getItem`, `setItem`, and `removeItem` methods from the [`Storage` interface](https://developer.mozilla.org/en-US/docs/Web/API/Storage). Async versions of these methods are also supported.

When using cookies to store access and refresh tokens, make sure that the [`Expires` or `Max-Age` attributes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#attributes) of the cookies is set to a timestamp very far into the future. Browsers will clear the cookies, but the session will remain active in Supabase Auth. Therefore it's best to let Supabase Auth control the validity of these tokens and instruct the browser to always store the cookies indefinitely.


# Implicit flow

About authenticating with implicit flow.

The implicit flow is one of two ways that a user can authenticate and your app can receive the necessary access and refresh tokens.

The flow is an implementation detail handled for you by Supabase Auth, but understanding the difference between implicit and [PKCE flow](/docs/guides/auth/sessions/pkce-flow) is important for understanding the difference between client-only and server-side auth.


## How it works

After a successful signin, the user is redirected to your app with a URL that looks like this:

    https://yourapp.com/...#access_token=<...>&refresh_token=<...>&...

The access and refresh tokens are contained in the URL fragment.

The client libraries:

*   Detect this type of URL
*   Extract the access token, refresh token, and some extra information
*   Persist this information to local storage for further use by the library and your app


## Limitations

The implicit flow only works on the client. Web browsers do not send the URL fragment to the server by design. This is a security feature:

*   You may be hosting your single-page app on a third-party server. The third-party service shouldn't get access to your user's credentials.
*   Even if the server is under your direct control, `GET` requests and their full URLs are often logged. This approach avoids leaking credentials in request or access logs.

If you wish to obtain the access token and refresh token on a server, use the [PKCE flow](/docs/guides/auth/sessions/pkce-flow).


# PKCE flow

About authenticating with PKCE flow.

The Proof Key for Code Exchange (PKCE) flow is one of two ways that a user can authenticate and your app can receive the necessary access and refresh tokens.

The flow is an implementation detail handled for you by Supabase Auth, but understanding the difference between PKCE and [implicit flow](/docs/guides/auth/sessions/implicit-flow) is important for understanding the difference between client-only and server-side auth.


## How it works

After a successful verification, the user is redirected to your app with a URL that looks like this:

    https://yourapp.com/...?code=<...>

The `code` parameter is commonly known as the Auth Code and can be exchanged for an access token by calling `exchangeCodeForSession(code)`.

As the flow is run server side, `localStorage` may not be available. You may configure the client library to use a custom storage adapter and an alternate backing storage such as cookies by setting the `storage` option to an object with the following methods:

```js
import { type SupportedStorage } from '@supabase/supabase-js';
const supportsLocalStorage = () => true

// ---cut---
const customStorageAdapter: SupportedStorage = {
    getItem: (key) => {
    if (!supportsLocalStorage()) {
        // Configure alternate storage
        return null
    }
    return globalThis.localStorage.getItem(key)
    },
    setItem: (key, value) => {
    if (!supportsLocalStorage()) {
        // Configure alternate storage here
        return
    }
    globalThis.localStorage.setItem(key, value)
    },
    removeItem: (key) => {
    if (!supportsLocalStorage()) {
        // Configure alternate storage here
        return
    }
    globalThis.localStorage.removeItem(key)
    },
}
```

You may also configure the client library to automatically exchange it for a session after a successful redirect. This can be done by setting the `detectSessionInUrl` option to `true`.

Putting it all together, your client library initialization may look like this:

```js
import { createClient } from '@supabase/supabase-js'

// ---cut---
const supabase = createClient('https://xyzcompany.supabase.co', 'public-anon-key', {
  // ...
  auth: {
    // ...
    detectSessionInUrl: true,
    flowType: 'pkce',
    storage: {
      getItem: () => Promise.resolve('FETCHED_TOKEN'),
      setItem: () => {},
      removeItem: () => {},
    },
  },
  // ...
})
```


## Limitations

Behind the scenes, the code exchange requires a code verifier. Both the code in the URL and the code verifier are sent back to the Auth server for a successful exchange.

The code verifier is created and stored locally when the Auth flow is first initiated. That means the code exchange must be initiated on the same browser and device where the flow was started.


## Resources

*   [OAuth 2.0 guide](https://oauth.net/2/pkce/) to PKCE flow


# Signing out

Signing out a user

Signing out a user works the same way no matter what method they used to sign in.

Call the sign out method from the client library. It removes the active session and clears Auth data from the storage medium.


## Sign out and scopes

Supabase Auth allows you to specify three different scopes for when a user invokes the [sign out API](/docs/reference/javascript/auth-signout) in your application:

*   `global` (default) when all sessions active for the user are terminated.
*   `local` which only terminates the current session for the user but keep sessions on other devices or browsers active.
*   `others` to terminate all but the current session for the user.

You can invoke these by providing the `scope` option:

Upon sign out, all refresh tokens and potentially other database objects related to the affected sessions are destroyed and the client library removes the session stored in the local storage medium.


# Social Login



Social Login (OAuth) is an open standard for authentication that allows users to log in to one website or application using their credentials from another website or application. OAuth allows users to grant third-party applications access to their online accounts without sharing their passwords.
OAuth is commonly used for things like logging in to a social media account from a third-party app. It is a secure and convenient way to authenticate users and share information between applications.


## Benefits

There are several reasons why you might want to add social login to your applications:

*   **Improved user experience**: Users can register and log in to your application using their existing social media accounts, which can be faster and more convenient than creating a new account from scratch. This makes it easier for users to access your application, improving their overall experience.

*   **Better user engagement**: You can access additional data and insights about your users, such as their interests, demographics, and social connections. This can help you tailor your content and marketing efforts to better engage with your users and provide a more personalized experience.

*   **Increased security**: Social login can improve the security of your application by leveraging the security measures and authentication protocols of the social media platforms that your users are logging in with. This can help protect against unauthorized access and account takeovers.


## Set up a social provider with Supabase Auth

Supabase supports a suite of social providers. Follow these guides to configure a social provider for your platform.


## Provider tokens

You can use the provider token and provider refresh token returned to make API calls to the OAuth provider. For example, you can use the Google provider token to access Google APIs on behalf of your user.

Supabase Auth does not manage refreshing the provider token for the user. Your application will need to use the provider refresh token to obtain a new provider token. If no provider refresh token is returned, then it could mean one of the following:

*   The OAuth provider does not return a refresh token
*   Additional scopes need to be specified in order for the OAuth provider to return a refresh token.

Provider tokens are intentionally not stored in your project's database. This is because provider tokens give access to potentially sensitive user data in third-party systems. Different applications have different needs, and one application's OAuth scopes may be significantly more permissive than another. If you want to use the provider token outside of the browser that completed the OAuth flow, it is recommended to send it to a trusted and secure server you control.


# Login with Apple



Supabase Auth supports using [Sign in with Apple](https://developer.apple.com/sign-in-with-apple/) on the web and in native apps for iOS, macOS, watchOS or tvOS.


## Overview

To support Sign in with Apple, you need to configure the [Apple provider in the Supabase dashboard](https://supabase.com/dashboard/project/_/auth/providers) for your project.

There are three general ways to use Sign in with Apple, depending on the application you're trying to build:

*   Sign in on the web or in web-based apps
    *   Using an OAuth flow initiated by Supabase Auth using the [Sign in with Apple REST API](https://developer.apple.com/documentation/sign_in_with_apple/sign_in_with_apple_rest_api).
    *   Using [Sign in with Apple JS](https://developer.apple.com/documentation/sign_in_with_apple/sign_in_with_apple_js) directly in the browser, usually suitable for websites.
*   Sign in natively inside iOS, macOS, watchOS or tvOS apps using [Apple's Authentication Services](https://developer.apple.com/documentation/authenticationservices)

In some cases you're able to use the OAuth flow within web-based native apps such as with [React Native](https://reactnative.dev), [Expo](https://expo.dev) or other similar frameworks. It is best practice to use native Sign in with Apple capabilities on those platforms instead.

When developing with Expo, you can test Sign in with Apple via the Expo Go app, in all other cases you will need to obtain an [Apple Developer](https://developer.apple.com) account to enable the capability.


# Login with Azure (Microsoft)



To enable Azure (Microsoft) Auth for your project, you need to set up an Azure OAuth application and add the application credentials to your Supabase Dashboard.


## Overview

Setting up OAuth with Azure consists of four broad steps:

*   Create an OAuth application under Azure Entra ID.
*   Add a secret to the application.
*   Add the Supabase Auth callback URL to the allowlist in the OAuth application in Azure.
*   Configure the client ID and secret of the OAuth application within the Supabase Auth dashboard.


## Access your Azure Developer account

*   Go to [portal.azure.com](https://portal.azure.com/#home).
*   Login and select Microsoft Entra ID under the list of Azure Services.


## Register an application

*   Under Microsoft Entra ID, select *App registrations* in the side panel and select *New registration.*
*   Choose a name and select your preferred option for the supported account types.
*   Specify a *Web* *Redirect URI*. It should look like this: `https://<project-ref>.supabase.co/auth/v1/callback`
*   Finally, select *Register* at the bottom of the screen.

![Register an application.](/docs/img/guides/auth-azure/azure-register-app.png)


## Obtain a client ID and secret

*   Once your app has been registered, the client ID can be found under the [list of app registrations](https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps) under the column titled *Application (client) ID*.
*   You can also find it in the app overview screen.
*   Place the Client ID in the Azure configuration screen in the Supabase Auth dashboard.

![Obtain the client ID](/docs/img/guides/auth-azure/azure-client-id.png)

*   Select *Add a certificate or secret* in the app overview screen and open the *Client secrets* tab.
*   Select *New client secret* to create a new client secret.
*   Choose a preferred expiry time of the secret. Make sure you record this in your calendar days in advance so you have enough time to create a new one without suffering from any downtime.
*   Once the secret is generated place the *Value* column (not *Secret ID*) in the Azure configuration screen in the Supabase Auth dashboard.

![Obtain the client secret](/docs/img/guides/auth-azure/azure-client-secret.png)


## Guarding against unverified email domains

Microsoft Entra ID can send out unverified email domains in certain cases. This may open up your project to a vulnerability where a malicious user can impersonate already existing accounts on your project.

This only applies in at least one of these cases:

*   You have configured the `authenticationBehaviors` setting of your OAuth application to allow unverified email domains
*   You are using an OAuth app configured as single-tenant in the supported account types
*   Your OAuth app was created before June 20th 2023 after Microsoft announced this vulnerability, and the app had used unverified emails prior

This means that most OAuth apps *are not susceptible* to this vulnerability.

Despite this, we recommend configuring the [optional `xms_edov` claim](https://learn.microsoft.com/en-us/azure/active-directory/develop/migrate-off-email-claim-authorization#using-the-xms_edov-optional-claim-to-determine-email-verification-status-and-migrate-users) on the OAuth app. This claim allows Supabase Auth to identify with certainty whether the email address sent over by Microsoft Entra ID is verified or not.

Configure this in the following way:

*   Select the *App registrations* menu in Microsoft Entra ID on the Azure portal.
*   Select the OAuth app.
*   Select the *Manifest* menu in the sidebar.
*   Make a backup of the JSON just in case.
*   Identify the `optionalClaims` key.
*   Edit it by specifying the following object:
    ```json
      "optionalClaims": {
          "idToken": [
              {
                  "name": "xms_edov",
                  "source": null,
                  "essential": false,
                  "additionalProperties": []
              },
              {
                  "name": "email",
                  "source": null,
                  "essential": false,
                  "additionalProperties": []
              }
          ],
          "accessToken": [
              {
                  "name": "xms_edov",
                  "source": null,
                  "essential": false,
                  "additionalProperties": []
              }
          ],
          "saml2Token": []
      },
    ```
*   Select *Save* to apply the new configuration.


## Configure a tenant URL (optional)

A Microsoft Entra tenant is the directory of users who are allowed to access your project. This section depends on what your OAuth registration uses for *Supported account types.*

By default, Supabase Auth uses the *common* Microsoft tenant (`https://login.microsoftonline.com/common`) which generally allows any Microsoft account to sign in to your project. Microsoft Entra further limits what accounts can access your project depending on the type of OAuth application you registered.

If your app is registered as *Personal Microsoft accounts only* for the *Supported account types* set Microsoft tenant to *consumers* (`https://login.microsoftonline.com/consumers`).

If your app is registered as *My organization only* for the *Supported account types* you may want to configure Supabase Auth with the organization's tenant URL. This will use the tenant's authorization flows instead, and will limit access at the Supabase Auth level to Microsoft accounts arising from only the specified tenant.

Configure this by storing a value under *Azure Tenant URL* in the Supabase Auth provider configuration page for Azure that has the following format `https://login.microsoftonline.com/<tenant-id>`.


## Add login code to your client app


## Obtain the provider refresh token

Azure OAuth2.0 doesn't return the `provider_refresh_token` by default. If you need the `provider_refresh_token` returned, you will need to include the following scope:


## Resources

*   [Azure Developer Account](https://portal.azure.com)
*   [GitHub Discussion](https://github.com/supabase/gotrue/pull/54#issuecomment-757043573)
*   [Potential Risk of Privilege Escalation in Azure AD Applications](https://msrc.microsoft.com/blog/2023/06/potential-risk-of-privilege-escalation-in-azure-ad-applications/)


# Login with Bitbucket



To enable Bitbucket Auth for your project, you need to set up a Bitbucket OAuth application and add the application credentials to your Supabase Dashboard.


## Overview

Setting up Bitbucket logins for your application consists of 3 parts:

*   Create and configure a Bitbucket OAuth Consumer on [Bitbucket](https://bitbucket.org)
*   Add your Bitbucket OAuth Consumer keys to your [Supabase Project](https://supabase.com/dashboard)
*   Add the login code to your [Supabase JS Client App](https://github.com/supabase/supabase-js)


## Access your Bitbucket account

*   Go to [bitbucket.org](https://bitbucket.org/).
*   Click on `Login` at the top right to log in.

![Bitbucket Developer Portal.](/docs/img/guides/auth-bitbucket/bitbucket-portal.png)


## Find your callback URL


## Create a Bitbucket OAuth app

*   Click on your profile icon at the bottom left
*   Click on `All Workspaces`
*   Select a workspace and click on it to select it
*   Click on `Settings` on the left
*   Click on `OAuth consumers` on the left under `Apps and Features` (near the bottom)
*   Click `Add Consumer` at the top
*   Enter the name of your app under `Name`
*   In `Callback URL`, type the callback URL of your app
*   Check the permissions you need (Email, Read should be enough)
*   Click `Save` at the bottom
*   Click on your app name (the name of your new OAuth Consumer)
*   Copy your `Key` (`client_key`) and `Secret` (`client_secret`) codes


## Add your Bitbucket credentials into your Supabase project


## Add login code to your client app


## Resources

*   [Supabase - Get started for free](https://supabase.com)
*   [Supabase JS Client](https://github.com/supabase/supabase-js)
*   [Bitbucket Account](https://bitbucket.org)


# Login with Discord



To enable Discord Auth for your project, you need to set up a Discord Application and add the Application OAuth credentials to your Supabase Dashboard.


## Overview

Setting up Discord logins for your application consists of 3 parts:

*   Create and configure a Discord Application [Discord Developer Portal](https://discord.com/developers)
*   Add your Discord OAuth Consumer keys to your [Supabase Project](https://supabase.com/dashboard)
*   Add the login code to your [Supabase JS Client App](https://github.com/supabase/supabase-js)


## Access your Discord account

*   Go to [discord.com](https://discord.com/).
*   Click on `Login` at the top right to log in.

![Discord Portal.](/docs/img/guides/auth-discord/discord-portal.png)

*   Once logged in, go to [discord.com/developers](https://discord.com/developers).

![Discord Portal.](/docs/img/guides/auth-discord/discord-developer-portal.png)


## Find your callback URL


## Create a Discord application

*   Click on `New Application` at the top right.
*   Enter the name of your application and click `Create`.
*   Click on `OAuth2` under `Settings` in the left side panel.
*   Click `Add Redirect` under `Redirects`.
*   Type or paste your `callback URL` into the `Redirects` box.
*   Click `Save Changes` at the bottom.
*   Copy your `Client ID` and `Client Secret` under `Client information`.


## Add your Discord credentials into your Supabase project


## Add login code to your client app

If your user is already signed in, Discord prompts the user again for authorization.


## Resources

*   [Supabase - Get started for free](https://supabase.com)
*   [Supabase JS Client](https://github.com/supabase/supabase-js)
*   [Discord Account](https://discord.com)
*   [Discord Developer Portal](https://discord.com/developers)


# Login with Facebook



To enable Facebook Auth for your project, you need to set up a Facebook OAuth application and add the application credentials to your Supabase Dashboard.


## Overview

Setting up Facebook logins for your application consists of 3 parts:

*   Create and configure a Facebook Application on the [Facebook Developers Site](https://developers.facebook.com)
*   Add your Facebook keys to your [Supabase Project](https://supabase.com/dashboard)
*   Add the login code to your [Supabase JS Client App](https://github.com/supabase/supabase-js)


## Access your Facebook Developer account

*   Go to [developers.facebook.com](https://developers.facebook.com).
*   Click on `Log In` at the top right to log in.

![Facebook Developer Portal.](/docs/img/guides/auth-facebook/facebook-portal.png)


## Create a Facebook app

*   Click on `My Apps` at the top right.
*   Click `Create App` near the top right.
*   Select your app type and click `Continue`.
*   Fill in your app information, then click `Create App`.
*   This should bring you to the screen: `Add Products to Your App`. (Alternatively you can click on `Add Product` in the left sidebar to get to this screen.)


## Set up Facebook login for your Facebook app

From the `Add Products to your App` screen:

*   Click `Setup` under `Facebook Login`
*   Skip the Quickstart screen, instead, in the left sidebar, click `Settings` under `Facebook Login`
*   Enter your callback URI under `Valid OAuth Redirect URIs` on the `Facebook Login Settings` page
*   Enter this in the `Valid OAuth Redirect URIs` box
*   Click `Save Changes` at the bottom right

Be aware that you have to set the right use case permissions to enable Third party applications to read the email address. To do so:

Under `Build Your App`, click on `Use Cases` screen. From there, do the following steps:

*   Click the Edit button in `Authentication and Account Creation` on the right side. This action will lead to the other page.
*   `public_profile` is set by default, so make sure it and `email` have status of **Ready for testing** in the redirected page.
*   If not, click the **Add** button in email on right side.


## Copy your Facebook app ID and secret

*   Click `Settings / Basic` in the left sidebar
*   Copy your App ID from the top of the `Basic Settings` page
*   Under `App Secret` click `Show` then copy your secret
*   Make sure all required fields are completed on this screen.


## Enter your Facebook app ID and secret into your Supabase project


## Add login code to your client app

Now, you should be able to login with Facebook and alert you to `Submit for Login Review` when users try to sign into your app. Follow the instructions there to make your app go live for full features and products.
You can read more about App Review [here](https://developers.facebook.com/docs/app-review/).


## Resources

*   [Supabase - Get started for free](https://supabase.com)
*   [Supabase JS Client](https://github.com/supabase/supabase-js)
*   [Facebook Developers Dashboard](https://developers.facebook.com/)


# Login with Figma



To enable Figma Auth for your project, you need to set up a Figma OAuth application and add the application credentials to your Supabase Dashboard.


## Overview

Setting up Figma logins for your application consists of 3 parts:

*   Create and configure a Figma App on the [Figma Developers page](https://www.figma.com/developers).
*   Add your Figma `client_id` and `client_secret` to your [Supabase Project](https://app.supabase.com).
*   Add the login code to your [Supabase JS Client App](https://github.com/supabase/supabase-js).


## Access the Figma Developers page

*   Go to the [Figma Developers page](https://www.figma.com/developers)
*   Click on `My apps` at the top right
*   Log in (if necessary)

![Figma Developers page](/docs/img/guides/auth-figma/figma_developers_page.png)


## Find your callback URL


## Create a Figma OAuth app

*   Enter your `App name`, `Website URL` and upload your app logo
*   Click on `Add callback`
*   Add your `Callback URL`
*   Click on `Save`

![Create Figma app](/docs/img/guides/auth-figma/figma_create_app.png)

*   Copy and save your newly-generated `Client ID`
*   Copy and save your newly-generated `Client Secret`

![Get Figma app credentials](/docs/img/guides/auth-figma/figma_app_credentials.png)


## Enter your Figma credentials into your Supabase project


## Add login code to your client app


## Resources

*   [Supabase - Get started for free](https://supabase.com)
*   [Supabase JS Client](https://github.com/supabase/supabase-js)
*   [Figma Developers page](https://www.figma.com/developers)


# Login with GitHub



To enable GitHub Auth for your project, you need to set up a GitHub OAuth application and add the application credentials to your Supabase Dashboard.


## Overview

Setting up GitHub logins for your application consists of 3 parts:

*   Create and configure a GitHub OAuth App on [GitHub](https://github.com)
*   Add your GitHub OAuth keys to your [Supabase Project](https://supabase.com/dashboard)
*   Add the login code to your [Supabase JS Client App](https://github.com/supabase/supabase-js)


## Find your callback URL


## Register a new OAuth application on GitHub

*   Navigate to the [OAuth apps page](https://github.com/settings/developers)
*   Click `Register a new application`. If you've created an app before, click `New OAuth App` here.
*   In `Application name`, type the name of your app.
*   In `Homepage URL`, type the full URL to your app's website.
*   In `Authorization callback URL`, type the callback URL of your app.
*   Leave `Enable Device Flow` unchecked.
*   Click `Register Application`.

Copy your new OAuth credentials

*   Copy and save your `Client ID`.
*   Click `Generate a new client secret`.
*   Copy and save your `Client secret`.


## Enter your GitHub credentials into your Supabase project


## Add login code to your client app


## Resources

*   [Supabase - Get started for free](https://supabase.com)
*   [Supabase JS Client](https://github.com/supabase/supabase-js)
*   [GitHub Developer Settings](https://github.com/settings/developers)


# Login with GitLab



To enable GitLab Auth for your project, you need to set up a GitLab OAuth application and add the application credentials to your Supabase Dashboard.


## Overview

Setting up GitLab logins for your application consists of 3 parts:

*   Create and configure a GitLab Application on [GitLab](https://gitlab.com)
*   Add your GitLab Application keys to your [Supabase Project](https://supabase.com/dashboard)
*   Add the login code to your [Supabase JS Client App](https://github.com/supabase/supabase-js)


## Access your GitLab account

*   Go to [gitlab.com](https://gitlab.com).
*   Click on `Login` at the top right to log in.

![GitLab Developer Portal.](/docs/img/guides/auth-gitlab/gitlab-portal.png)


## Find your callback URL


## Create your GitLab application

*   Click on your `profile logo` (avatar) in the top-right corner.
*   Select `Edit profile`.
*   In the left sidebar, select Applications.
*   Enter the name of the application.
*   In the `Redirect URI` box, type the callback URL of your app.
*   Check the box next to `Confidential` (make sure it is checked).
*   Check the scope named `read_user` (this is the only required scope).
*   Click `Save Application` at the bottom.
*   Copy and save your `Application ID` (`client_id`) and `Secret` (`client_secret`) which you'll need later.


## Add your GitLab credentials into your Supabase project


## Add login code to your client app


## Resources

*   [Supabase - Get started for free](https://supabase.com)
*   [Supabase JS Client](https://github.com/supabase/supabase-js)
*   [GitLab Account](https://gitlab.com)


# Login with Google



Supabase Auth supports Sign in with Google for the web, native Android applications, and Chrome extensions.


## Prerequisites

*   A Google Cloud project. Go to the [Google Cloud Platform](https://console.cloud.google.com/home/dashboard) and create a new project if necessary.


## Configuration

To support Sign In with Google, you need to configure the Google provider for your Supabase project.


## Signing users in


## Google consent screen

![Google Consent Screen](/docs/img/guides/auth-google/auth-google-consent-screen.png)

By default, the Google consent screen shows the root domain of the callback URL, where Google will send the authentication response. With Supabase Auth, it is your Supabase project's domain `(https://<your-project-ref>.supabase.co)`.

If that is not preferable, you can use a [Custom Domain](https://supabase.com/docs/guides/platform/custom-domains) with your Supabase project. You can use it as your project's domain when creating the Supabase client in your application and initiating the authentication flow. It will then show up in the Google consent screen. If you want your app name and the logo on the consent screen, [you must submit your app to Google for verification](https://support.google.com/cloud/answer/10311615).


# Login with Kakao



To enable Kakao Auth for your project, you need to set up an Kakao OAuth application and add the application credentials to your Supabase Dashboard.


## Overview

Kakao OAuth consists of six broad steps:

*   Create and configure your app in the [Kakao Developer Portal](https://developers.kakao.com).
*   Obtaining a `REST API key` - this will serve as the `client_id`.
*   Generating the `Client secret code` - this will serve as the `client_secret`.
*   Additional configurations on Kakao Developers Portal.
*   Add your `client id` and `client secret` keys to your [Supabase Project](https://supabase.com/dashboard).
*   Add the login code to your [Supabase JS Client App](https://github.com/supabase/supabase-js).


## Access your Kakao Developer account

*   Go to [Kakao Developers Portal](https://developers.kakao.com).
*   Click on `Login` at the top right to log in.

![Kakao Developers Portal.](/docs/img/guides/auth-kakao/kakao-developers-page.png)


## Create and configure your app

*   Go to `My Application`.
*   Click on `Add an application` at the top.
*   Fill out your app information:
    *   App icon.
    *   App name.
    *   Company name.
*   Click `Save` at the bottom right.


## Obtain a REST API key

This will serve as the `client_id` when you make API calls to authenticate the user.

*   Go to `My Application`.
*   Click on your app.
*   You will be redirected to `Summary` tab of your app.
*   In the `App Keys` section you will see `REST API key` -- this ID will become your `client_id` later.


## Find your callback URL

*   To add callback URL on Kakao, go to `Product settings` >
    `Kakao Login` > `Redirect URI`.


## Generate and activate a `client_secret`

*   Go to `Product settings` > `Kakao Login` > `Security`.
*   Click on the `Kakao Login` switch to enable Kakao Login.
*   Click on `generate code` at the bottom to generate the `Client secret code` -- this will serve as a `client_secret` for your Supabase project.
*   Make sure you enabled `Client secret code` by selecting `enable` from the `Activation state` section.


## Additional configurations on Kakao Developers portal

*   Make sure the Kakao Login is enabled in the `Kakao Login` tab.
*   Set following scopes under the "Consent Items": account\_email, profile\_image, profile\_nickname

![Consent items needs to be set.](/docs/img/guides/auth-kakao/kakao-developers-consent-items-set.png)


## Add your OAuth credentials to Supabase


## Add login code to your client app


## Using Kakao Login JS SDK

[Kakao Login JS SDK](https://developers.kakao.com/docs/latest/en/kakaologin/js) is an official Kakao SDK for authenticating Kakao users on websites.

Exchange the [authorization code returned by Kakao API](https://developers.kakao.com/docs/latest/en/kakaologin/rest-api#request-code) for an [ID Token](https://developers.kakao.com/docs/latest/en/kakaologin/common#login-with-oidc).

For example, this code shows a how to get ID Token:

    const requestUrl = new URL(request.url);
    const code = requestUrl.searchParams.get('code');

    if (code) {
      const res = await fetch('https://kauth.kakao.com/oauth/token', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/x-www-form-urlencoded;charset=utf-8',
        },
        body: new URLSearchParams({
          grant_type: 'authorization_code',
          client_id: '<CLIENT_ID>',
          redirect_uri: '<url>/api/auth/kakao/oidc',
          code,
          client_secret: '<CLIENT_SECRET>',
        }),
      });

      const {id_token} = await res.json();
    }

Use the ID Token to sign in:

    const res = await auth.signInWithIdToken({
      provider: 'kakao',
      token: id_token,
    });


### Configuration

1.  Set 'State' to 'ON' under [OpenID Connect Activation](https://developers.kakao.com/docs/latest/en/kakaologin/prerequisite#activate-oidc) on Kakao Developers portal Application Dashboard.
2.  Add `openid` to [scope](https://developers.kakao.com/docs/latest/en/kakaologin/common#additional-consent-scope) along with the scope values you wish to obtain consent for.


## Resources

*   [Kakao Developers Portal](https://developers.kakao.com).


# Login with Keycloak



To enable Keycloak Auth for your project, you need to set up an Keycloak OAuth application and add the application credentials to your Supabase Dashboard.


## Overview

To get started with Keycloak, you can run it in a docker container with: `docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:latest start-dev`

This guide will be assuming that you are running Keycloak in a docker container as described in the command above.

Keycloak OAuth consists of five broad steps:

*   Create a new client in your specified Keycloak realm.
*   Obtain the `issuer` from the "OpenID Endpoint Configuration". This will be used as the `Keycloak URL`.
*   Ensure that the new client has the "Client Protocol" set to `openid-connect` and the "Access Type" is set to "confidential".
*   The `Client ID` of the client created will be used as the `client id`.
*   Obtain the `Secret` from the credentials tab which will be used as the `client secret`.
*   Add the callback URL of your application to your allowlist.


## Access your Keycloak admin console

*   Login by visiting [`http://localhost:8080`](http://localhost:8080) and clicking on "Administration Console".


## Create a Keycloak realm

*   Once you've logged in to the Keycloak console, you can add a realm from the side panel. The default realm should be named "Master".
*   After you've added a new realm, you can retrieve the `issuer` from the "OpenID Endpoint Configuration" endpoint. The `issuer` will be used as the `Keycloak URL`.
*   You can find this endpoint from the realm settings under the "General Tab" or visit [`http://localhost:8080/realms/my_realm_name/.well-known/openid-configuration`](http://localhost:8080/realms/my_realm_name/.well-known/openid-configuration)

![Add a Keycloak Realm.](/docs/img/guides/auth-keycloak/keycloak-create-realm.png)


## Create a Keycloak client

The "Client ID" of the created client will serve as the `client_id` when you make API calls to authenticate the user.

![Add a Keycloak client](/docs/img/guides/auth-keycloak/keycloak-add-client.png)


## Client settings

After you've created the client successfully, ensure that you set the following settings:

1.  The "Client Protocol" should be set to `openid-connect`.
2.  The "Access Type" should be set to "confidential".
3.  The "Valid Redirect URIs" should be set to: `https://<project-ref>.supabase.co/auth/v1/callback`.

![Obtain the client id, set the client protocol and access type](/docs/img/guides/auth-keycloak/keycloak-client-id.png)
![Set redirect uri](/docs/img/guides/auth-keycloak/keycloak-redirect-uri.png)


## Obtain the client secret

This will serve as the `client_secret` when you make API calls to authenticate the user.
Under the "Credentials" tab, the `Secret` value will be used as the `client secret`.

![Obtain the client secret](/docs/img/guides/auth-keycloak/keycloak-client-secret.png)


## Add login code to your client app

Since Keycloak version 22, the `openid` scope must be passed. Add this to the [`supabase.auth.signInWithOAuth()`](/docs/reference/javascript/auth-signinwithoauth) method.


## Resources

*   You can find the Keycloak OpenID endpoint configuration under the realm settings.
    ![Keycloak OpenID Endpoint Configuration](/docs/img/guides/auth-keycloak/keycloak-openid-endpoint-config.png)


# Login with LinkedIn



To enable LinkedIn Auth for your project, you need to set up a LinkedIn OAuth application and add the application credentials to your Supabase Dashboard.


## Overview

Setting up LinkedIn logins for your application consists of 3 parts:

*   Create and configure a LinkedIn Project and App on the [LinkedIn Developer Dashboard](https://www.linkedin.com/developers/apps).
*   Add your *LinkedIn (OIDC)* `client_id` and `client_secret` to your [Supabase Project](https://supabase.com/dashboard).
*   Add the login code to your [Supabase JS Client App](https://github.com/supabase/supabase-js).


## Access your LinkedIn Developer account

*   Go to [LinkedIn Developer Dashboard](https://www.linkedin.com/developers/apps).
*   Log in (if necessary.)

![LinkedIn Developer Portal](/docs/img/guides/auth-linkedin/linkedin_developers_page.png)


## Find your callback URL


## Create a LinkedIn OAuth app

*   Go to [LinkedIn Developer Dashboard](https://www.linkedin.com/developers/apps).
*   Click on `Create App` at the top right
*   Enter your `LinkedIn Page` and `App Logo`
*   Save your app
*   Click `Products` from the top menu
*   Look for `Sign In with LinkedIn using OpenID Connect` and click on Request Access
*   Click `Auth` from the top menu
*   Add your `Redirect URL` to the `Authorized Redirect URLs for your app` section
*   Copy and save your newly-generated `Client ID`
*   Copy and save your newly-generated `Client Secret`

Ensure that the appropriate scopes have been added under OAuth 2.0 Scopes at the bottom of the `Auth` screen.

![Required OAuth 2.0 Scopes](/docs/img/guides/auth-linkedin/oauth-scopes.png)


## Enter your LinkedIn (OIDC) credentials into your Supabase project


## Add login code to your client app


## LinkedIn Open ID Connect (OIDC)

We will be replacing the *LinkedIn* provider with a new *LinkedIn (OIDC)* provider to support recent changes to the LinkedIn [OAuth APIs](https://learn.microsoft.com/en-us/linkedin/shared/authentication/authorization-code-flow?context=linkedin%2Fcontext\&tabs=HTTPS1). The new provider utilizes the [Open ID Connect standard](https://learn.microsoft.com/en-us/linkedin/consumer/integrations/self-serve/sign-in-with-linkedin-v2#validating-id-tokens). In view of this change, we have disabled edits on the *LinkedIn* provider and will be removing it effective 4th January 2024. Developers with LinkedIn OAuth Applications created prior to 1st August 2023 should create a new OAuth application [via the steps outlined above](/docs/guides/auth/social-login/auth-linkedin#create-a-linkedin-oauth-app) and migrate their credentials from the *LinkedIn* provider to the *LinkedIn (OIDC)* provider. Alternatively, you can also head to the `Products` section and add the newly release`Sign In with LinkedIn using OpenID Connect` to your existing OAuth application.

Developers using the Supabase CLI to test their LinkedIn OAuth application should also update their `config.toml` to make use of the new provider:

    [auth.external.linkedin_oidc]
    enabled = true
    client_id = ...
    secret = ...

Do reach out to support if you have any concerns around this change.


## Resources

*   [Supabase - Get started for free](https://supabase.com)
*   [Supabase JS Client](https://github.com/supabase/supabase-js)
*   [LinkedIn Developer Dashboard](https://api.LinkedIn.com/apps)


# Login with Notion



To enable Notion Auth for your project, you need to set up a Notion Application and add the Application OAuth credentials to your Supabase Dashboard.


## Overview

Setting up Notion logins for your application consists of 3 parts:

*   Create and configure a Notion Application [Notion Developer Portal](https://www.notion.so/my-integrations)
*   Retrieve your OAuth client ID and OAuth client secret and add them to your [Supabase Project](https://supabase.com/dashboard)
*   Add the login code to your [Supabase JS Client App](https://github.com/supabase/supabase-js)


## Create your notion integration

*   Go to [developers.notion.com](https://developers.notion.com/).

*   Click "View my integrations" and login.
    ![notion.so](/docs/img/guides/auth-notion/notion.png)

*   Once logged in, go to [notion.so/my-integrations](https://notion.so/my-integrations) and create a new integration.

*   When creating your integration, ensure that you select "Public integration" under "Integration type" and "Read user information including email addresses" under "Capabilities".

*   You will need to add a redirect URI, see [Add the redirect URI](#add-the-redirect-uri)

*   Once you've filled in the necessary fields, click "Submit" to finish creating the integration.

![notion.so](/docs/img/guides/auth-notion/notion-developer.png)


## Add the redirect URI

*   After selecting "Public integration", you should see an option to add "Redirect URIs".

![notion.so](/docs/img/guides/auth-notion/notion-redirect-uri.png)


## Add your Notion credentials into your Supabase project

*   Once you've created your notion integration, you should be able to retrieve the "OAuth client ID" and "OAuth client secret" from the "OAuth Domain and URIs" tab.

![notion.so](/docs/img/guides/auth-notion/notion-creds.png)


## Add login code to your client app


## Resources

*   [Supabase - Get started for free](https://supabase.com)
*   [Supabase JS Client](https://github.com/supabase/supabase-js)
*   [Notion Account](https://notion.so)
*   [Notion Developer Portal](https://www.notion.so/my-integrations)


# Login with Slack



To enable Slack Auth for your project, you need to set up a Slack OAuth application and add the application credentials to your Supabase Dashboard.


## Overview

Setting up Slack logins for your application consists of 3 parts:

*   Create and configure a Slack Project and App on the [Slack Developer Dashboard](https://api.slack.com/apps).
*   Add your Slack `API Key` and `API Secret Key` to your [Supabase Project](https://supabase.com/dashboard).
*   Add the login code to your [Supabase JS Client App](https://github.com/supabase/supabase-js).


## Access your Slack Developer account

*   Go to [api.slack.com](https://api.slack.com/apps).
*   Click on `Your Apps` at the top right to log in.

![Slack Developer Portal.](/docs/img/guides/auth-slack/slack-portal.png)


## Find your callback URL


## Create a Slack OAuth app

*   Go to [api.slack.com](https://api.slack.com/apps).
*   Click on `Create New App`

Under `Create an app...`:

*   Click `From scratch`
*   Type the name of your app
*   Select your `Slack Workspace`
*   Click `Create App`

Under `App Credentials`:

*   Copy and save your newly-generated `Client ID`
*   Copy and save your newly-generated `Client Secret`

Under the sidebar, select `OAuth & Permissions` and look for `Redirect URLs`:

*   Click `Add New Redirect URL`
*   Paste your `Callback URL` then click `Add`
*   Click `Save URLs`

Under `Scopes`:

*   Add the following scopes under the `User Token Scopes`: `profile`, `email`, `openid`. These scopes are the default scopes that Supabase Auth uses to request for user information. Do not add other scopes as [Sign In With Slack only supports `profile`, `email`, `openid`](https://api.slack.com/authentication/sign-in-with-slack#request).


## Enter your Slack credentials into your Supabase project


## Add login code to your client app


## Resources

*   [Supabase - Get started for free](https://supabase.com)
*   [Supabase JS Client](https://github.com/supabase/supabase-js)
*   [Slack Developer Dashboard](https://api.slack.com/apps)


# Login with Spotify



To enable Spotify Auth for your project, you need to set up a Spotify OAuth application and add the application credentials to your Supabase Dashboard.


## Overview

Setting up Spotify logins for your application consists of 3 parts:

*   Create and configure a Spotify Project and App on the [Spotify Developer Dashboard](https://developer.spotify.com/dashboard/).
*   Add your Spotify `API Key` and `API Secret Key` to your [Supabase Project](https://supabase.com/dashboard).
*   Add the login code to your [Supabase JS Client App](https://github.com/supabase/supabase-js).


## Access your Spotify Developer account

*   Log into [Spotify](https://spotify.com)
*   Access the [Spotify Developer Dashboard](https://developer.spotify.com/dashboard)

![Spotify Developer Portal.](/docs/img/guides/auth-spotify/spotify-portal.png)


## Find your callback URL


## Create a Spotify OAuth app

*   Log into [Spotify](https://spotify.com).
*   Go to the [Spotify Developer Dashboard](https://developer.spotify.com/dashboard)
*   Click `Create an App`
*   Type your `App name`
*   Type your `App description`
*   Check the box to agree with the `Developer TOS and Branding Guidelines`
*   Click `Create`
*   Save your `Client ID`
*   Save your `Client Secret`
*   Click `Edit Settings`

Under `Redirect URIs`:

*   Paste your Supabase Callback URL in the box
*   Click `Add`
*   Click `Save` at the bottom


## Enter your Spotify credentials into your Supabase project


## Add login code to your client app

The following outlines the steps to sign in using Spotify with Supabase Auth.

1.  Call the signin method from the client library.
2.  The user is redirected to the Spotify login page.
3.  After completing the sign-in process, the user will be redirected to your app with an error that says the email address needs to be confirmed. Simultaneously the user receives a confirmation email from Supabase Auth.
4.  The user clicks the confirmation link in the email.
5.  The user is brought back to the app and is now signed in.


## Resources

*   [Supabase - Get started for free](https://supabase.com)
*   [Supabase JS Client](https://github.com/supabase/supabase-js)
*   [Spotify Developer Dashboard](https://developer.spotify.com/dashboard/)


# Login with Twitch



To enable Twitch Auth for your project, you need to set up a Twitch Application and add the Application OAuth credentials to your Supabase Dashboard.


## Overview

Setting up Twitch logins for your application consists of 3 parts:

*   Create and configure a Twitch Application [Twitch Developer Console](https://dev.twitch.tv/console)
*   Add your Twitch OAuth Consumer keys to your [Supabase Project](https://supabase.com/dashboard)
*   Add the login code to your [Supabase JS Client App](https://github.com/supabase/supabase-js)


## Access your Twitch Developer account

*   Go to [dev.twitch.tv](https://dev.twitch.tv).
*   Click on `Log in with Twitch` at the top right to log in.
*   If you have not already enabled 2-Factor Authentication for your Twitch Account, you will need to do that at [Twitch Security Settings](https://www.twitch.tv/settings/security) before you can continue.

![Twitch Developer Page](/docs/img/guides/auth-twitch/twitch-developer-page.png)

*   Once logged in, go to the [Twitch Developer Console](https://dev.twitch.tv/console).

![Twitch Developer Console](/docs/img/guides/auth-twitch/twitch-console.png)


## Find your callback URL


## Create a Twitch application

![Twitch Developer Console](/docs/img/guides/auth-twitch/twitch-console.png)

*   Click on `+ Register Your Application` at the top right.

![Register Application](/docs/img/guides/auth-twitch/twitch-register-your-application.png)

*   Enter the name of your application.
*   Type or paste your `OAuth Redirect URL` (the callback URL from the previous step.)
*   Select a category for your app.
*   Check the CAPTCHA box and click `Create`.


## Retrieve your Twitch OAuth client ID and client secret

*   Click `Manage` at the right of your application entry in the list.

![Twitch Applications List](/docs/img/guides/auth-twitch/twitch-applications-list.png)

*   Copy your Client ID.
*   Click `New Secret` to create a new Client Secret.
*   Copy your Client Secret.

![Get Client ID and Secret](/docs/img/guides/auth-twitch/twitch-get-keys.png)


## Add your Twitch credentials into your Supabase project


## Add login code to your client app


## Resources

*   [Supabase - Get started for free](https://supabase.com)
*   [Supabase JS Client](https://github.com/supabase/supabase-js)
*   [Twitch Account](https://twitch.tv)
*   [Twitch Developer Console](https://dev.twitch.tv/console)


# Login with Twitter



To enable Twitter Auth for your project, you need to set up a Twitter OAuth application and add the application credentials in the Supabase Dashboard.


## Overview

Setting up Twitter logins for your application consists of 3 parts:

*   Create and configure a Twitter Project and App on the [Twitter Developer Dashboard](https://developer.twitter.com/en/portal/dashboard).
*   Add your Twitter `API Key` and `API Secret Key` to your [Supabase Project](https://supabase.com/dashboard).
*   Add the login code to your [Supabase JS Client App](https://github.com/supabase/supabase-js).


## Access your Twitter Developer account

*   Go to [developer.twitter.com](https://developer.twitter.com).
*   Click on `Sign in` at the top right to log in.

![Twitter Developer Portal.](/docs/img/guides/auth-twitter/twitter-portal.png)


## Find your callback URL


## Create a Twitter OAuth app

*   Click `+ Create Project`.
    *   Enter your project name, click `Next`.
    *   Select your use case, click `Next`.
    *   Enter a description for your project, click `Next`.
    *   Enter a name for your app, click `Next`.
    *   Copy and save your `API Key` (this is your `client_id`).
    *   Copy and save your `API Secret Key` (this is your `client_secret`).
    *   Click on `App settings` to proceed to next steps.
*   At the bottom, you will find `User authentication settings`. Click on `Set up`.
*   Under `User authentication settings`, you can configure `App permissions`.
*   Make sure you turn ON `Request email from users`.
*   Select `Web App...` as the `Type of App`.
*   Under `App info` configure the following.
    *   Enter your `Callback URL`. Check the **Find your callback URL** section above to learn how to obtain your callback URL.
    *   Enter your `Website URL` (tip: try `http://127.0.0.1:port` or `http://www.localhost:port` during development)
    *   Enter your `Terms of service URL`.
    *   Enter your `Privacy policy URL`.
*   Click `Save`.


## Enter your Twitter credentials into your Supabase project


## Add login code to your client app


## Resources

*   [Supabase - Get started for free](https://supabase.com)
*   [Supabase JS Client](https://github.com/supabase/supabase-js)
*   [Twitter Developer Dashboard](https://developer.twitter.com/en/portal/dashboard)


# SSO and Social Login with WorkOS



## Use Social Login with WorkOS


### Step 1. Create a WorkOS organization

Log in to the WorkOS dashboard and visit the Organizations tab to create an organization.
![Create an Organization](/docs/img/guides/auth-workos/workos-create-organization.png)

Alternatively, you can [create an organization via the WorkOS API](https://workos.com/docs/reference/organization/create).


## Step 2. Obtain your `Client ID` and `WORKOS_API_KEY` values

![Get your Environment's Client ID and Secret](/docs/img/guides/auth-workos/workos-dashboard-get-client-id-and-key.png)

Visit the getting started page of the [WorkOS Dashboard](https://dashboard.workos.com/get-started). Copy the following values from the Quickstart panel:

*   `WORKOS_CLIENT_ID`
*   `WORKOS_API_KEY`


## Step 3. Add your WorkOS credentials to your Supabase project

![Enter your WorkOS application details in your Supabase app's auth provider settings panel](/docs/img/guides/auth-workos/supabase-workos-configuration.png)

1.  Go to your Supabase Project Dashboard.
2.  In the left sidebar, click the Authentication icon (near the top).
3.  Click on Providers under the Configuration section.
4.  Click on WorkOS from the accordion list to expand.
5.  Toggle the `WorkOS Enabled` switch to ON.
6.  Enter `https://api.workos.com` in the WorkOS URL field.
7.  Enter your WorkOS Client ID and WorkOS Client Secret saved in the previous step.
8.  Copy the `Callback URL (for OAuth)` value from the form and save it somewhere handy.
9.  Click Save.


## Step 4. Set your Supabase redirect URI in the WorkOS Dashboard

Visit the WorkOS dashboard and click the redirects button in the left navigation panel.

On the redirects page, enter your Supabase project's `Callback URL (for OAuth)` which you saved in the previous step, as shown below:

![Set your Supbase project redirect URL in the WorkOS dashboard](/docs/img/guides/auth-workos/workos-set-supabase-redirect.png)


## Step 5. Add login code to your client app

When a user signs in, call `signInWithOAuth` with `workos` as the provider.

```javascript
import { createClient } from '@supabase/supabase-js';
const supabase = createClient('<your-project-url>', '<your-anon-key>');
const redirect = (url: string) => {}

// ---cut---
async function signInWithWorkOS() {
  const { data, error } = await supabase.auth.signInWithOAuth({
    provider: 'workos',
    options: {
      redirectTo: 'http://example.com/auth/v1/callback', // Make sure your redirect URL is configured in the Supabase Dashboard Auth settings
      queryParams: {
        connection: '<connection_id>',
      },
    },
  })

  if (data.url) {
    redirect(data.url) // use the redirect API for your server or framework
  }
}
```

Within your specified callback URL, you'll exchange the code for a logged-in user profile:

```javascript auth/v1/callback/route.ts
import { NextResponse } from 'next/server'
import { createClient } from '@/utils/supabase/server'

export async function GET(request: Request) {
  const { searchParams, origin } = new URL(request.url)
  const code = searchParams.get('code')
  // if "next" is in param, use it as the redirect URL
  const next = searchParams.get('next') ?? '/'

  if (code) {
    const supabase = await createClient()
    const { error } = await supabase.auth.exchangeCodeForSession(code)
    if (!error) {
      const forwardedHost = request.headers.get('x-forwarded-host') // original origin before load balancer
      const isLocalEnv = process.env.NODE_ENV === 'development'
      if (isLocalEnv) {
        // we can be sure that there is no load balancer in between, so no need to watch for X-Forwarded-Host
        return NextResponse.redirect(`${origin}${next}`)
      } else if (forwardedHost) {
        return NextResponse.redirect(`https://${forwardedHost}${next}`)
      } else {
        return NextResponse.redirect(`${origin}${next}`)
      }
    }
  }

  // return the user to an error page with instructions
  return NextResponse.redirect(`${origin}/auth/auth-code-error`)
}

```


## Resources

*   [WorkOS Documentation](https://workos.com/docs/sso/guide)


# Login with Zoom



To enable Zoom Auth for your project, you need to set up a Zoom OAuth application and add the application credentials to your Supabase Dashboard.


## Overview

Setting up Zoom logins for your application consists of 3 parts:

*   Create and configure a Zoom OAuth App on [Zoom App Marketplace](https://marketplace.zoom.us/)
*   Add your Zoom OAuth keys to your [Supabase Project](https://supabase.com/dashboard)
*   Add the login code to your [Supabase JS Client App](https://github.com/supabase/supabase-js)


## Access your Zoom Developer account

*   Go to [marketplace.zoom.us](https://marketplace.zoom.us/).
*   Click on `Sign In` at the top right to log in.

![Zoom Developer Portal.](/docs/img/guides/auth-zoom/zoom-portal.png)


## Find your callback URL


## Create a Zoom OAuth app

*   Go to [marketplace.zoom.us](https://marketplace.zoom.us/).
*   Click on `Sign In` at the top right to log in.
*   Click `Build App` (from the dropdown Develop)
*   In the OAuth card, click `Create`
*   Type the name of your app
*   Choose app type
*   Click `Create`

Under `App credentials`

*   Copy and save your `Client ID`.
*   Copy and save your `Client secret`.
*   Add your `Callback URL` in the OAuth allow list.

Under `Redirect URL for OAuth`

*   Paste your `Callback URL`

Under `Scopes`

*   Click on `Add scopes`
*   Click on `User`
*   Choose `user:read`
*   Click `Done`
*   Click `Continue`


## Enter your Zoom credentials into your Supabase project


## Add login code to your client app


## Resources

*   [Supabase - Get started for free](https://supabase.com)
*   [Supabase JS Client](https://github.com/supabase/supabase-js)
*   [Zoom App Marketplace](https://marketplace.zoom.us/)


# Auth0

Use Auth0 with your Supabase project

Auth0 can be used as a third-party authentication provider alongside Supabase Auth, or standalone, with your Supabase project.


## Getting started

1.  First you need to add an integration to connect your Supabase project with your Auth0 tenant. You will need your tenant ID (and in some cases region ID).
2.  Add a new Third-party Auth integration in your project's [Authentication settings](/dashboard/project/_/settings/auth).
3.  Assign the `role: 'authenticated'` custom claim to all JWTs by using an Auth0 Action.
4.  Finally setup the Supabase client in your application.


## Setup the Supabase client library


## Add a new Third-Party Auth integration to your project

In the dashboard navigate to your project's [Authentication settings](/dashboard/project/_/settings/auth) and find the Third-Party Auth section to add a new integration.

In the CLI add the following config to your `supabase/config.toml` file:

```toml
[auth.third_party.auth0]
enabled = true
tenant = "<id>"
tenant_region = "<region>" # if your tenant has a region
```


## Use an Auth0 Action to assign the authenticated role

Your Supabase project inspects the `role` claim present in all JWTs sent to it, to assign the correct Postgres role when using the Data API, Storage or Realtime authorization.

By default, Auth0 JWTs (both access token and ID token) do not contain a `role` claim in them. If you were to send such a JWT to your Supabase project, the `anon` role would be assigned when executing the Postgres query. Most of your app's logic will be accessible by the `authenticated` role.

A recommended approach to do this is to configure the [`onExecutePostLogin` Auth0 Action](https://auth0.com/docs/secure/tokens/json-web-tokens/create-custom-claims#create-custom-claims) which will add the custom claim:

```javascript
exports.onExecutePostLogin = async (event, api) => {
  api.accessToken.setCustomClaim('role', 'authenticated')
}
```


## Limitations

At this time, Auth0 tenants with the following [signing algorithms](https://auth0.com/docs/get-started/applications/signing-algorithms) are not supported:

*   HS256 (HMAC with SHA-256) -- also known as symmetric JWTs
*   PS256 (RSA-PSS with SHA-256)


# Amazon Cognito (Amplify)

Use Amazon Cognito via Amplify or standalone with your Supabase project

Amazon Cognito User Pools (via AWS Amplify or on its own) can be used as a third-party authentication provider alongside Supabase Auth, or standalone, with your Supabase project.


## Getting started

1.  First you need to add an integration to connect your Supabase project with your Amazon Cognito User Pool. You will need the pool's ID and region.
2.  Add a new Third-party Auth integration in your project's [Authentication settings](/dashboard/project/_/settings/auth) or configure it in the CLI.
3.  Assign the `role: 'authenticated'` custom claim to all JWTs by using a Pre-Token Generation Trigger.
4.  Finally setup the Supabase client in your application.


## Setup the Supabase client library


## Add a new Third-Party Auth integration to your project

In the dashboard navigate to your project's [Authentication settings](/dashboard/project/_/settings/auth) and find the Third-Party Auth section to add a new integration.

In the CLI add the following config to your `supabase/config.toml` file:

```toml
[auth.third_party.aws_cognito]
enabled = true
user_pool_id = "<id>"
user_pool_region = "<region>"
```


## Use a pre-token generation trigger to assign the authenticated role

Your Supabase project inspects the `role` claim present in all JWTs sent to it, to assign the correct Postgres role when using the Data API, Storage or Realtime authorization.

By default, Amazon Cognito JWTs (both ID token and access tokens) do not contain a `role` claim in them. If you were to send such a JWT to your Supabase project, the `anon` role would be assigned when executing the Postgres query. Most of your app's logic will be accessible by the `authenticated` role.

A recommended approach to do this is to configure a [Pre-Token Generation Trigger](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-pre-token-generation.html) either `V1_0` (ID token only) or `V2_0` (both access and ID token). To do this you will need to create a new Lambda function (in any language and runtime) and assign it to the [Amazon Cognito User Pool's Lambda Triggers configuration](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-identity-pools-working-with-aws-lambda-triggers.html). For example, the Lambda function should look similar to this:


# Clerk

Use Clerk with your Supabase project

Clerk can be used as a third-party authentication provider alongside Supabase Auth, or standalone, with your Supabase project.


## Getting started

Getting started is incredibly easy. Start off by visiting [Clerk's Connect with Supabase page](https://dashboard.clerk.com/setup/supabase) to configure your Clerk instance for Supabase compatibility.

Finally add a [new Third-Party Auth integration with Clerk](/dashboard/project/_/auth/third-party) in the Supabase dashboard.


### Configure for local development or self-hosting

When developing locally or self-hosting with the Supabase CLI, add the following config to your `supabase/config.toml` file:

```toml
[auth.third_party.clerk]
enabled = true
domain = "example.clerk.accounts.dev"
```

You will still need to configure your Clerk instance for Supabase compatibility.


### Manually configuring your Clerk instance

If you are not able to use [Clerk's Connect with Supabase page](https://dashboard.clerk.com/setup/supabase) to configure your Clerk instance for working with Supabase, follow these steps.

1.  Add the `role` claim to [Clerk session tokens](https://clerk.com/docs/backend-requests/resources/session-tokens) by [customizing them](https://clerk.com/docs/backend-requests/custom-session-token). End-users who are authenticated should have the `authenticated` value for the claim. If you have an advanced Postgres setup where authenticated end-users use different Postgres roles to access the database, adjust the value to use the correct role name.
2.  Once all Clerk session tokens for your instance contain the `role` claim, add a [new Third-Party Auth integration with Clerk](/dashboard/project/_/auth/third-party) in the Supabase dashboard or register it in the CLI as instructed above.


## Setup the Supabase client library


## Using RLS policies

Once you've configured the Supabase client library to use Clerk session tokens, you can use RLS policies to secure access to your project's database, Storage objects and Realtime channels.

The recommended way to design RLS policies with Clerk is to use claims present in your Clerk session token to allow or reject access to your project's data. Check [Clerk's docs](https://clerk.com/docs/backend-requests/resources/session-tokens) on the available JWT claims and their values.


### Example: Check user organization role

```sql
create policy "Only organization admins can insert in table"
  on table_name
  for insert
  to authenticated
  with check (
    ((select auth.jwt()->>'org_role') = 'org:admin')
      and
    (organization_id = (select auth.jwt()->>'org_id'))
  );
```

This RLS policy checks that the newly inserted row in the table has the user's declared organization ID (from the `org_id` session token claim) in the `organization_id` column. Additionally it ensures that they're an `org:admin`.

This way only organization admins can add rows to the table, for organizations they're a member of.


### Example: Check user has passed second factor verification

```sql
create policy "Only users that have passed second factor verification can read from table"
  on table_name
  for select
  as restrictive
  to authenticated
  using (
    ((select auth.jwt()->'fva'->>1) != '-1')
  );
```

This example uses a restrictive RLS policy checks that the [second factor verification](https://clerk.com/docs/guides/reverification) age element in the `fva` claim is not `'-1'` indicating the user has passed through second factor verification.


## Deprecated integration with JWT templates

As of 1st April 2025 the previously available [Clerk Integration with Supabase](https://supabase.com/partners/integrations/clerk) is considered deprecated and is no longer recommended for use. All projects using the deprecated integration will be excluded from Third-Party Monthly Active User (TP-MAU) charges until at least 1st January 2026.

This integration used low-level primitives that are still available in Supabase and Clerk, such as a [configurable JWT secret](/dashboard/project/_/settings/api) and [JWT templates from Clerk](https://clerk.com/docs/backend-requests/jwt-templates). This enables you to keep using it in an unofficial manner, though only limited support will be provided from Supabase.

Deprecation is done for the following reasons:

*   Sharing your project's JWT secret with a third-party is a problematic security practice
*   Rotating the project's JWT secret in this case almost always results in significant downtime for your application
*   Additional latency to [generate a new JWT](https://clerk.com/docs/backend-requests/jwt-templates#generate-a-jwt) for use with Supabase, instead of using the Clerk [session tokens](https://clerk.com/docs/backend-requests/resources/session-tokens)


# Firebase Auth

Use Firebase Auth with your Supabase project

Firebase Auth can be used as a third-party authentication provider alongside Supabase Auth, or standalone, with your Supabase project.


## Getting started

1.  First you need to add an integration to connect your Supabase project with your Firebase project. You will need to get the Project ID in the [Firebase Console](https://console.firebase.google.com/u/0/project/_/settings/general).
2.  Add a new Third-party Auth integration in your project's [Authentication settings](/dashboard/project/_/settings/auth).
3.  If you are using Third Party Auth when self hosting, create and attach restrictive RLS policies to all tables in your public schema, Storage and Realtime to **prevent unauthorized access from unrelated Firebase projects**.
4.  Assign the `role: 'authenticated'` [custom user claim](https://firebase.google.com/docs/auth/admin/custom-claims) to all your users.
5.  Finally set up the Supabase client in your application.


## Setup the Supabase client library


## Add a new Third-Party Auth integration to your project

In the dashboard navigate to your project's [Authentication settings](/dashboard/project/_/settings/auth) and find the Third-Party Auth section to add a new integration.

In the CLI add the following config to your `supabase/config.toml` file:

```toml
[auth.third_party.firebase]
enabled = true
project_id = "<id>"
```


## Adding an extra layer of security to your project's RLS policies (self-hosting only)

Firebase Auth uses a single set of JWT signing keys for all projects. This means that JWTs issued from an unrelated Firebase project to yours could access data in your Supabase project.

When using the Supabase hosted platform, JWTs coming from Firebase project IDs you have not registered will be rejected before they reach your database. When self-hosting implementing this mechanism is your responsibility. An easy way to guard against this is to create and maintain the following RLS policies for **all of your tables in the `public` schema**. You should also attach this policy to [Storage](/docs/guides/storage/security/access-control) buckets or [Realtime](/docs/guides/realtime/authorization) channels.

It's recommended you use a [restrictive Postgres Row-Level Security policy](https://www.postgresql.org/docs/current/sql-createpolicy.html).

Restrictive RLS policies differ from regular (or permissive) policies in that they use the `as restrictive` clause when being defined. They do not grant permissions, but rather restrict any existing or future permissions. They're great for cases like this where the technical limitations of Firebase Auth remain separate from your app's logic.

This is an example of such an RLS policy that will restrict access to only your project's (denoted with `<firebase-project-id>`) users, and not any other Firebase project.

```sql
create policy "Restrict access to Supabase Auth and Firebase Auth for project ID <firebase-project-id>"
  on table_name
  as restrictive
  to authenticated
  using (
    (auth.jwt()->>'iss' = 'https://<project-ref>.supabase.co/auth/v1')
    or
    (
        auth.jwt()->>'iss' = 'https://securetoken.google.com/<firebase-project-id>'
        and
        auth.jwt()->>'aud' = '<firebase-project-id>'
     )
  );
```

If you have a lot of tables in your app, or need to manage complex RLS policies for [Storage](/docs/guides/storage) or [Realtime](/docs/guides/realtime) it can be useful to define a [stable Postgres function](https://www.postgresql.org/docs/current/xfunc-volatility.html) that performs the check to cut down on duplicate code. For example:

```sql
create function public.is_supabase_or_firebase_project_jwt()
  returns bool
  language sql
  stable
  returns null on null input
  return (
    (auth.jwt()->>'iss' = 'https://<project-ref>.supabase.co/auth/v1')
    or
    (
        auth.jwt()->>'iss' = concat('https://securetoken.google.com/<firebase-project-id>')
        and
        auth.jwt()->>'aud' = '<firebase-project-id>'
     )
  );
```

Make sure you substitute `<project-ref>` with your Supabase project's ID and the `<firebase-project-id>` to your Firebase Project ID. Then the restrictive policies on all your tables, buckets and channels can be simplified to be:

```sql
create policy "Restrict access to correct Supabase and Firebase projects"
  on table_name
  as restrictive
  to authenticated
  using ((select public.is_supabase_or_firebase_project_jwt()) is true);
```


## Assign the "role" custom claim

Your Supabase project inspects the `role` claim present in all JWTs sent to it, to assign the correct Postgres role when using the Data API, Storage or Realtime authorization.

By default, Firebase JWTs do not contain a `role` claim in them. If you were to send such a JWT to your Supabase project, the `anon` role would be assigned when executing the Postgres query. Most of your app's logic will be accessible by the `authenticated` role.


### Use Firebase Authentication functions to assign the authenticated role

You have two choices to set up a Firebase Authentication function depending on your Firebase project's configuration:

1.  Easiest: Use a [blocking Firebase Authentication function](https://firebase.google.com/docs/auth/extend-with-blocking-functions) but this is only available if your project uses [Firebase Authentication with Identity Platform](https://cloud.google.com/security/products/identity-platform).
2.  Manually assign the custom claims to all users with the [admin SDK](https://firebase.google.com/docs/auth/admin/custom-claims#set_and_validate_custom_user_claims_via_the_admin_sdk) and define an [`onCreate` Firebase Authentication Cloud Function](https://firebase.google.com/docs/auth/extend-with-functions) to persist the role to all newly created users.

Finally deploy your functions for the changes to take effect:

    firebase deploy --only functions

Note that these functions are only called on new sign-ups and sign-ins. Existing users will not have these claims in their ID tokens. You will need to use the admin SDK to assign the role custom claim to all users. Make sure you do this after the blocking Firebase Authentication functions as described above are deployed.


### Use the admin SDK to assign the role custom claim to all users

You need to run a script that will assign the `role: 'authenticated'` custom claim to all of your existing Firebase Authentication users. You can do this by combining the [list users](https://firebase.google.com/docs/auth/admin/manage-users#list_all_users) and [set custom user claims](https://firebase.google.com/docs/auth/admin/create-custom-tokens) admin APIs. An example script is provided below:

```javascript
'use strict';
const { initializeApp } = require('firebase-admin/app');
const { getAuth } = require('firebase-admin/auth');
initializeApp();

async function setRoleCustomClaim() => {
  let nextPageToken = undefined

  do {
    const listUsersResult = await getAuth().listUsers(1000, nextPageToken)

    nextPageToken = listUsersResult.pageToken

    await Promise.all(listUsersResult.users.map(async (userRecord) => {
      try {
        await getAuth().setCustomUserClaims(userRecord.id, {
          role: 'authenticated'
        })
      } catch (error) {
        console.error('Failed to set custom role for user', userRecord.id)
      }
    })
  } while (nextPageToken);
};

setRoleCustomClaim().then(() => process.exit(0))
```

After all users have received the `role: 'authenticated'` claim, it will appear in all newly issued ID tokens for the user.


# Third-party auth

First-class support for authentication providers

Supabase has first-class support for these third-party authentication providers:

*   [Clerk](/docs/guides/auth/third-party/clerk)
*   [Firebase Auth](/docs/guides/auth/third-party/firebase-auth)
*   [Auth0](/docs/guides/auth/third-party/auth0)
*   [AWS Cognito (with or without AWS Amplify)](/docs/guides/auth/third-party/aws-cognito)

You can use these providers alongside Supabase Auth, or on their own, to access the [Data API (REST and GraphQL)](/docs/guides/database), [Storage](/docs/guides/storage), [Realtime](/docs/guides/storage) and [Functions](/docs/guides/functions) from your existing apps.

If you already have production apps using one of these authentication providers, and would like to use a Supabase feature, you no longer need to migrate your users to Supabase Auth or use workarounds like translating JWTs into the Supabase Auth format and using your project's signing secret.


## How does it work?

To use Supabase products like Data APIs for your Postgres database, Storage or Realtime, you often need to send access tokens or JWTs via the Supabase client libraries or via the REST API. Third-party auth support means that when you add a new integration with one of these providers, the API will trust JWTs issued by the provider similar to how it trusts JWTs issued by Supabase Auth.

This is made possible if the providers are using JWTs signed with asymmetric keys, which means that the Supabase APIs will be able to only verify but not create JWTs.


## Limitations

There are some limitations you should be aware of when using third-party authentication providers with Supabase.

1.  The third-party provider must use asymmetrically signed JWTs (exposed as an OIDC Issuer Discovery URL by the third-party authentication provider). Using symmetrically signed JWTs is not possible at this time.
2.  The JWT signing keys from the third-party provider are stored in the configuration of your project, and are checked for changes periodically. If you are rotating your keys (when supported) allow up to 30 minutes for the change to be picked up.
3.  It is not possible to disable Supabase Auth at this time.


## Pricing

For a detailed breakdown of how charges are calculated, refer to [Manage Monthly Active Third-Party Users usage](/docs/guides/platform/manage-your-usage/monthly-active-users-third-party).


# Users



A **user** in Supabase Auth is someone with a user ID, stored in the Auth schema. Once someone is a user, they can be issued an Access Token, which can be used to access Supabase endpoints. The token is tied to the user, so you can restrict access to resources via [RLS policies](/docs/guides/database/postgres/row-level-security).


## Permanent and anonymous users

Supabase distinguishes between permanent and anonymous users.

*   **Permanent users** are tied to a piece of Personally Identifiable Information (PII), such as an email address, a phone number, or a third-party identity. They can use these identities to sign back into their account after signing out.
*   **Anonymous users** aren't tied to any identities. They have a user ID and a personalized Access Token, but they have no way of signing back in as the same user if they are signed out.

Anonymous users are useful for:

*   E-commerce applications, to create shopping carts before checkout
*   Full-feature demos without collecting personal information
*   Temporary or throw-away accounts

See the [Anonymous Signins guide](/docs/guides/auth/auth-anonymous) to learn more about anonymous users.


## The user object

The user object stores all the information related to a user in your application. The user object can be retrieved using one of these methods:

1.  [`supabase.auth.getUser()`](/docs/reference/javascript/auth-getuser)
2.  Retrieve a user object as an admin using [`supabase.auth.admin.getUserById()`](/docs/reference/javascript/auth-admin-listusers)

A user can sign in with one of the following methods:

*   Password-based method (with email or phone)
*   Passwordless method (with email or phone)
*   OAuth
*   SAML SSO

An identity describes the authentication method that a user can use to sign in. A user can have multiple identities. These are the types of identities supported:

*   Email
*   Phone
*   OAuth
*   SAML

The user object contains the following attributes:

| Attributes         | Type             | Description                                                                                                                                                                                                                                          |
| ------------------ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id                 | `string`         | The unique id of the identity of the user.                                                                                                                                                                                                           |
| aud                | `string`         | The audience claim.                                                                                                                                                                                                                                  |
| role               | `string`         | The role claim used by Postgres to perform Row Level Security (RLS) checks.                                                                                                                                                                          |
| email              | `string`         | The user's email address.                                                                                                                                                                                                                            |
| email\_confirmed\_at | `string`         | The timestamp that the user's email was confirmed. If null, it means that the user's email is not confirmed.                                                                                                                                         |
| phone              | `string`         | The user's phone number.                                                                                                                                                                                                                             |
| phone\_confirmed\_at | `string`         | The timestamp that the user's phone was confirmed. If null, it means that the user's phone is not confirmed.                                                                                                                                         |
| confirmed\_at       | `string`         | The timestamp that either the user's email or phone was confirmed. If null, it means that the user does not have a confirmed email address and phone number.                                                                                         |
| last\_sign\_in\_at    | `string`         | The timestamp that the user last signed in.                                                                                                                                                                                                          |
| app\_metadata       | `object`         | The `provider` attribute indicates the first provider that the user used to sign up with. The `providers` attribute indicates the list of providers that the user can use to login with.                                                             |
| user\_metadata      | `object`         | Defaults to the first provider's identity data but can contain additional custom user metadata if specified. Refer to [**User Identity**](/docs/guides/auth/auth-identity-linking#the-user-identity) for more information about the identity object. |
| identities         | `UserIdentity[]` | Contains an object array of identities linked to the user.                                                                                                                                                                                           |
| created\_at         | `string`         | The timestamp that the user was created.                                                                                                                                                                                                             |
| updated\_at         | `string`         | The timestamp that the user was last updated.                                                                                                                                                                                                        |
| is\_anonymous       | `boolean`        | Is true if the user is an anonymous user.                                                                                                                                                                                                            |


## Resources

*   [User Management guide](/docs/guides/auth/managing-user-data)


# Local Dev with CLI

Developing locally using the Supabase CLI.

You can use the Supabase CLI to run the entire Supabase stack locally on your machine, by running `supabase init` and then `supabase start`. To install the CLI, see the [installation guide](/docs/guides/cli/getting-started#installing-the-supabase-cli).

The Supabase CLI provides tools to develop your project locally, deploy to the Supabase Platform, handle database migrations, and generate types directly from your database schema.


## Resources


# Cron

Schedule Recurring Jobs with Cron Syntax in Postgres

Supabase Cron is a Postgres Module that simplifies scheduling recurring Jobs with cron syntax and monitoring Job runs inside Postgres.

Cron Jobs can be created via SQL or the Cron interface inside of Supabase Dashboard and can run anywhere from every second to once a year depending on your use case.

Every Job can run SQL snippets or database functions with zero network latency or make an HTTP request, such as invoking a Supabase Edge Function, with ease.


## How does Cron work?

Under the hood, Supabase Cron uses the [`pg_cron`](https://github.com/citusdata/pg_cron) Postgres database extension which is the scheduling and execution engine for your Jobs.

The extension creates a `cron` schema in your database and all Jobs are stored on the `cron.job` table. Every Job's run and its status is recorded on the `cron.job_run_details` table.

The Supabase Dashboard provides and interface for you to schedule Jobs and monitor Job runs. You can also do the same with SQL.


## Resources

*   [`pg_cron` GitHub Repository](https://github.com/citusdata/pg_cron)


# Install



Install the Supabase Cron Postgres Module to begin scheduling recurring Jobs.


## Uninstall

Uninstall Supabase Cron by disabling the `pg_cron` extension:

```sql
drop extension if exists pg_cron;
```


# Quickstart



## Schedule a job


## Edit a job


## Activate/Deactivate a job


## Unschedule a job


## Inspecting job runs


## Examples


### Delete data every week

Delete old data every Saturday at 3:30AM (GMT):

```sql
select cron.schedule (
  'saturday-cleanup', -- name of the cron job
  '30 3 * * 6', -- Saturday at 3:30AM (GMT)
  $$ delete from events where event_time < now() - interval '1 week' $$
);
```


### Run a vacuum every day

Vacuum every day at 3:00AM (GMT):

```sql
select cron.schedule('nightly-vacuum', '0 3 * * *', 'VACUUM');
```


### Call a database function every 5 minutes

Create a [`hello_world()`](/docs/guides/database/functions?language=sql#simple-functions) database function and then call it every 5 minutes:

```sql
select cron.schedule('call-db-function', '*/5 * * * *', 'SELECT hello_world()');
```


### Call a database stored procedure

To use a stored procedure, you can call it like this:

```sql
select cron.schedule('call-db-procedure', '*/5 * * * *', 'CALL my_procedure()');
```


### Invoke Supabase Edge Function every 30 seconds

Make a POST request to a Supabase Edge Function every 30 seconds:

```sql
select
  cron.schedule(
    'invoke-function-every-half-minute',
    '30 seconds',
    $$
    select
      net.http_post(
          url:='https://project-ref.supabase.co/functions/v1/function-name',
          headers:=jsonb_build_object('Content-Type','application/json', 'Authorization', 'Bearer ' || 'YOUR_ANON_KEY'),
          body:=jsonb_build_object('time', now() ),
          timeout_milliseconds:=5000
      ) as request_id;
    $$
  );
```


## Caution: Scheduling system maintenance

Be extremely careful when setting up Jobs for system maintenance tasks as they can have unintended consequences.

For instance, scheduling a command to terminate idle connections with `pg_terminate_backend(pid)` can disrupt critical background processes like nightly backups. Often, there is an existing Postgres setting, such as `idle_session_timeout`, that can perform these common maintenance tasks without the risk.

Reach out to [Supabase Support](https://supabase.com/support) if you're unsure if that applies to your use case.


# Working With Arrays



Postgres supports flexible [array types](https://www.postgresql.org/docs/12/arrays.html). These arrays are also supported in the Supabase Dashboard and in the JavaScript API.


## Create a table with an array column

Create a test table with a text array (an array of strings):


## Insert a record with an array value


## View the results


## Query array data

Postgres uses 1-based indexing (e.g., `textarray[1]` is the first item in the array).


## Resources

*   [Supabase JS Client](https://github.com/supabase/supabase-js)
*   [Supabase - Get started for free](https://supabase.com)
*   [Postgres Arrays](https://www.postgresql.org/docs/15/arrays.html)


# Connecting with Beekeeper Studio



[`Beekeeper Studio Community`](https://www.beekeeperstudio.io/get-community) is a free GUI tool for interacting with databases.


# Connect to your database

Connect to Postgres from your frontend, backend, or serverless environment

## Quick summary

How you connect to your database depends on where you're connecting from:

*   For frontend applications, use the [Data API](#data-apis-and-client-libraries)
*   For Postgres clients, use a connection string
    *   For single sessions (for example, database GUIs) or Postgres native commands (for example, using client applications like [pg\_dump](https://www.postgresql.org/docs/current/app-pgdump.html) or specifying connections for [replication](/docs/guides/database/postgres/setup-replication-external)) use the [direct connection string](#direct-connection) if your environment supports IPv6
    *   For persistent clients, and support for both IPv4 and IPv6, use [Supavisor session mode](#supavisor-session-mode)
    *   For temporary clients (for example, serverless or edge functions) use [Supavisor transaction mode](#supavisor-transaction-mode)


## Quickstarts


## Data APIs and client libraries

The Data APIs allow you to interact with your database using REST or GraphQL requests. You can use these APIs to fetch and insert data from the frontend, as long as you have [RLS](/docs/guides/database/postgres/row-level-security) enabled.

*   [REST](/docs/guides/api)
*   [GraphQL](/docs/guides/graphql/api)

For convenience, you can also use the Supabase client libraries, which wrap the Data APIs with a developer-friendly interface and automatically handle authentication:

*   [JavaScript](/docs/reference/javascript)
*   [Flutter](/docs/reference/dart)
*   [Swift](/docs/reference/swift)
*   [Python](/docs/reference/python)
*   [C#](/docs/reference/csharp)
*   [Kotlin](/docs/reference/kotlin)


## Direct connection

The direct connection string connects directly to your Postgres instance. It is ideal for persistent servers, such as virtual machines (VMs) and long-lasting containers. Examples include AWS EC2 machines, Fly.io VMs, and DigitalOcean Droplets.

The connection string looks like this:

    postgresql://postgres:[YOUR-PASSWORD]@db.apbkobhfnmcqqzqeeqss.supabase.co:5432/postgres

Get your project's direct string from the [Database Settings](/dashboard/project/_/settings/database) page:

1.  Go to the `Settings` section.
2.  Click `Database`.
3.  Under `Connection string`, make sure `Display connection pooler` is unchecked. Copy the URI.


## Shared pooler

Every Supabase project includes a free, shared connection pooler. This is ideal for persistent servers when IPv6 is not supported.


### Supavisor session mode

The session mode connection string connects to your Postgres instance via a proxy.

The connection string looks like this:

    postgres://postgres.apbkobhfnmcqqzqeeqss:[YOUR-PASSWORD]@aws-0-[REGION].pooler.supabase.com:5432/postgres

Get your project's session mode string from the [Database Settings](/dashboard/project/_/settings/database) page:

1.  Go to the `Settings` section.
2.  Click `Database`.
3.  Under `Connection string`, make sure `Display connection pooler` is checked and `Session mode` is selected. Copy the URI.


### Supavisor transaction mode

The transaction mode connection string connects to your Postgres instance via a proxy which serves as a connection pooler. This is ideal for serverless or edge functions, which require many transient connections.

The connection string looks like this:

    postgres://postgres.apbkobhfnmcqqzqeeqss:[YOUR-PASSWORD]@aws-0-[REGION].pooler.supabase.com:6543/postgres

Get your project's transaction mode string from the [Database Settings](/dashboard/project/_/settings/database) page:

1.  Go to the `Settings` section.
2.  Click `Database`.
3.  Under `Connection string`, make sure `Display connection pooler` is checked and `Transaction mode` is selected. Copy the URI.


## Dedicated pooler

For paying customers, we provision a Dedicated Pooler ([PgBouncer](https://www.pgbouncer.org/)) that's co-located with your Postgres database. This will require you to connect with IPv6 or, if that's not an option, you can use the [IPv4 add-on](/docs/guides/platform/ipv4-address).

The Dedicated Pooler ensures best performance and latency, while using up more of your project's compute resources. If your network supports IPv6 or you have the IPv4 add-on, we encourage you to use the Dedicated Pooler over the Shared Pooler.


## More about connection pooling

Connection pooling improves database performance by reusing existing connections between queries. This reduces the overhead of establishing connections and improves scalability.

You can use an application-side pooler or a server-side pooler (Supabase automatically provides one called Supavisor), depending on whether your backend is persistent or serverless.


### Application-side poolers

Application-side poolers are built into connection libraries and API servers, such as Prisma, SQLAlchemy, and PostgREST. They maintain several active connections with Postgres or a server-side pooler, reducing the overhead of establishing connections between queries. When deploying to static architecture, such as long-standing containers or VMs, application-side poolers are satisfactory on their own.


### Serverside poolers

Postgres connections are like a WebSocket. Once established, they are preserved until the client (application server) disconnects. A server might only make a single 10 ms query, but needlessly reserve its database connection for seconds or longer.

Serverside-poolers, such as Supabase's [Supavisor](https://github.com/supabase/supavisor) in transaction mode, sit between clients and the database and can be thought of as load balancers for Postgres connections.

They maintain hot connections with the database and intelligently share them with clients only when needed, maximizing the amount of queries a single connection can service. They're best used to manage queries from auto-scaling systems, such as edge and serverless functions.


## Connecting with SSL

You should connect to your database using SSL wherever possible, to prevent snooping and man-in-the-middle attacks.

You can obtain your connection info and Server root certificate from your application's dashboard:

![Connection Info and Certificate.](/docs/img/database/database-settings-ssl.png)


## Resources

*   [Connection management](/docs/guides/database/connection-management)


# Serverless Drivers

Connecting to your Postgres database in serverless environments.

Supabase provides several options for connecting to your Postgres database from serverless environments.

[supabase-js](/docs/reference/javascript/introduction) is an isomorphic JavaScript client that uses the [auto-generated REST API](/docs/guides/api) and therefore works in any environment that supports HTTPS connections. This API has a built-in [connection pooler](/docs/guides/database/connecting-to-postgres#connection-pooler) and can serve thousands of simultaneous requests, and therefore is ideal for Serverless workloads.


## Vercel Edge Functions

Vercel's [Edge runtime](https://vercel.com/docs/functions/runtimes/edge-runtime) is built on top of the [V8 engine](https://v8.dev/), that provides a limited set of Web Standard APIs.


### Quickstart

Choose one of these Vercel Deploy Templates which use our [Vercel Deploy Integration](https://vercel.com/integrations/supabase) to automatically configure your connection strings as environment variables on your Vercel project!


### Manual configuration

In your [`Database Settings`](https://supabase.com/dashboard/project/_/settings/database), make sure `Use connection pooler` is checked and `Transaction` mode is selected, then copy the URI and save it as the `POSTGRES_URL` environment variable. Remember to replace the password placeholder with your actual database password and add the following suffix `?workaround=supabase-pooler.vercel`.

```txt .env.local
POSTGRES_URL="postgres://postgres.cfcxynqnhdybqtbhjemm:[YOUR-PASSWORD]@aws-0-ap-southeast-1.pooler.supabase.com:6543/postgres?workaround=supabase-pooler.vercel"
```


## Cloudflare Workers

Cloudflare's Workers runtime also uses the [V8 engine](https://v8.dev/) but provides polyfills for a subset of Node.js APIs and [TCP Sockets API](https://developers.cloudflare.com/workers/runtime-apis/tcp-sockets/), giving you a couple of options:

*   [supabase-js](https://developers.cloudflare.com/workers/databases/native-integrations/supabase/)
*   [Postgres.js](https://github.com/porsager/postgres?tab=readme-ov-file#cloudflare-workers-support)
*   [node-postgres](https://developers.cloudflare.com/workers/tutorials/postgres/)


## Supabase Edge Functions

Supabase Edge Functions uses the [Deno runtime](https://deno.com/) which has native support for TCP connections allowing you to choose your favorite client:

*   [supabase-js](/docs/guides/functions/connect-to-postgres#using-supabase-js)
*   [Deno Postgres driver](/docs/guides/functions/connect-to-postgres#using-a-postgres-client)
*   [Postgres.js](https://github.com/porsager/postgres)
*   [Drizzle](/docs/guides/functions/connect-to-postgres#using-drizzle)


# Connection management

Using your connections resourcefully

## Connections

Every [Compute Add-On](/docs/guides/platform/compute-add-ons) has a pre-configured direct connection count and Supavisor pool size. This guide discusses ways to observe and manage them resourcefully.


### Configuring Supavisor's pool size

You can change how many database connections Supavisor can manage by altering the pool size in the "Connection pooling configuration" section of the [Database Settings](/dashboard/project/_/settings/database):

![Connection Info and Certificate.](/docs/img/database/pool-size.png)

The general rule is that if you are heavily using the PostgREST database API, you should be conscientious about raising your pool size past 40%. Otherwise, you can commit 80% to the pool. This leaves adequate room for the Authentication server and other utilities.

These numbers are generalizations and depends on other Supabase products that you use and the extent of their usage. The actual values depend on your concurrent peak connection usage. For instance, if you were only using 80 connections in a week period and your database max connections is set to 500, then realistically you could allocate the difference of 420 (minus a reasonable buffer) to service more demand.


## Monitoring connections


### Capturing historical usage

Supabase offers a Grafana Dashboard that records and visualizes over 200 project metrics, including connections. For setup instructions, check the [metrics docs](/docs/guides/platform/metrics).

Its "Client Connections" graph displays connections for both Supavisor and Postgres
![client connection graph](/docs/img/database/grafana-connections.png)


### Observing live connections

`pg_stat_activity` is a special view that keeps track of processes being run by your database, including live connections. It's particularly useful for determining if idle clients are hogging connection slots.

Query to get all live connections:

```sql
SELECT
  pg_stat_activity.pid as connection_id,
  ssl,
  datname as database,
  usename as connected_role,
  application_name,
  client_addr as IP,
  query,
  query_start,
  state,
  backend_start
FROM pg_stat_ssl
JOIN pg_stat_activity
ON pg_stat_ssl.pid = pg_stat_activity.pid;
```

Interpreting the query:

| Column             | Description                                         |
| ------------------ | --------------------------------------------------- |
| `connection_id`    | connection id                                       |
| `ssl`              | Indicates if SSL is in use                          |
| `database`         | Name of the connected database (usually `postgres`) |
| `usename`          | Role of the connected user                          |
| `application_name` | Name of the connecting application                  |
| `client_addr`      | IP address of the connecting server                 |
| `query`            | Last query executed by the connection               |
| `query_start`      | Time when the last query was executed               |
| `state`            | Querying state: active or idle                      |
| `backend_start`    | Timestamp of the connection's establishment         |

The username can be used to identify the source:

| Role                         | API/Tool                                                                  |
| ---------------------------- | ------------------------------------------------------------------------- |
| `supabase_admin`             | Used by Supabase for monitoring and by Realtime                           |
| `authenticator`              | Data API (PostgREST)                                                      |
| `supabase_auth_admin`        | Auth                                                                      |
| `supabase_storage_admin`     | Storage                                                                   |
| `supabase_replication_admin` | Synchronizes Read Replicas                                                |
| `postgres`                   | Supabase Dashboard and External Tools (e.g., Prisma, SQLAlchemy, PSQL...) |
| Custom roles defined by user | External Tools (e.g., Prisma, SQLAlchemy, PSQL...)                        |


# Customizing Postgres configs



Each Supabase project is a pre-configured Postgres cluster. You can override some configuration settings to suit your needs. This is an advanced topic, and we don't recommend touching these settings unless it is necessary.


### Viewing settings

To list all Postgres settings and their descriptions, run:

```sql
select * from pg_settings;
```


## Configurable settings


### User-context settings

The [`pg_settings`](https://www.postgresql.org/docs/current/view-pg-settings.html) table's `context` column specifies the requirements for changing a setting. By default, those with a `user` context can be changed at the `role` or `database` level with [SQL](https://supabase.com/dashboard/project/_/sql/).

To list all user-context settings, run:

```sql
select * from pg_settings where context = 'user';
```

As an example, the `statement_timeout` setting can be altered:

```sql
alter database "postgres" set "statement_timeout" TO '60s';
```

To verify the change, execute:

```sql
show "statement_timeout";
```


### Superuser settings

Some settings can only be modified by a superuser. Supabase pre-enables the [`supautils` extension](https://supabase.com/blog/roles-postgres-hooks#setting-up-the-supautils-extension), which allows the `postgres` role to retain certain superuser privileges. It enables modification of the below reserved configurations at the `role` level:

| Setting                              | Description                                                                                                                                                  |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `auto_explain.log_min_duration`      | Logs query plans taking longer than this duration.                                                                                                           |
| `auto_explain.log_nested_statements` | Log nested statements' plans.                                                                                                                                |
| `log_min_messages`                   | Minimum severity level of messages to log.                                                                                                                   |
| `pg_net.ttl`                         | Sets how long the [pg\_net extension](/docs/guides/database/extensions/pg_net) saves responses                                                                |
| `pg_net.batch_size`                  | Sets how many requests the [pg\_net extension](/docs/guides/database/extensions/pg_net) can make per second                                                   |
| `pgaudit.*`                          | Configures the [PGAudit extension](https://supabase.com/docs/guides/database/extensions/pgaudit). The `log_parameter` is still restricted to protect secrets |
| `pgrst.*`                            | [`PostgREST` settings](https://docs.postgrest.org/en/stable/references/configuration.html#db-aggregates-enabled)                                             |
| `plan_filter.*`                      | Configures the [pg\_plan\_filter extension](https://supabase.com/docs/guides/database/extensions/pg_plan_filter)                                               |
| `session_replication_role`           | Sets the session's behavior for triggers and rewrite rules.                                                                                                  |
| `track_io_timing`                    | Collects timing statistics for database I/O activity.                                                                                                        |

For example, to enable `log_nested_statements` for the `postgres` role, execute:

```sql
alter role "postgres" set "auto_explain.log_nested_statements" to 'on';
```

To view the change:

```sql
select
  rolname,
  rolconfig
from pg_roles
where rolname = 'postgres';
```


### CLI configurable settings

While many Postgres parameters are configurable directly, some configurations can be changed with the Supabase CLI at the [`system`](https://www.postgresql.org/docs/current/config-setting.html#CONFIG-SETTING-SQL) level.


#### CLI supported parameters

The following parameters are available for overrides:

1.  [effective\_cache\_size](https://www.postgresql.org/docs/current/runtime-config-query.html#GUC-EFFECTIVE-CACHE-SIZE)
2.  [logical\_decoding\_work\_mem](https://www.postgresql.org/docs/current/runtime-config-resource.html#GUC-LOGICAL-DECODING-WORK-MEM) (CLI only)
3.  [maintenance\_work\_mem](https://www.postgresql.org/docs/current/runtime-config-resource.html#GUC-MAINTENANCE-WORK-MEM)
4.  [max\_connections](https://www.postgresql.org/docs/current/runtime-config-connection.html#GUC-MAX-CONNECTIONS) (CLI only)
5.  [max\_locks\_per\_transaction](https://www.postgresql.org/docs/current/runtime-config-locks.html#GUC-MAX-LOCKS-PER-TRANSACTION) (CLI only)
6.  [max\_parallel\_maintenance\_workers](https://www.postgresql.org/docs/current/runtime-config-resource.html#GUC-MAX-PARALLEL-MAINTENANCE-WORKERS)
7.  [max\_parallel\_workers\_per\_gather](https://www.postgresql.org/docs/current/runtime-config-resource.html#GUC-MAX-PARALLEL-WORKERS-PER-GATHER)
8.  [max\_parallel\_workers](https://www.postgresql.org/docs/current/runtime-config-resource.html#GUC-MAX-PARALLEL-WORKERS)
9.  [max\_replication\_slots](https://www.postgresql.org/docs/current/runtime-config-replication.html#GUC-MAX-REPLICATION-SLOTS) (CLI only)
10. [max\_slot\_wal\_keep\_size](https://www.postgresql.org/docs/current/runtime-config-replication.html#GUC-MAX-SLOT-WAL-KEEP-SIZE) (CLI only)
11. [max\_standby\_archive\_delay](https://www.postgresql.org/docs/current/runtime-config-replication.html#GUC-MAX-STANDBY-ARCHIVE-DELAY) (CLI only)
12. [max\_standby\_streaming\_delay](https://www.postgresql.org/docs/current/runtime-config-replication.html#GUC-MAX-STANDBY-STREAMING-DELAY) (CLI only)
13. [max\_wal\_size](https://www.postgresql.org/docs/current/runtime-config-wal.html#GUC-MAX-WAL-SIZE) (CLI only)
14. [max\_wal\_senders](https://www.postgresql.org/docs/current/runtime-config-replication.html#GUC-MAX-WAL-SENDERS) (CLI only)
15. [max\_worker\_processes](https://www.postgresql.org/docs/current/runtime-config-resource.html#GUC-MAX-WORKER-PROCESSES) (CLI only)
16. [session\_replication\_role](https://www.postgresql.org/docs/current/runtime-config-client.html#GUC-SESSION-REPLICATION-ROLE)
17. [shared\_buffers](https://www.postgresql.org/docs/current/runtime-config-resource.html#GUC-SHARED-BUFFERS) (CLI only)
18. [statement\_timeout](https://www.postgresql.org/docs/current/runtime-config-client.html#GUC-STATEMENT-TIMEOUT)
19. [track\_activity\_query\_size](https://www.postgresql.org/docs/current/runtime-config-statistics.html#GUC-TRACK-ACTIVITY-QUERY-SIZE)
20. [track\_commit\_timestamp](https://www.postgresql.org/docs/current/runtime-config-replication.html#GUC-TRACK-COMMIT-TIMESTAMP)
21. [wal\_keep\_size](https://www.postgresql.org/docs/current/runtime-config-replication.html#GUC-WAL-KEEP-SIZE) (CLI only)
22. [wal\_sender\_timeout](https://www.postgresql.org/docs/current/runtime-config-replication.html#GUC-WAL-SENDER-TIMEOUT) (CLI only)
23. [work\_mem](https://www.postgresql.org/docs/current/runtime-config-resource.html#GUC-WORK-MEM)


#### Managing Postgres configuration with the CLI

To start:

1.  [Install](/docs/guides/resources/supabase-cli) Supabase CLI 1.69.0+.
2.  [Log in](/docs/guides/cli/local-development#log-in-to-the-supabase-cli) to your Supabase account using the CLI.

To update Postgres configurations, use the [`postgres config`](/docs/reference/cli/supabase-postgres-config) command:

```bash
supabase --experimental \
--project-ref <project-ref> \
postgres-config update --config shared_buffers=250MB
```

By default, the CLI will merge any provided config overrides with any existing ones. The `--replace-existing-overrides` flag can be used to instead force all existing overrides to be replaced with the ones being provided:

```bash
supabase --experimental \
--project-ref <project-ref> \
postgres-config update --config max_parallel_workers=3 \
--replace-existing-overrides
```

To delete specific configuration overrides, use the `postgres-config delete` command:

```bash
supabase --experimental \
--project-ref <project-ref> \
postgres-config delete --config shared_buffers,work_mem
```

By default, changing the configuration, whether by updating or deleting, causes the database and all associated read replicas to restart. You can use the `--no-restart` flag to prevent this behavior, and attempt to reload the updated configuration without a restart. Refer to the Postgres documentation to determine if a given parameter can be reloaded without a restart.

```bash
supabase --experimental \
--project-ref <project-ref> \
postgres-config delete --config shared_buffers --no-restart
```


### Resetting to default config

To reset a setting to its default value at the database level:

```sql
-- reset a single setting at the database level
alter database "postgres" set "<setting_name>" to default;

-- reset all settings at the database level
alter database "postgres" reset all;
```

For `role` level configurations, you can run:

```sql
alter role "<role_name>" set "<setting_name>" to default;
```


### Considerations

1.  Changes through the CLI might restart the database causing momentary disruption to existing database connections; in most cases this should not take more than a few seconds. However, you can use the --no-restart flag to bypass the restart and keep the connections intact. Keep in mind that this depends on the specific configuration changes you're making. if the change requires a restart, using the --no-restart flag will prevent the restart but you won't see those changes take effect until a restart is manually triggered. Additionally, some parameters are required to be the same on Primary and Read Replicas; not restarting in these cases can result in read replica failure if the Primary/Read Replicas restart in isolation.
2.  Custom Postgres Config will always override the default optimizations generated by Supabase. When changing compute add-ons, you should also review and update your custom Postgres Config to ensure they remain compatible and effective with the updated compute.
3.  Some parameters (e.g. `wal_keep_size`) can increase disk utilization, triggering disk expansion, which in turn can lead to [increases in your bill](/docs/guides/platform/compute-add-ons#disk-io).


# Connecting with DBeaver



If you do not have DBeaver, you can download it from its [website](https://dbeaver.io/download/).


# Debugging performance issues

Debug slow-running queries using the Postgres execution planner.

`explain()` is a method that provides the Postgres `EXPLAIN` execution plan of a query. It is a powerful tool for debugging slow queries and understanding how Postgres will execute a given query. This feature is applicable to any query, including those made through `rpc()` or write operations.


## Enabling `explain()`

`explain()` is disabled by default to protect sensitive information about your database structure and operations. We recommend using `explain()` in a non-production environment. Run the following SQL to enable `explain()`:

```sql
-- enable explain
alter role authenticator
set pgrst.db_plan_enabled to 'true';

-- reload the config
notify pgrst, 'reload config';
```


## Using `explain()`

To get the execution plan of a query, you can chain the `explain()` method to a Supabase query:

```ts
const { data, error } = await supabase
  .from('instruments')
  .select()
  .explain()
```


### Example data

To illustrate, consider the following setup of a `instruments` table:

```sql
create table instruments (
  id int8 primary key,
  name text
);

insert into books
  (id, name)
values
  (1, 'violin'),
  (2, 'viola'),
  (3, 'cello');
```


### Expected response

The response would typically look like this:

```markdown
Aggregate  (cost=33.34..33.36 rows=1 width=112)
  ->  Limit  (cost=0.00..18.33 rows=1000 width=40)
        ->  Seq Scan on instruments  (cost=0.00..22.00 rows=1200 width=40)
```

By default, the execution plan is returned in TEXT format. However, you can also retrieve it as JSON by specifying the `format` parameter.


## Production use with pre-request protection

If you need to enable `explain()` in a production environment, ensure you protect your database by restricting access to the `explain()` feature. You can do so by using a pre-request function that filters requests based on the IP address:

```sql
create or replace function filter_plan_requests()
returns void as $$
declare
  headers   json := current_setting('request.headers', true)::json;
  client_ip text := coalesce(headers->>'cf-connecting-ip', '');
  accept    text := coalesce(headers->>'accept', '');
  your_ip   text := '123.123.123.123'; -- replace this with your IP
begin
  if accept like 'application/vnd.pgrst.plan%' and client_ip != your_ip then
    raise insufficient_privilege using
      message = 'Not allowed to use application/vnd.pgrst.plan';
  end if;
end; $$ language plpgsql;
alter role authenticator set pgrst.db_pre_request to 'filter_plan_requests';
notify pgrst, 'reload config';
```

Replace `'123.123.123.123'` with your actual IP address.


## Disabling explain

To disable the `explain()` method after use, execute the following SQL commands:

```sql
-- disable explain
alter role authenticator
set pgrst.db_plan_enabled to 'false';

-- if you used the above pre-request
alter role authenticator
set pgrst.db_pre_request to '';

-- reload the config
notify pgrst, 'reload config';
```


# Drizzle



### Connecting with Drizzle

[Drizzle ORM](https://github.com/drizzle-team/drizzle-orm) is a TypeScript ORM for SQL databases designed with maximum type safety in mind. You can use their ORM to connect to your database.


# Postgres Extensions Overview



Extensions are exactly as they sound - they "extend" the database with functionality which isn't part of the Postgres core.
Supabase has pre-installed some of the most useful open source extensions.


### Enable and disable extensions


### Upgrade extensions

If a new version of an extension becomes available on Supabase, you need to initiate a software upgrade in the [Infrastructure Settings](https://supabase.com/dashboard/project/_/settings/infrastructure) to access it. Software upgrades can also be initiated by restarting your server in the [General Settings](https://supabase.com/dashboard/project/_/settings/general).


### Full list of extensions

Supabase is pre-configured with over 50 extensions. You can also install your own SQL extensions directly in the database through our SQL editor.


# http: RESTful Client



The `http` extension allows you to call RESTful endpoints within Postgres.


## Quick demo


## Overview

Let's cover some basic concepts:

*   REST: stands for REpresentational State Transfer. It's a way to request data from external services.
*   RESTful APIs are servers which accept HTTP "calls". The calls are typically:
    *   `GET` − Read only access to a resource.
    *   `POST` − Creates a new resource.
    *   `DELETE` − Removes a resource.
    *   `PUT` − Updates an existing resource or creates a new resource.

You can use the `http` extension to make these network requests from Postgres.


## Usage


### Enable the extension


### Available functions

While the main usage is `http('http_request')`, there are 5 wrapper functions for specific functionality:

*   `http_get()`
*   `http_post()`
*   `http_put()`
*   `http_delete()`
*   `http_head()`


### Returned values

A successful call to a web URL from the `http` extension returns a record with the following fields:

*   `status`: integer
*   `content_type`: character varying
*   `headers`: http\_header\[]
*   `content`: character varying. Typically you would want to cast this to `jsonb` using the format `content::jsonb`


## Examples


### Simple `GET` example

```sql
select
  "status", "content"::jsonb
from
  http_get('https://jsonplaceholder.typicode.com/todos/1');
```


### Simple `POST` example

```sql
select
  "status", "content"::jsonb
from
  http_post(
    'https://jsonplaceholder.typicode.com/posts',
    '{ "title": "foo", "body": "bar", "userId": 1 }',
    'application/json'
  );
```


## Resources

*   Official [`http` GitHub Repository](https://github.com/pramsey/pgsql-http)


# HypoPG: Hypothetical indexes



`HypoPG` is Postgres extension for creating hypothetical/virtual indexes. HypoPG allows users to rapidly create hypothetical/virtual indexes that have no resource cost (CPU, disk, memory) that are visible to the Postgres query planner.

The motivation for HypoPG is to allow users to quickly search for an index to improve a slow query without consuming server resources or waiting for them to build.


## Enable the extension


### Speeding up a query

Given the following table and a simple query to select from the table by `id`:

```sql
create table account (
  id int,
  address text
);

insert into account(id, address)
select
  id,
  id || ' main street'
from
  generate_series(1, 10000) id;
```

We can generate an explain plan for a description of how the Postgres query planner
intends to execute the query.

```sql
explain select * from account where id=1;

                      QUERY PLAN
-------------------------------------------------------
 Seq Scan on account  (cost=0.00..180.00 rows=1 width=13)
   Filter: (id = 1)
(2 rows)
```

Using HypoPG, we can create a hypothetical index on the `account(id)` column to check if it would be useful to the query planner and then re-run the explain plan.

Note that the virtual indexes created by HypoPG are only visible in the Postgres connection that they were created in. Supabase connects to Postgres through a connection pooler so the `hypopg_create_index` statement and the `explain` statement should be executed in a single query.

```sql
select * from hypopg_create_index('create index on account(id)');

explain select * from account where id=1;

                                     QUERY PLAN
------------------------------------------------------------------------------------
 Index Scan using <13504>btree_account_id on hypo  (cost=0.29..8.30 rows=1 width=13)
   Index Cond: (id = 1)
(2 rows)
```

The query plan has changed from a `Seq Scan` to an `Index Scan` using the newly created virtual index, so we may choose to create a real version of the index to improve performance on the target query:

```sql
create index on account(id);
```


## Functions

*   [`hypo_create_index(text)`](https://hypopg.readthedocs.io/en/rel1_stable/usage.html#create-a-hypothetical-index): A function to create a hypothetical index.
*   [`hypopg_list_indexes`](https://hypopg.readthedocs.io/en/rel1_stable/usage.html#manipulate-hypothetical-indexes): A View that lists all hypothetical indexes that have been created.
*   [`hypopg()`](https://hypopg.readthedocs.io/en/rel1_stable/usage.html#manipulate-hypothetical-indexes): A function that lists all hypothetical indexes that have been created with the same format as `pg_index`.
*   [`hypopg_get_index_def(oid)`](https://hypopg.readthedocs.io/en/rel1_stable/usage.html#manipulate-hypothetical-indexes): A function to display the `create index` statement that would create the index.
*   [`hypopg_get_relation_size(oid)`](https://hypopg.readthedocs.io/en/rel1_stable/usage.html#manipulate-hypothetical-indexes): A function to estimate how large a hypothetical index would be.
*   [`hypopg_drop_index(oid)`](https://hypopg.readthedocs.io/en/rel1_stable/usage.html#manipulate-hypothetical-indexes): A function to remove a given hypothetical index by `oid`.
*   [`hypopg_reset()`](https://hypopg.readthedocs.io/en/rel1_stable/usage.html#manipulate-hypothetical-indexes): A function to remove all hypothetical indexes.


## Resources

*   Official [HypoPG documentation](https://hypopg.readthedocs.io/en/rel1_stable/)


# index_advisor: query optimization



[Index advisor](https://github.com/supabase/index_advisor) is a Postgres extension for recommending indexes to improve query performance.

Features:

*   Supports generic parameters e.g. `$1`, `$2`
*   Supports materialized views
*   Identifies tables/columns obfuscated by views
*   Skips duplicate indexes

`index_advisor` is accessible directly through Supabase Studio by navigating to the [Query Performance Report](/dashboard/project/_/advisors/query-performance) and selecting a query and then the "indexes" tab.

![Supabase Studio index\_advisor integration.](/docs/img/index_advisor_studio.png)

Alternatively, you can use index\_advisor directly via SQL.

For example:

```sql
select
    *
from
  index_advisor('select book.id from book where title = $1');

 startup_cost_before | startup_cost_after | total_cost_before | total_cost_after |                  index_statements                   | errors
---------------------+--------------------+-------------------+------------------+-----------------------------------------------------+--------
 0.00                | 1.17               | 25.88             | 6.40             | {"CREATE INDEX ON public.book USING btree (title)"},| {}
(1 row)
```


## Installation

To get started, enable index\_advisor by running

```sql
create extension index_advisor;
```


## API

Index advisor exposes a single function `index_advisor(query text)` that accepts a query and searches for a set of SQL DDL `create index` statements that improve the query's execution time.

The function's signature is:

```sql
index_advisor(query text)
returns
    table  (
        startup_cost_before jsonb,
        startup_cost_after jsonb,
        total_cost_before jsonb,
        total_cost_after jsonb,
        index_statements text[],
        errors text[]
    )
```


## Usage

As a minimal example, the `index_advisor` function can be given a single table query with a filter on an unindexed column.

```sql
create extension if not exists index_advisor cascade;

create table book(
  id int primary key,
  title text not null
);

select
  *
from
  index_advisor('select book.id from book where title = $1');

 startup_cost_before | startup_cost_after | total_cost_before | total_cost_after |                  index_statements                   | errors
---------------------+--------------------+-------------------+------------------+-----------------------------------------------------+--------
 0.00                | 1.17               | 25.88             | 6.40             | {"CREATE INDEX ON public.book USING btree (title)"},| {}
(1 row)
```

and will return a row recommending an index on the unindexed column.

More complex queries may generate additional suggested indexes:

```sql
create extension if not exists index_advisor cascade;

create table author(
    id serial primary key,
    name text not null
);

create table publisher(
    id serial primary key,
    name text not null,
    corporate_address text
);

create table book(
    id serial primary key,
    author_id int not null references author(id),
    publisher_id int not null references publisher(id),
    title text
);

create table review(
    id serial primary key,
    book_id int references book(id),
    body text not null
);

select
    *
from
    index_advisor('
        select
            book.id,
            book.title,
            publisher.name as publisher_name,
            author.name as author_name,
            review.body review_body
        from
            book
            join publisher
                on book.publisher_id = publisher.id
            join author
                on book.author_id = author.id
            join review
                on book.id = review.book_id
        where
            author.id = $1
            and publisher.id = $2
    ');

 startup_cost_before | startup_cost_after | total_cost_before | total_cost_after |                  index_statements                         | errors
---------------------+--------------------+-------------------+------------------+-----------------------------------------------------------+--------
 27.26               | 12.77              | 68.48             | 42.37            | {"CREATE INDEX ON public.book USING btree (author_id)",   | {}
                                                                                    "CREATE INDEX ON public.book USING btree (publisher_id)",
                                                                                    "CREATE INDEX ON public.review USING btree (book_id)"}
(3 rows)
```


## Limitations

*   index\_advisor will only recommend single column, B-tree indexes. More complex indexes will be supported in future releases.
*   when a generic argument's type is not discernible from context, an error is returned in the `errors` field. To resolve those errors, add explicit type casting to the argument. e.g. `$1::int`.


## Resources

*   [`index_advisor`](https://github.com/supabase/index_advisor) repo


# pg_cron: Schedule Recurring Jobs with Cron Syntax in Postgres



See the [Supabase Cron docs](/docs/guides/cron).


# pg_graphql: GraphQL for PostgreSQL



[pg\_graphql](https://supabase.github.io/pg_graphql/) is Postgres extension for interacting with the database using [GraphQL](https://graphql.org) instead of SQL.

The extension reflects a GraphQL schema from the existing SQL schema and exposes it through a SQL function, `graphql.resolve(...)`. This enables any programming language that can connect to Postgres to query the database via GraphQL with no additional servers, processes, or libraries.

The `pg_graphql` resolve method is designed to interop with [PostgREST](https://postgrest.org/en/stable/index.html), the tool that underpins the Supabase API, such that the `graphql.resolve` function can be called via RPC to safely and performantly expose the GraphQL API over HTTP/S.

For more information about how the SQL schema is reflected into a GraphQL schema, see the [pg\_graphql API docs](https://supabase.github.io/pg_graphql/api/).


## Enable the extension


## Usage

Given a table

```sql
create table "Blog"(
  id serial primary key,
  name text not null,
  description text
);

insert into "Blog"(name)
values ('My Blog');
```

The reflected GraphQL schema can be queried immediately as

```sql
select
  graphql.resolve($$
    {
      blogCollection(first: 1) {
        edges {
          node {
            id,
            name
          }
        }
      }
    }
  $$);
```

returning the JSON

```json
{
  "data": {
    "blogCollection": {
      "edges": [
        {
          "node": {
            "id": 1
            "name": "My Blog"
          }
        }
      ]
    }
  }
}
```

Note that `pg_graphql` fully supports schema introspection so you can connect any GraphQL IDE or schema inspection tool to see the full set of fields and arguments available in the API.


## API

*   [`graphql.resolve`](https://supabase.github.io/pg_graphql/sql_interface/): A SQL function for executing GraphQL queries.


## Resources

*   Official [`pg_graphql` documentation](https://github.com/supabase/pg_graphql)


# pg_hashids: Short UIDs



[pg\_hashids](https://github.com/iCyberon/pg_hashids) provides a secure way to generate short, unique, non-sequential ids from numbers. The hashes are intended to be small, easy-to-remember identifiers that can be used to obfuscate data (optionally) with a password, alphabet, and salt. For example, you may wish to hide data like user IDs, order numbers, or tracking codes in favor of `pg_hashid`'s unique identifiers.


## Enable the extension


## Usage

Suppose we have a table that stores order information, and we want to give customers a unique identifier without exposing the sequential `id` column. To do this, we can use `pg_hashid`'s `id_encode` function.

```sql
create table orders (
  id serial primary key,
  description text,
  price_cents bigint
);

insert into orders (description, price_cents)
values ('a book', 9095);

select
  id,
  id_encode(id) as short_id,
  description,
  price_cents
from
  orders;

  id | short_id | description | price_cents
----+----------+-------------+-------------
  1 | jR       | a book      |        9095
(1 row)
```

To reverse the `short_id` back into an `id`, there is an equivalent function named `id_decode`.


## Resources

*   Official [pg\_hashids documentation](https://github.com/iCyberon/pg_hashids)


# pg_jsonschema: JSON Schema Validation



[JSON Schema](https://json-schema.org) is a language for annotating and validating JSON documents. [`pg_jsonschema`](https://github.com/supabase/pg_jsonschema) is a Postgres extension that adds the ability to validate PostgreSQL's built-in `json` and `jsonb` data types against JSON Schema documents.


## Enable the extension


## Functions

*   [`json_matches_schema(schema json, instance json)`](https://github.com/supabase/pg_jsonschema#api): Checks if a `json` *instance* conforms to a JSON Schema *schema*.
*   [`jsonb_matches_schema(schema json, instance jsonb)`](https://github.com/supabase/pg_jsonschema#api): Checks if a `jsonb` *instance* conforms to a JSON Schema *schema*.


## Usage

Since `pg_jsonschema` exposes its utilities as functions, we can execute them with a select statement:

```sql
select
  extensions.json_matches_schema(
    schema := '{"type": "object"}',
    instance := '{}'
  );
```

`pg_jsonschema` is generally used in tandem with a [check constraint](https://www.postgresql.org/docs/current/ddl-constraints.html) as a way to constrain the contents of a json/b column to match a JSON Schema.

```sql
create table customer(
    id serial primary key,
    ...
    metadata json,

    check (
        json_matches_schema(
            '{
                "type": "object",
                "properties": {
                    "tags": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "maxLength": 16
                        }
                    }
                }
            }',
            metadata
        )
    )
);

-- Example: Valid Payload
insert into customer(metadata)
values ('{"tags": ["vip", "darkmode-ui"]}');
-- Result:
--   INSERT 0 1

-- Example: Invalid Payload
insert into customer(metadata)
values ('{"tags": [1, 3]}');
-- Result:
--   ERROR:  new row for relation "customer" violates check constraint "customer_metadata_check"
--   DETAIL:  Failing row contains (2, {"tags": [1, 3]}).
```


## Resources

*   Official [`pg_jsonschema` documentation](https://github.com/supabase/pg_jsonschema)


# pg_net: Async Networking



[pg\_net](https://github.com/supabase/pg_net/) enables Postgres to make asynchronous HTTP/HTTPS requests in SQL. It differs from the [`http`](https://supabase.com/docs/guides/database/extensions/http) extension in that it is asynchronous by default. This makes it useful in blocking functions (like triggers).

It eliminates the need for servers to continuously poll for database changes and instead allows the database to proactively notify external resources about significant events.


## Enable the extension


## `http_get`

Creates an HTTP GET request returning the request's ID. HTTP requests are not started until the transaction is committed.


### Signature \[#get-signature]

```sql
net.http_get(
    -- url for the request
    url text,
    -- key/value pairs to be url encoded and appended to the `url`
    params jsonb default '{}'::jsonb,
    -- key/values to be included in request headers
    headers jsonb default '{}'::jsonb,
    -- the maximum number of milliseconds the request may take before being canceled
    timeout_milliseconds int default 2000
)
    -- request_id reference
    returns bigint

    strict
    volatile
    parallel safe
    language plpgsql
```


### Usage \[#get-usage]

```sql
select
    net.http_get('https://news.ycombinator.com')
    as request_id;
request_id
----------
         1
(1 row)
```


## `http_post`

Creates an HTTP POST request with a JSON body, returning the request's ID. HTTP requests are not started until the transaction is committed.

The body's character set encoding matches the database's `server_encoding` setting.


### Signature \[#post-signature]

```sql
net.http_post(
    -- url for the request
    url text,
    -- body of the POST request
    body jsonb default '{}'::jsonb,
    -- key/value pairs to be url encoded and appended to the `url`
    params jsonb default '{}'::jsonb,
    -- key/values to be included in request headers
    headers jsonb default '{"Content-Type": "application/json"}'::jsonb,
    -- the maximum number of milliseconds the request may take before being canceled
    timeout_milliseconds int default 2000
)
    -- request_id reference
    returns bigint

    volatile
    parallel safe
    language plpgsql
```


### Usage \[#post-usage]

```sql
select
    net.http_post(
        url:='https://httpbin.org/post',
        body:='{"hello": "world"}'::jsonb
    ) as request_id;
request_id
----------
         1
(1 row)
```


## `http_delete`

Creates an HTTP DELETE request, returning the request's ID. HTTP requests are not started until the transaction is committed.


### Signature \[#post-signature]

```sql
net.http_delete(
    -- url for the request
    url text,
    -- key/value pairs to be url encoded and appended to the `url`
    params jsonb default '{}'::jsonb,
    -- key/values to be included in request headers
    headers jsonb default '{}'::jsonb,
    -- the maximum number of milliseconds the request may take before being canceled
    timeout_milliseconds int default 2000
)
    -- request_id reference
    returns bigint

    strict
    volatile
    parallel safe
    language plpgsql
    security definer
```


### Usage \[#delete-usage]

```sql
select
    net.http_delete(
        'https://dummy.restapiexample.com/api/v1/delete/2'
    ) as request_id;
----------
         1
(1 row)
```


## Analyzing responses

Waiting requests are stored in the `net.http_request_queue` table. Upon execution, they are deleted.

```sql
CREATE UNLOGGED TABLE
    net.http_request_queue (
        id bigint NOT NULL DEFAULT nextval('net.http_request_queue_id_seq'::regclass),
        method text NOT NULL,
        url text NOT NULL,
        headers jsonb NOT NULL,
        body bytea NULL,
        timeout_milliseconds integer NOT NULL
    )
```

Once a response is returned, by default, it is stored for 6 hours in the `net._http_response` table.

```sql
CREATE UNLOGGED TABLE
    net._http_response (
        id bigint NULL,
        status_code integer NULL,
        content_type text NULL,
        headers jsonb NULL,
        content text NULL,
        timed_out boolean NULL,
        error_msg text NULL,
        created timestamp with time zone NOT NULL DEFAULT now()
    )
```

The responses can be observed with the following query:

```sql
select * from net._http_response;
```

The data can also be observed in the `net` schema with the [Supabase Dashboard's SQL Editor](https://supabase.com/dashboard/project/_/editor)


## Debugging requests


### Inspecting request data

The [Postman Echo API](https://documenter.getpostman.com/view/5025623/SWTG5aqV) returns a response with the same body and content
as the request. It can be used to inspect the data being sent.

Sending a post request to the echo API

```sql
select
    net.http_post(
        url := 'https://postman-echo.com/post',
        body := '{"key1": "value", "key2": 5}'::jsonb
    ) as request_id;
```

Inspecting the echo API response content to ensure it contains the right body

```sql
select
    "content"
from net._http_response
where id = <request_id>
-- returns information about the request
-- including the body sent: {"key": "value", "key": 5}
```

Alternatively, by wrapping a request in a [database function](https://supabase.com/docs/guides/database/functions), sent row data can be logged or returned for inspection and debugging.

```sql
create or replace function debugging_example (row_id int)
returns jsonb as $$
declare
    -- Store payload data
    row_data_var jsonb;
begin
    -- Retrieve row data and convert to JSON
    select to_jsonb("<example_table>".*) into row_data_var
    from "<example_table>"
    where "<example_table>".id = row_id;

    -- Initiate HTTP POST request to URL
    perform
        net.http_post(
            url := 'https://postman-echo.com/post',
            -- Use row data as payload
            body := row_data_var
        ) as request_id;

    -- Optionally Log row data or other data for inspection in Supabase Dashboard's Postgres Logs
    raise log 'Logging an entire row as JSON (%)', row_data_var;

    -- return row data to inspect
    return row_data_var;

-- Handle exceptions here if needed
exception
    when others then
        raise exception 'An error occurred: %', SQLERRM;
end;
$$ language plpgsql;

-- calling function
select debugging_example(<row_id>);
```


### Inspecting failed requests

Finds all failed requests

```sql
select
  *
from net._http_response
where "status_code" >= 400 or "error_msg" is not null
order by "created" desc;
```


## Configuration

The extension is configured to reliably execute up to 200 requests per second. The response messages are stored for only 6 hours to prevent needless buildup. The default behavior can be modified by rewriting config variables.


### Get current settings

```sql
select
  "name",
  "setting"
from pg_settings
where "name" like 'pg_net%';
```


### Alter settings

Change variables:

```sql
alter role "postgres" set pg_net.ttl to '24 hours';
alter role "postgres" set pg_net.batch_size to 500;
```

Then reload the settings and restart the `pg_net` background worker with:

```sql
select net.worker_restart();
```


## Examples


### Invoke a Supabase Edge Function

Make a POST request to a Supabase Edge Function with auth header and JSON body payload:

```sql
select
    net.http_post(
        url:='https://project-ref.supabase.co/functions/v1/function-name',
        headers:='{"Content-Type": "application/json", "Authorization": "Bearer <YOUR_ANON_KEY>"}'::jsonb,
        body:='{"name": "pg_net"}'::jsonb
    ) as request_id;
```


### Call an endpoint every minute with [pg\_cron](https://supabase.com/docs/guides/database/extensions/pgcron)

The pg\_cron extension enables Postgres to become its own cron server. With it you can schedule regular calls with up to a minute precision to endpoints.

```sql
select cron.schedule(
	'cron-job-name',
	'* * * * *', -- Executes every minute (cron syntax)
	$$
	    -- SQL query
	    select "net"."http_post"(
            -- URL of Edge function
            url:='https://project-ref.supabase.co/functions/v1/function-name',
            headers:='{"Authorization": "Bearer <YOUR_ANON_KEY>"}'::jsonb,
            body:='{"name": "pg_net"}'::jsonb
	    ) as "request_id";
	$$
);
```


### Execute pg\_net in a trigger

Make a call to an external endpoint when a trigger event occurs.

```sql
-- function called by trigger
create or replace function <function_name>()
    returns trigger
    language plpgSQL
as $$
begin
    -- calls pg_net function net.http_post
    -- sends request to postman API
    perform "net"."http_post"(
      'https://postman-echo.com/post'::text,
      jsonb_build_object(
        'old_row', to_jsonb(old.*),
        'new_row', to_jsonb(new.*)
      ),
      headers:='{"Content-Type": "application/json"}'::jsonb
    ) as request_id;
    return new;
END $$;

-- trigger for table update
create trigger <trigger_name>
    after update on <table_name>
    for each row
    execute function <function_name>();
```


### Send multiple table rows in one request

```sql
with "selected_table_rows" as (
    select
        -- Converts all the rows into a JSONB array
        jsonb_agg(to_jsonb(<table_name>.*)) as JSON_payload
    from <table_name>
    -- good practice to LIMIT the max amount of rows
)
select
    net.http_post(
        url := 'https://postman-echo.com/post'::text,
        body := JSON_payload
    ) AS request_id
FROM "selected_table_rows";
```

More examples can be seen on the [Extension's GitHub page](https://github.com/supabase/pg_net/)


## Limitations

*   To improve speed and performance, the requests and responses are stored in [unlogged tables](https://pgpedia.info/u/unlogged-table.html), which are not preserved during a crash or unclean shutdown.
*   By default, response data is saved for only 6 hours
*   Can only make POST requests with JSON data. No other data formats are supported
*   Intended to handle at most 200 requests per second. Increasing the rate can introduce instability
*   Does not have support for PATCH/PUT requests
*   Can only work with one database at a time. It defaults to the `postgres` database.


## Resources

*   Source code: [github.com/supabase/pg\_net](https://github.com/supabase/pg_net/)
*   Official Docs: [github.com/supabase/pg\_net](https://github.com/supabase/pg_net/)


# pg_plan_filter: Restrict Total Cost



[`pg_plan_filter`](https://github.com/pgexperts/pg_plan_filter) is Postgres extension to block execution of statements where query planner's estimate of the total cost exceeds a threshold. This is intended to give database administrators a way to restrict the contribution an individual query has on database load.


## Enable the extension

`pg_plan_filter` can be enabled on a per connection basis:

```sql
load 'plan_filter';
```

or for all connections:

```sql
alter database some_db set session_preload_libraries = 'plan_filter';
```


## API

`plan_filter.statement_cost_limit`: restricts the maximum total cost for executed statements
`plan_filter.limit_select_only`: restricts to `select` statements

Note that `limit_select_only = true` is not the same as read-only because `select` statements may modify data, for example, through a function call.


## Example

To demonstrate total cost filtering, we'll compare how `plan_filter.statement_cost_limit` treats queries that are under and over its cost limit. First, we set up a table with some data:

```sql
create table book(
  id int primary key
);
-- CREATE TABLE

insert into book(id) select * from generate_series(1, 10000);
-- INSERT 0 10000
```

Next, we can review the explain plans for a single record select, and a whole table select.

```sql
explain select * from book where id =1;
                                QUERY PLAN
---------------------------------------------------------------------------
 Index Only Scan using book_pkey on book  (cost=0.28..2.49 rows=1 width=4)
   Index Cond: (id = 1)
(2 rows)

explain select * from book;
                       QUERY PLAN
---------------------------------------------------------
 Seq Scan on book  (cost=0.00..135.00 rows=10000 width=4)
(1 row)
```

Now we can choose a `statement_cost_filter` value between the total cost for the single select (2.49) and the whole table select (135.0) so one statement will succeed and one will fail.

```sql
load 'plan_filter';
set plan_filter.statement_cost_limit = 50; -- between 2.49 and 135.0

select * from book where id = 1;
 id
----
  1
(1 row)
-- SUCCESS
```

```sql
select * from book;

ERROR:  plan cost limit exceeded
HINT:  The plan for your query shows that it would probably have an excessive run time. This may be due to a logic error in the SQL, or it maybe just a very costly query. Rewrite your query or increase the configuration parameter "plan_filter.statement_cost_limit".
-- FAILURE
```


## Resources

*   Official [`pg_plan_filter` documentation](https://github.com/pgexperts/pg_plan_filter)


# pg_repack: Physical storage optimization and maintenance



[pg\_repack](https://github.com/reorg/pg_repack) is a Postgres extension to remove bloat from tables and indexes, and optionally restore the physical order of clustered indexes. Unlike CLUSTER and VACUUM FULL, pg\_repack runs "online" and does not hold a exclusive locks on the processed tables that could prevent ongoing database operations. pg\_repack's efficiency is comparable to using CLUSTER directly.

pg\_repack provides the following methods to optimize physical storage:

*   Online CLUSTER: ordering table data by cluster index in a non-blocking way
*   Ordering table data by specified columns
*   Online VACUUM FULL: packing rows only in a non-blocking way
*   Rebuild or relocate only the indexes of a table

pg\_repack has 2 components, the database extension and a client-side CLI to control it.


## Requirements

*   A target table must have a PRIMARY KEY, or a UNIQUE total index on a NOT NULL column.
*   Performing a full-table repack requires free disk space about twice as large as the target table and its indexes.

pg\_repack requires the Postgres superuser role by default. That role is not available to users on the Supabase platform. To avoid that requirement, use the `-k` or `--no-superuser-check` flags on every `pg_repack` CLI command.

The first version of pg\_repack with full support for non-superuser repacking is 1.5.2. You can check the version installed on your Supabase instance using

```sql
select default_version
from pg_available_extensions
where name = 'pg_repack';
```

If pg\_repack is not present, or the version is < 1.5.2, [upgrade to the latest version](/docs/guides/platform/upgrading) of Supabase to gain access.


## Usage


### Enable the extension

Get started with pg\_repack by enabling the extension in the Supabase Dashboard.


### Install the CLI

Select an option from the pg\_repack docs to [install the client CLI](https://reorg.github.io/pg_repack/#download).


### Syntax

All pg\_repack commands should include the `-k` flag to skip the client-side superuser check.

```sh
pg_repack -k [OPTION]... [DBNAME]
```


## Example

Perform an online `VACUUM FULL` on the tables `public.foo` and `public.bar` in the database `postgres`:

```sh
pg_repack -k -h db.<PROJECT_REF>.supabase.co -p 5432 -U postgres -d postgres --no-order --table public.foo --table public.bar
```

See the [official pg\_repack documentation](https://reorg.github.io/pg_repack/) for the full list of options.


## Limitations

*   pg\_repack cannot reorganize temporary tables.
*   pg\_repack cannot cluster tables by GiST indexes.
*   You cannot perform DDL commands of the target tables except VACUUM or ANALYZE while pg\_repack is working.
    pg\_repack holds an ACCESS SHARE lock on the target table to enforce this restriction.


## Resources

*   [Official pg\_repack documentation](https://reorg.github.io/pg_repack/)


# pg_stat_statements: Query Performance Monitoring



`pg_stat_statements` is a database extension that exposes a view, of the same name, to track statistics about SQL statements executed on the database. The following table shows some of the available statistics and metadata:

| Column Name       | Column Type                          | Description                                                                                                                  |
| ----------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| `userid`          | `oid` (references `pg_authid.oid`)   | OID of user who executed the statement                                                                                       |
| `dbid`            | `oid` (references `pg_database.oid`) | OID of database in which the statement was executed                                                                          |
| `toplevel`        | `bool`                               | True if the query was executed as a top-level statement (always true if pg\_stat\_statements.track is set to top)              |
| `queryid`         | `bigint`                             | Hash code to identify identical normalized queries.                                                                          |
| `query`           | `text`                               | Text of a representative statement                                                                                           |
| `plans`           | `bigint`                             | Number of times the statement was planned (if pg\_stat\_statements.track\_planning is enabled, otherwise zero)                  |
| `total_plan_time` | `double precision`                   | Total time spent planning the statement, in milliseconds (if pg\_stat\_statements.track\_planning is enabled, otherwise zero)   |
| `min_plan_time`   | `double precision`                   | Minimum time spent planning the statement, in milliseconds (if pg\_stat\_statements.track\_planning is enabled, otherwise zero) |

A full list of statistics is available in the [pg\_stat\_statements docs](https://www.postgresql.org/docs/current/pgstatstatements.html).

For more information on query optimization, check out the [query performance guide](/docs/guides/platform/performance#examining-query-performance).


## Enable the extension


## Inspecting activity

A common use for `pg_stat_statements` is to track down expensive or slow queries. The `pg_stat_statements` view contains a row for each executed query with statistics inlined. For example, you can leverage the statistics to identify frequently executed and slow queries against a given table.

```sql
select
	calls,
	mean_exec_time,
	max_exec_time,
	total_exec_time,
	stddev_exec_time,
	query
from
	pg_stat_statements
where
    calls > 50                   -- at least 50 calls
    and mean_exec_time > 2.0     -- averaging at least 2ms/call
    and total_exec_time > 60000  -- at least one minute total server time spent
    and query ilike '%user_in_organization%' -- filter to queries that touch the user_in_organization table
order by
	calls desc
```

From the results, we can make an informed decision about which queries to optimize or index.


## Resources

*   Official [pg\_stat\_statements documentation](https://www.postgresql.org/docs/current/pgstatstatements.html)


# PGAudit: Postgres Auditing



[PGAudit](https://www.pgaudit.org) extends Postgres's built-in logging abilities. It can be used to selectively track activities within your database.

This helps you with:

*   **Compliance**: Meeting audit requirements for regulations
*   **Security**: Detecting suspicious database activity
*   **Troubleshooting**: Identifying and fixing database issues


## Enable the extension


## Configure the extension

PGAudit can be configured with different levels of precision.

**PGAudit logging precision:**

*   **[Session](#session-logging):** Logs activity within a connection, such as a [psql](https://supabase.com/docs/guides/database/connecting-to-postgres#connecting-with-psql) connection.
*   **[User](#user-logging):** Logs activity by a particular database user (for example, `anon` or `postgres`).
*   **[Global](#global-logging):** Logs activity across the entire database.
*   **[Object](#object-logging):** Logs events related to specific database objects (for example, the auth.users table).

Although Session, User, and Global modes differ in their precision, they're all considered variants of **Session Mode** and are configured with the same input categories.


### Session mode categories

These modes can monitor predefined categories of database operations:

| Category   | What it Logs                                                          | Description                                                                |
| ---------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `read`     | Data retrieval (SELECT, COPY)                                         | Tracks what data is being accessed.                                        |
| `write`    | Data modification (INSERT, DELETE, UPDATE, TRUNCATE, COPY)            | Tracks changes made to your database.                                      |
| `function` | FUNCTION, PROCEDURE, and DO/END block executions                      | Tracks routine/function executions                                         |
| `role`     | User management actions (CREATE, DROP, ALTER on users and privileges) | Tracks changes to user permissions and access.                             |
| `ddl`      | Schema changes (CREATE, DROP, ALTER statements)                       | Monitors modifications to your database structure (tables, indexes, etc.). |
| `misc`     | Less common commands (FETCH, CHECKPOINT)                              | Captures obscure actions for deeper analysis if needed.                    |
| `all`      | Everything above                                                      | Comprehensive logging for complete audit trails.                           |

Below is a limited example of how to assign PGAudit to monitor specific categories.

```sql
-- log all CREATE, ALTER, and DROP events
... pgaudit.log = 'ddl';

-- log all CREATE, ALTER, DROP, and SELECT events
... pgaudit.log = 'read, ddl';

-- log nothing
... pgaudit.log = 'none';
```


### Session logging

When you are connecting in a session environment, such as a [psql](https://supabase.com/docs/guides/database/connecting-to-postgres#connecting-with-psql) connection, you can configure PGAudit to record events initiated within the session.

Inside a session, by default, PGAudit will log nothing:

```sql
-- returns 'none'
show pgaudit.log;
```

In the session, you can `set` the `pgaudit.log` variable to record events:

```sql
-- log CREATE, ALTER, and DROP events
set pgaudit.log = 'ddl';

-- log all CREATE, ALTER, DROP, and SELECT events
set pgaudit.log = 'read, ddl';

-- log nothing
set pgaudit.log = 'none';
```


### User logging

There are some cases where you may want to monitor a database user's actions. For instance, let's say you connected your database to [Zapier](https://supabase.com/partners/integrations/zapier) and created a custom role for it to use:

```sql
create user "zapier" with password '<new password>';
```

You may want to log all actions initiated by `zapier`, which can be done with the following command:

```sql
alter role "zapier" set pgaudit.log to 'all';
```

To remove the settings, execute the following code:

```sql
-- disables role's log
alter role "zapier" set pgaudit.log to 'none';

-- check to make sure the changes are finalized:
select
  rolname,
  rolconfig
from pg_roles
where rolname = 'zapier';
-- should return a rolconfig path with "pgaudit.log=none" present
```


### Global logging

The below SQL configures PGAudit to record all events associated with the `postgres` role. Since it has extensive privileges, this effectively monitors all database activity.

```sql
alter role "postgres" set pgaudit.log to 'all';
```

To check if the `postgres` role is auditing, execute the following command:

```sql
select
  rolname,
  rolconfig
from pg_roles
where rolname = 'postgres';
-- should return a rolconfig path with "pgaudit.log=all" present
```

To remove the settings, execute the following code:

```sql
alter role "postgres" set pgaudit.log to 'none';
```


### Object logging

To fine-tune what object events PGAudit will record, you must create a custom database role with limited permissions:

```sql
create role "some_audit_role" noinherit;
```

No other Postgres user can assume or login via this role. It solely exists to securely define what PGAudit will record.

Once the role is created, you can direct PGAudit to log by assigning it to the `pgaudit.role` variable:

```sql
alter role "postgres" set pgaudit.role to 'some_audit_role';
```

You can then assign the role to monitor only approved object events, such as `select` statements that include a specific table:

```sql
grant select on random_table to "some_audit_role";
```

With this privilege granted, PGAudit will record all select statements that reference the `random_table`, regardless of *who* or *what* actually initiated the event. All assignable privileges can be viewed in the [Postgres documentation](https://www.postgresql.org/docs/current/ddl-priv.html).

If you would no longer like to use object logging, you will need to unassign the `pgaudit.role` variable:

```sql
-- change pgaudit.role to no longer reference some_audit_role
alter role "postgres" set pgaudit.role to '';

-- view if pgaudit.role changed with the following command:
select
  rolname,
  rolconfig
from pg_roles
where rolname = 'postgres';
-- should return a rolconfig path with "pgaudit.role="
```


## Interpreting Audit Logs

PGAudit was designed for storing logs as CSV files with the following headers:

| header          | Description                                                                                                                               |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| AUDIT\_TYPE      | SESSION or OBJECT                                                                                                                         |
| STATEMENT\_ID    | Unique statement ID for this session. Sequential even if some statements are not logged.                                                  |
| SUBSTATEMENT\_ID | Sequential ID for each sub-statement within the main statement. Continuous even if some are not logged.                                   |
| CLASS           | ..., READ, ROLE (see pgaudit.log).                                                                                                        |
| COMMAND         | ..., ALTER TABLE, SELECT.                                                                                                                 |
| OBJECT\_TYPE     | TABLE, INDEX, VIEW, etc. Available for SELECT, DML, and most DDL statements.                                                              |
| OBJECT\_NAME     | The fully qualified object name (for example, public.account). Available for SELECT, DML, and most DDL.                                   |
| STATEMENT       | Statement executed on the backend.                                                                                                        |
| PARAMETER       | If pgaudit.log\_parameter is set, this field contains the statement parameters as quoted CSV, or \<none>. Otherwise, it's \<not logged>. |

A log made from the following create statement:

```sql
create table account (
  id int primary key,
  name text,
  description text
);
```

Generates the following log in the [Dashboard's Postgres Logs](https://supabase.com/dashboard/project/_/logs/postgres-logs):

     AUDIT: SESSION,1,1,DDL,CREATE TABLE,TABLE,public.account,create table account(
      id int,
      name text,
      description text
    ); <not logged>


## Finding and filtering audit logs

Logs generated by PGAudit can be found in [Postgres Logs](https://supabase.com/dashboard/project/_/logs/postgres-logs?s=AUDIT). To find a specific log, you can use the log explorer. Below is a basic example to extract logs referencing `CREATE TABLE` events

```sql
select
  cast(t.timestamp as datetime) as timestamp,
  event_message
from
  postgres_logs as t
  cross join unnest(metadata) as m
  cross join unnest(m.parsed) as p
where event_message like 'AUDIT%CREATE TABLE%'
order by timestamp desc
limit 100;
```


## Practical examples


### Monitoring API events

To monitor all writes initiated by the PostgREST API roles:

```sql
alter role "authenticator" set pgaudit.log to 'write';

-- the above is the practical equivalent to:
-- alter role "anon" set pgaudit.log TO 'write';
-- alter role "authenticated" set pgaudit.log TO 'write';
-- alter role "service_role" set pgaudit.log TO 'write';
```


### Monitoring the `auth.users` table

In the worst case scenario, where a privileged roles' password is exposed, you can use PGAudit to monitor if the `auth.users` table was targeted. It should be stated that API requests are already monitored in the [API Edge Network](https://supabase.com/dashboard/project/_/logs/edge-logs) and this is more about providing greater clarity about what is happening at the database level.

Logging `auth.user` should be done in Object Mode and requires a custom role:

```sql
-- create logging role
create role "auth_auditor" noinherit;

-- give role permission to observe relevant table events
grant select on auth.users to "auth_auditor";
grant delete on auth.users to "auth_auditor";

-- assign auth_auditor to pgaudit.role
alter role "postgres" set pgaudit.role to 'auth_auditor';
```

With the above code, any query involving reading or deleting from the auth.users table will be logged.


## Best practices


### Disabling excess logging

PGAudit, if not configured mindfully, can log all database events, including background tasks. This can generate an undesirably large amount of logs in a few hours.

The first step to solve this problem is to identify which database users PGAudit is observing:

```sql
-- find all users monitored by pgaudit
select
  rolname,
  rolconfig
from pg_roles
where
  exists (
    select
      1
    from UNNEST(rolconfig) as c
    where c like '%pgaudit.role%' or c like '%pgaudit.log%'
  );
```

To prevent PGAudit from monitoring the problematic roles, you'll want to change their `pgaudit.log` values to `none` and `pgaudit.role` values to `empty quotes ''`

```sql
  -- Use to disable object level logging
  alter role "<role name>" set pgaudit.role to '';

  -- Use to disable global and user level logging
  alter role "<role name>" set pgaudit.log to 'none';
```


## FAQ


#### Using PGAudit to debug database functions

Technically yes, but it is not the best approach. It is better to check out our [function debugging guide](https://supabase.com/docs/guides/database/functions#general-logging) instead.


#### Downloading database logs

In the [Logs Dashboard](https://supabase.com/dashboard/project/_/logs/postgres-logs) you can download logs as CSVs.


#### Logging observed table rows

By default, PGAudit records queries, but not the returned rows. You can modify this behavior with the `pgaudit.log_rows` variable:

```sql
--enable
alter role "postgres" set pgaudit.log_rows to 'on';

-- disable
alter role "postgres" set pgaudit.log_rows to 'off';
```

You should not do this unless you are *absolutely* certain it is necessary for your use case. It can expose sensitive values to your logs that ideally should not be preserved. Furthermore, if done in excess, it can noticeably reduce database performance.


#### Logging function parameters

We don't currently support configuring `pgaudit.log_parameter` because it may log secrets in encrypted columns if you are using [pgsodium](https://supabase.com/docs/guides/database/extensions/pgsodium) or[Vault](https://supabase.com/docs/guides/database/vault).

You can upvote this [feature request](https://github.com/orgs/supabase/discussions/20183) with your use-case if you'd like this restriction lifted.


#### Does PGAudit support system wide configurations?

PGAudit allows settings to be applied to 3 different database scopes:

| Scope    | Description        | Configuration File/Command |
| -------- | ------------------ | -------------------------- |
| System   | Entire server      | ALTER SYSTEM commands      |
| Database | Specific database  | ALTER DATABASE commands    |
| Role     | Specific user/role | ALTER ROLE commands        |

Supabase limits full privileges for file system and database variables, meaning PGAudit modifications can only occur at the role level. Assigning PGAudit to the `postgres` role grants it nearly complete visibility into the database, making role-level adjustments a practical alternative to configuring at the database or system level.

PGAudit's [official documentation](https://www.pgaudit.org) focuses on system and database level configs, but its docs officially supports role level configs, too.


## Resources

*   [Official `PGAudit` documentation](https://www.pgaudit.org)
*   [Database Function Logging](https://supabase.com/docs/guides/database/functions#general-logging)
*   [Supabase Logging](https://supabase.com/docs/guides/platform/logs)
*   [Self-Hosting Logs](https://supabase.com/docs/reference/self-hosting-analytics/introduction)


# pgjwt: JSON Web Tokens



The [`pgjwt`](https://github.com/michelp/pgjwt) (PostgreSQL JSON Web Token) extension allows you to create and parse [JSON Web Tokens (JWTs)](https://en.wikipedia.org/wiki/JSON_Web_Token) within a PostgreSQL database. JWTs are commonly used for authentication and authorization in web applications and services.


## Enable the extension


## API

*   [`sign(payload json, secret text, algorithm text default 'HSA256')`](https://github.com/michelp/pgjwt#usage): Signs a JWT containing *payload* with *secret* using *algorithm*.
*   [`verify(token text, secret text, algorithm text default 'HSA256')`](https://github.com/michelp/pgjwt#usage): Decodes a JWT *token* that was signed with *secret* using *algorithm*.

Where:

*   `payload` is an encrypted JWT represented as a string.
*   `secret` is the private/secret passcode which is used to sign the JWT and verify its integrity.
*   `algorithm` is the method used to sign the JWT using the secret.
*   `token` is an encrypted JWT represented as a string.


## Usage

Once the extension is installed, you can use its functions to create and parse JWTs. Here's an example of how you can use the `sign` function to create a JWT:

```sql
select
  extensions.sign(
    payload   := '{"sub":"1234567890","name":"John Doe","iat":1516239022}',
    secret    := 'secret',
    algorithm := 'HS256'
  );
```

The `pgjwt_encode` function returns a string that represents the JWT, which can then be safely transmitted between parties.

                  sign
    ---------------------------------
     eyJhbGciOiJIUzI1NiIsInR5cCI6IkpX
     VCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiw
     ibmFtZSI6IkpvaG4gRG9lIiwiaWF0Ijo
     xNTE2MjM5MDIyfQ.XbPfbIHMI6arZ3Y9
     22BhjWgQzWXcXNrz0ogtVhfEd2o
    (1 row)

To parse a JWT and extract its claims, you can use the `verify` function. Here's an example:

```sql
select
  extensions.verify(
    token := 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiRm9vIn0.Q8hKjuadCEhnCPuqIj9bfLhTh_9QSxshTRsA5Aq4IuM',
    secret    := 'secret',
    algorithm := 'HS256'
  );
```

Which returns the decoded contents and some associated metadata.

```sql
           header            |    payload     | valid
-----------------------------+----------------+-------
 {"alg":"HS256","typ":"JWT"} | {"name":"Foo"} | t
(1 row)
```


## Resources

*   Official [`pgjwt` documentation](https://github.com/michelp/pgjwt)


# pgmq: Queues



See the [Supabase Queues docs](/docs/guides/queues).


# PGroonga: Multilingual Full Text Search



`PGroonga` is a Postgres extension adding a full text search indexing method based on [Groonga](https://groonga.org). While native Postgres supports full text indexing, it is limited to alphabet and digit based languages. `PGroonga` offers a wider range of character support making it viable for a superset of languages supported by Postgres including Japanese, Chinese, etc.


## Enable the extension


## Creating a full text search index

Given a table with a `text` column:

```sql
create table memos (
  id serial primary key,
  content text
);
```

We can index the column for full text search with a `pgroonga` index:

```sql
create index ix_memos_content ON memos USING pgroonga(content);
```

To test the full text index, we'll add some data.

```sql
insert into memos(content)
values
  ('PostgreSQL is a relational database management system.'),
  ('Groonga is a fast full text search engine that supports all languages.'),
  ('PGroonga is a PostgreSQL extension that uses Groonga as index.'),
  ('There is groonga command.');
```

The Postgres query planner is smart enough to know that, for extremely small tables, it's faster to scan the whole table rather than loading an index. To force the index to be used, we can disable sequential scans:

```sql
-- For testing only. Don't do this in production
set enable_seqscan = off;
```

Now if we run an explain plan on a query filtering on `memos.content`:

```sql
explain select * from memos where content like '%engine%';

                               QUERY PLAN
-----------------------------------------------------------------------------
Index Scan using ix_memos_content on memos  (cost=0.00..1.11 rows=1 width=36)
  Index Cond: (content ~~ '%engine%'::text)
(2 rows)
```

The `pgroonga` index is used to retrieve the result set:

```markdown
| id  | content                                                                  |
| --- | ------------------------------------------------------------------------ |
| 2   | 'Groonga is a fast full text search engine that supports all languages.' |
```


## Full text search

The `&@~` operator performs full text search. It returns any matching results. Unlike `LIKE` operator, `pgroonga` can search any text that contains the keyword case insensitive.

Take the following example:

```sql
select * from memos where content &@~ 'groonga';
```

And the result:

```markdown
id | content  
----+------------------------------------------------------------------------
2 | Groonga is a fast full text search engine that supports all languages.
3 | PGroonga is a PostgreSQL extension that uses Groonga as index.
4 | There is groonga command.
(3 rows)
```


### Match all search words

To find all memos where content contains BOTH of the words `postgres` and `pgroonga`, we can just use space to separate each words:

```sql
select * from memos where content &@~ 'postgres pgroonga';
```

And the result:

```markdown
id | content  
----+----------------------------------------------------------------
3 | PGroonga is a PostgreSQL extension that uses Groonga as index.
(1 row)
```


### Match any search words

To find all memos where content contain ANY of the words `postgres` or `pgroonga`, use the upper case `OR`:

```sql
select * from memos where content &@~ 'postgres OR pgroonga';
```

And the result:

```markdown
id | content  
----+----------------------------------------------------------------
1 | PostgreSQL is a relational database management system.
3 | PGroonga is a PostgreSQL extension that uses Groonga as index.
(2 rows)
```


### Search that matches words with negation

To find all memos where content contain the word `postgres` but not `pgroonga`, use `-` symbol:

```sql
select * from memos where content &@~ 'postgres -pgroonga';
```

And the result:

```markdown
id | content  
----+--------------------------------------------------------
1 | PostgreSQL is a relational database management system.
(1 row)
```


## Resources

*   Official [PGroonga documentation](https://pgroonga.github.io/tutorial/)


# pgrouting: Geospatial Routing



[`pgRouting`](http://pgrouting.org) is Postgres and [PostGIS](http://postgis.net) extension adding geospatial routing functionality.

The core functionality of `pgRouting` is a set of path finding algorithms including:

*   All Pairs Shortest Path, Johnson’s Algorithm
*   All Pairs Shortest Path, Floyd-Warshall Algorithm
*   Shortest Path A\*
*   Bi-directional Dijkstra Shortest Path
*   Bi-directional A\* Shortest Path
*   Shortest Path Dijkstra
*   Driving Distance
*   K-Shortest Path, Multiple Alternative Paths
*   K-Dijkstra, One to Many Shortest Path
*   Traveling Sales Person
*   Turn Restriction Shortest Path (TRSP)


## Enable the extension


## Example

As an example, we'll solve the [traveling salesperson problem](https://en.wikipedia.org/wiki/Travelling_salesman_problem) using the `pgRouting`'s `pgr_TSPeuclidean` function from some PostGIS coordinates.

A summary of the traveling salesperson problem is, given a set of city coordinates, solve for a path that goes through each city and minimizes the total distance traveled.

First we populate a table with some X, Y coordinates

```sql
create table wi29 (
  id bigint,
  x float,
  y float,
  geom geometry
);

insert into wi29 (id, x, y)
values
  (1,20833.3333,17100.0000),
  (2,20900.0000,17066.6667),
  (3,21300.0000,13016.6667),
  (4,21600.0000,14150.0000),
  (5,21600.0000,14966.6667),
  (6,21600.0000,16500.0000),
  (7,22183.3333,13133.3333),
  (8,22583.3333,14300.0000),
  (9,22683.3333,12716.6667),
  (10,23616.6667,15866.6667),
  (11,23700.0000,15933.3333),
  (12,23883.3333,14533.3333),
  (13,24166.6667,13250.0000),
  (14,25149.1667,12365.8333),
  (15,26133.3333,14500.0000),
  (16,26150.0000,10550.0000),
  (17,26283.3333,12766.6667),
  (18,26433.3333,13433.3333),
  (19,26550.0000,13850.0000),
  (20,26733.3333,11683.3333),
  (21,27026.1111,13051.9444),
  (22,27096.1111,13415.8333),
  (23,27153.6111,13203.3333),
  (24,27166.6667,9833.3333),
  (25,27233.3333,10450.0000),
  (26,27233.3333,11783.3333),
  (27,27266.6667,10383.3333),
  (28,27433.3333,12400.0000),
  (29,27462.5000,12992.2222);
```

Next we use the `pgr_TSPeuclidean` function to find the best path.

```sql
select
    *
from
     pgr_TSPeuclidean($$select * from wi29$$)
```

```sql
 seq | node |       cost       |     agg_cost     
-----+------+------------------+------------------
   1 |    1 |                0 |                0
   2 |    2 |  74.535614157127 |  74.535614157127
   3 |    6 | 900.617093380362 | 975.152707537489
   4 |   10 | 2113.77757765045 | 3088.93028518793
   5 |   11 | 106.718669615254 | 3195.64895480319
   6 |   12 | 1411.95293791574 | 4607.60189271893
   7 |   13 | 1314.23824873744 | 5921.84014145637
   8 |   14 | 1321.76283931305 | 7243.60298076942
   9 |   17 | 1202.91366735569 |  8446.5166481251
  10 |   18 | 683.333268292684 | 9129.84991641779
  11 |   15 | 1108.05137466134 | 10237.9012910791
  12 |   19 | 772.082339448903 |  11009.983630528
  13 |   22 | 697.666150054665 | 11707.6497805827
  14 |   23 | 220.141999627513 | 11927.7917802102
  15 |   21 | 197.926372783442 | 12125.7181529937
  16 |   29 | 440.456596290771 | 12566.1747492844
  17 |   28 | 592.939989005405 | 13159.1147382898
  18 |   26 | 648.288376333318 | 13807.4031146231
  19 |   20 | 509.901951359278 | 14317.3050659824
  20 |   25 | 1330.83095428717 | 15648.1360202696
  21 |   27 |  74.535658878487 | 15722.6716791481
  22 |   24 | 559.016994374947 |  16281.688673523
  23 |   16 | 1243.87392358622 | 17525.5625971092
  24 |    9 |  4088.0585364911 | 21613.6211336004
  25 |    7 |  650.85409697993 | 22264.4752305803
  26 |    3 | 891.004385199336 | 23155.4796157796
  27 |    4 | 1172.36699411442 |  24327.846609894
  28 |    8 | 994.708187806297 | 25322.5547977003
  29 |    5 | 1188.01888359478 | 26510.5736812951
  30 |    1 | 2266.91173136004 | 28777.4854126552
```


## Resources

*   Official [`pgRouting` documentation](https://docs.pgrouting.org/latest/en/index.html)


# pgsodium (pending deprecation): Encryption Features



Supabase DOES NOT RECOMMEND any new usage of [`pgsodium`](https://github.com/michelp/pgsodium).

The [`pgsodium`](https://github.com/michelp/pgsodium) extension is expected to go through a deprecation cycle in the near future. We will reach out to owners of impacted projects to assist with migrations away from [`pgsodium`](https://github.com/michelp/pgsodium) once the deprecation process begins.

[`pgsodium`](https://github.com/michelp/pgsodium) is a Postgres extension which provides SQL access to [`libsodium`'s](https://doc.libsodium.org/) high-level cryptographic algorithms.

Supabase previously documented two features derived from pgsodium. Namely [Server Key Management](https://github.com/michelp/pgsodium#server-key-management) and [Transparent Column Encryption](https://github.com/michelp/pgsodium#transparent-column-encryption). At this time, we do not recommend using either on the Supabase platform due to their high level of operational complexity and misconfiguration risk.

Note that Supabase projects are encrypted at rest by default which likely is sufficient for your compliance needs e.g. SOC2 & HIPAA.


## Get the root encryption key for your Supabase project

Encryption requires keys. Keeping the keys in the same database as the encrypted data would be unsafe. For more information about managing the `pgsodium` root encryption key on your Supabase project see **[encryption key location](/docs/guides/database/vault#encryption-key-location)**. This key is required to decrypt values stored in [Supabase Vault](/docs/guides/database/vault) and data encrypted with Transparent Column Encryption.


## Resources

*   [Supabase Vault](/docs/guides/database/vault)
*   Read more about Supabase Vault in the [blog post](https://supabase.com/blog/vault-now-in-beta)
*   [Supabase Vault on GitHub](https://github.com/supabase/vault)


## Resources

*   Official [`pgsodium` documentation](https://github.com/michelp/pgsodium)


# pgTAP: Unit Testing



`pgTAP` is a unit testing extension for Postgres.


## Overview

Let's cover some basic concepts:

*   Unit tests: allow you to test small parts of a system (like a database table!).
*   TAP: stands for [Test Anything Protocol](http://testanything.org/). It is an framework which aims to simplify the error reporting during testing.


## Enable the extension


## Testing tables

```sql
begin;
select plan( 1 );

select has_table( 'profiles' );

select * from finish();
rollback;
```

API:

*   [`has_table()`](https://pgtap.org/documentation.html#has_table): Tests whether or not a table exists in the database
*   [`has_index()`](https://pgtap.org/documentation.html#has_index): Checks for the existence of a named index associated with the named table.
*   [`has_relation()`](https://pgtap.org/documentation.html#has_relation): Tests whether or not a relation exists in the database.


## Testing columns

```sql
begin;
select plan( 2 );

select has_column( 'profiles', 'id' ); -- test that the "id" column exists in the "profiles" table
select col_is_pk( 'profiles', 'id' ); -- test that the "id" column is a primary key

select * from finish();
rollback;
```

API:

*   [`has_column()`](https://pgtap.org/documentation.html#has_column): Tests whether or not a column exists in a given table, view, materialized view or composite type.
*   [`col_is_pk()`](https://pgtap.org/documentation.html#col_is_pk): Tests whether the specified column or columns in a table is/are the primary key for that table.


## Testing RLS policies

```sql
begin;
select plan( 1 );

select policies_are(
  'public',
  'profiles',
  ARRAY [
    'Profiles are public', -- Test that there is a policy called  "Profiles are public" on the "profiles" table.
    'Profiles can only be updated by the owner'  -- Test that there is a policy called  "Profiles can only be updated by the owner" on the "profiles" table.
  ]
);

select * from finish();
rollback;
```

API:

*   [`policies_are()`](https://pgtap.org/documentation.html#policies_are): Tests that all of the policies on the named table are only the policies that should be on that table.
*   [`policy_roles_are()`](https://pgtap.org/documentation.html#policy_roles_are): Tests whether the roles to which policy applies are only the roles that should be on that policy.
*   [`policy_cmd_is()`](https://pgtap.org/documentation.html#policy_cmd_is): Tests whether the command to which policy applies is same as command that is given in function arguments.

You can also use the `results_eq()` method to test that a Policy returns the correct data:

```sql
begin;
select plan( 1 );

select results_eq(
    'select * from profiles()',
    $$VALUES ( 1, 'Anna'), (2, 'Bruce'), (3, 'Caryn')$$,
    'profiles() should return all users'
);


select * from finish();
rollback;
```

API:

*   [`results_eq()`](https://pgtap.org/documentation.html#results_eq)
*   [`results_ne()`](https://pgtap.org/documentation.html#results_ne)


## Testing functions

```sql
prepare hello_expr as select 'hello'

begin;
select plan(3);
-- You'll need to create a hello_world and is_even function
select function_returns( 'hello_world', 'text' );                   -- test if the function "hello_world" returns text
select function_returns( 'is_even', ARRAY['integer'], 'boolean' );  -- test if the function "is_even" returns a boolean
select results_eq('select * from hello_world()', 'hello_expr');          -- test if the function "hello_world" returns "hello"

select * from finish();
rollback;
```

API:

*   [`function_returns()`](https://pgtap.org/documentation.html#function_returns): Tests that a particular function returns a particular data type
*   [`is_definer()`](https://pgtap.org/documentation.html#is_definer): Tests that a function is a security definer (that is, a `setuid` function).


## Resources

*   Official [`pgTAP` documentation](https://pgtap.org/)


# pgvector: Embeddings and vector similarity



[pgvector](https://github.com/pgvector/pgvector/) is a Postgres extension for vector similarity search. It can also be used for storing [embeddings](https://supabase.com/blog/openai-embeddings-postgres-vector).

Learn more about Supabase's [AI & Vector](/docs/guides/ai) offering.


## Concepts


### Vector similarity

Vector similarity refers to a measure of the similarity between two related items. For example, if you have a list of products, you can use vector similarity to find similar products. To do this, you need to convert each product into a "vector" of numbers, using a mathematical model. You can use a similar model for text, images, and other types of data. Once all of these vectors are stored in the database, you can use vector similarity to find similar items.


### Embeddings

This is particularly useful if you're building on top of OpenAI's [GPT-3](https://openai.com/blog/gpt-3-apps/). You can create and store [embeddings](/docs/guides/ai/quickstarts/generate-text-embeddings) for retrieval augmented generation.


## Usage


### Enable the extension


## Usage


### Create a table to store vectors

```sql
create table posts (
  id serial primary key,
  title text not null,
  body text not null,
  embedding vector(384)
);
```


### Storing a vector / embedding

In this example we'll generate a vector using Transformer.js, then store it in the database using the Supabase client.

```js
import { pipeline } from '@xenova/transformers'
const generateEmbedding = await pipeline('feature-extraction', 'Supabase/gte-small')

const title = 'First post!'
const body = 'Hello world!'

// Generate a vector using Transformers.js
const output = await generateEmbedding(body, {
  pooling: 'mean',
  normalize: true,
})

// Extract the embedding output
const embedding = Array.from(output.data)

// Store the vector in Postgres
const { data, error } = await supabase.from('posts').insert({
  title,
  body,
  embedding,
})
```


## Specific usage cases


### Queries with filtering

If you use an IVFFlat or HNSW index and naively filter the results based on the value of another column, you may get fewer rows returned than requested.

For example, the following query may return fewer than 5 rows, even if 5 corresponding rows exist in the database. This is because the embedding index may not return 5 rows matching the filter.

    SELECT * FROM items WHERE category_id = 123 ORDER BY embedding <-> '[3,1,2]' LIMIT 5;

To get the exact number of requested rows, use [iterative search](https://github.com/pgvector/pgvector/?tab=readme-ov-file#iterative-index-scans) to continue scanning the index until enough results are found.


## More pgvector and Supabase resources

*   [Supabase Clippy: ChatGPT for Supabase Docs](https://supabase.com/blog/chatgpt-supabase-docs)
*   [Storing OpenAI embeddings in Postgres with pgvector](https://supabase.com/blog/openai-embeddings-postgres-vector)
*   [A ChatGPT Plugins Template built with Supabase Edge Runtime](https://supabase.com/blog/building-chatgpt-plugins-template)
*   [Template for building your own custom ChatGPT style doc search](https://github.com/supabase-community/nextjs-openai-doc-search)


# plpgsql_check: PL/pgSQL Linter



[plpgsql\_check](https://github.com/okbob/plpgsql_check) is a Postgres extension that lints plpgsql for syntax, semantic and other related issues. The tool helps developers to identify and correct errors before executing the code. plpgsql\_check is most useful for developers who are working with large or complex SQL codebases, as it can help identify and resolve issues early in the development cycle.


## Enable the extension


## API

*   [`plpgsql_check_function( ... )`](https://github.com/okbob/plpgsql_check#active-mode): Scans a function for errors.

`plpgsql_check_function` is highly customizable. For a complete list of available arguments see [the docs](https://github.com/okbob/plpgsql_check#arguments)


## Usage

To demonstrate `plpgsql_check` we can create a function with a known error. In this case we create a function `some_func`, that references a non-existent column `place.created_at`.

```sql
create table place(
  x float,
  y float
);

create or replace function public.some_func()
  returns void
  language plpgsql
as $$
declare
  rec record;
begin
  for rec in select * from place
  loop
    -- Bug: There is no column `created_at` on table `place`
    raise notice '%', rec.created_at;
  end loop;
end;
$$;
```

Note that executing the function would not catch the invalid reference error because the `loop` does not execute if no rows are present in the table.

```sql
select public.some_func();
  some_func
 ───────────

 (1 row)
```

Now we can use plpgsql\_check's `plpgsql_check_function` function to identify the known error.

```sql
select plpgsql_check_function('public.some_func()');

                   plpgsql_check_function
------------------------------------------------------------
 error:42703:8:RAISE:record "rec" has no field "created_at"
 Context: SQL expression "rec.created_at"
```


## Resources

*   Official [`plpgsql_check` documentation](https://github.com/okbob/plpgsql_check)


# plv8: JavaScript Language



The `plv8` extension allows you use JavaScript within Postgres.


## Overview

While Postgres natively runs SQL, it can also run other procedural languages.
`plv8` allows you to run JavaScript code - specifically any code that runs on the [V8 JavaScript engine](https://v8.dev).

It can be used for database functions, triggers, queries and more.


## Enable the extension


## Create `plv8` functions

Functions written in `plv8` are written just like any other Postgres functions, only
with the `language` identifier set to `plv8`.

```sql
create or replace function function_name()
returns void as $$
    // V8 JavaScript
    // code
    // here
$$ language plv8;
```

You can call `plv8` functions like any other Postgres function:


## Examples


### Scalar functions

A [scalar function](https://plv8.github.io/#scalar-function-calls) is anything that takes in some user input and returns a single result.

```sql
create or replace function hello_world(name text)
returns text as $$

    let output = `Hello, ${name}!`;
    return output;

$$ language plv8;
```


### Executing SQL

You can execute SQL within `plv8` code using the [`plv8.execute` function](https://plv8.github.io/#plv8-execute).

```sql
create or replace function update_user(id bigint, first_name text)
returns smallint as $$

    var num_affected = plv8.execute(
        'update profiles set first_name = $1 where id = $2',
        [first_name, id]
    );

    return num_affected;
$$ language plv8;
```


### Set-returning functions

A [set-returning function](https://plv8.github.io/#set-returning-function-calls) is anything that returns a full set of results - for example, rows in a table.

```sql
create or replace function get_messages()
returns setof messages as $$

    var json_result = plv8.execute(
        'select * from messages'
    );

    return json_result;
$$ language plv8;

select * from get_messages();
```


## Resources

*   Official [`plv8` documentation](https://plv8.github.io/)
*   [plv8 GitHub Repository](https://github.com/plv8/plv8)


# PostGIS: Geo queries



[PostGIS](https://postgis.net/) is a Postgres extension that allows you to interact with Geo data within Postgres. You can sort your data by geographic location, get data within certain geographic boundaries, and do much more with it.


## Overview

While you may be able to store simple lat/long geographic coordinates as a set of decimals, it does not scale very well when you try to query through a large data set. PostGIS comes with special data types that are efficient, and indexable for high scalability.

The additional data types that PostGIS provides include [Point](https://postgis.net/docs/using_postgis_dbmanagement.html#Point), [Polygon](https://postgis.net/docs/using_postgis_dbmanagement.html#Polygon), [LineString](https://postgis.net/docs/using_postgis_dbmanagement.html#LineString), and many more to represent different types of geographical data. In this guide, we will mainly focus on how to interact with `Point` type, which represents a single set of latitude and longitude. If you are interested in digging deeper, you can learn more about different data types on the [data management section of PostGIS docs](https://postgis.net/docs/using_postgis_dbmanagement.html).


## Enable the extension

You can get started with PostGIS by enabling the PostGIS extension in your Supabase dashboard.


## Examples

Now that we are ready to get started with PostGIS, let’s create a table and see how we can utilize PostGIS for some typical use cases. Let’s imagine we are creating a simple restaurant-searching app.

Let’s create our table. Each row represents a restaurant with its location stored in `location` column as a `Point` type.

```sql
create table if not exists public.restaurants (
	id int generated by default as identity primary key,
	name text not null,
	location gis.geography(POINT) not null
);
```

We can then set a [spatial index](https://postgis.net/docs/using_postgis_dbmanagement.html#build-indexes) on the `location` column of this table.

```sql
create index restaurants_geo_index
  on public.restaurants
  using GIST (location);
```


### Inserting data

You can insert geographical data through SQL or through our API.

Notice the order in which you pass the latitude and longitude. Longitude comes first, and is because longitude represents the x-axis of the location. Another thing to watch for is when inserting data from the client library, there is no comma between the two values, just a single space.

At this point, if you go into your Supabase dashboard and look at the data, you will notice that the value of the `location` column looks something like this.

    0101000020E6100000A4DFBE0E9C91614044FAEDEBC0494240

We can query the `restaurants` table directly, but it will return the `location` column in the format you see above.
We will create [database functions](https://supabase.com/docs/guides/database/functions) so that we can use the [st\_y()](https://postgis.net/docs/ST_Y.html) and [st\_x()](https://postgis.net/docs/ST_X.html) function to convert it back to lat and long floating values.


### Order by distance

Sorting datasets from closest to farthest, sometimes called nearest-neighbor sort, is a very common use case in Geo-queries. PostGIS can handle it with the use of the [`<->`](https://postgis.net/docs/geometry_distance_knn.html) operator. `<->` operator returns the two-dimensional distance between two geometries and will utilize the spatial index when used within `order by` clause. You can create the following database function to sort the restaurants from closest to farthest by passing the current locations as parameters.

```sql
create or replace function nearby_restaurants(lat float, long float)
returns table (id public.restaurants.id%TYPE, name public.restaurants.name%TYPE, lat float, long float, dist_meters float)
set search_path = ''
language sql
as $$
  select id, name, gis.st_y(location::gis.geometry) as lat, gis.st_x(location::gis.geometry) as long, gis.st_distance(location, gis.st_point(long, lat)::gis.geography) as dist_meters
  from public.restaurants
  order by location operator(gis.<->) gis.st_point(long, lat)::gis.geography;
$$;
```

Before being able to call this function from our client we need to grant access to our `gis` schema:

```sql
grant usage on schema gis to anon, authenticated;
```

Now you can call this function from your client using `rpc()` like this:


### Finding all data points within a bounding box

![Searching within a bounding box of a map](/docs/img/guides/database/extensions/postgis/map.png)

When you are working on a map-based application where the user scrolls through your map, you might want to load the data that lies within the bounding box of the map every time your users scroll. PostGIS can return the rows that are within the bounding box just by supplying the bottom left and the top right coordinates. Let’s look at what the function would look like:

```sql
create or replace function restaurants_in_view(min_lat float, min_long float, max_lat float, max_long float)
returns table (id public.restaurants.id%TYPE, name public.restaurants.name%TYPE, lat float, long float)
set search_path to ''
language sql
as $$
	select id, name, gis.st_y(location::gis.geometry) as lat, gis.st_x(location::gis.geometry) as long
	from public.restaurants
	where location operator(gis.&&) gis.ST_SetSRID(gis.ST_MakeBox2D(gis.ST_Point(min_long, min_lat), gis.ST_Point(max_long, max_lat)), 4326)
$$;
```

The [`&&`](https://postgis.net/docs/geometry_overlaps.html) operator used in the `where` statement here returns a boolean of whether the bounding box of the two geometries intersect or not. We are basically creating a bounding box from the two points and finding those points that fall under the bounding box. We are also utilizing a few different PostGIS functions:

*   [ST\_MakeBox2D](https://postgis.net/docs/ST_MakeBox2D.html): Creates a 2-dimensional box from two points.
*   [ST\_SetSRID](https://postgis.net/docs/ST_SetSRID.html): Sets the [SRID](https://postgis.net/docs/manual-dev/using_postgis_dbmanagement.html#spatial_ref_sys), which is an identifier of what coordinate system to use for the geometry. 4326 is the standard longitude and latitude coordinate system.

You can call this function from your client using `rpc()` like this:


## Troubleshooting

As of PostGIS 2.3 or newer, the PostGIS extension is no longer relocatable from one schema to another. If you need to move it from one schema to another for any reason (e.g. from the public schema to the extensions schema for security reasons), you would normally run a ALTER EXTENSION to relocate the schema. However, you will now to do the following steps:

1.  Backup your Database to prevent data loss - You can do this through the [CLI](https://supabase.com/docs/reference/cli/supabase-db-dump) or Postgres backup tools such as [pg\_dumpall](https://www.postgresql.org/docs/current/backup-dump.html#BACKUP-DUMP-ALL)

2.  Drop all dependencies you created and the PostGIS extension - `DROP EXTENSION postgis CASCADE;`

3.  Enable PostGIS extension in the new schema - `CREATE EXTENSION postgis SCHEMA extensions;`

4.  Restore dropped data via the Backup if necessary from step 1 with your tool of choice.


## Resources

*   [Official PostGIS documentation](https://postgis.net/documentation/)


# postgres_fdw



The extension enables Postgres to query tables and views on a remote Postgres server.


## Enable the extension


## Create a connection to another database


### Configuring execution options


#### Fetch\_size

Maximum rows fetched per operation. For example, fetching 200 rows with `fetch_size` set to 100 requires 2 requests.

```sql
alter server "<foreign_server_name>"
options (fetch_size '10000');
```


#### Batch\_size

Maximum rows inserted per cycle. For example, inserting 200 rows with `batch_size` set to 100 requires 2 requests.

```sql
alter server "<foreign_server_name>"
options (batch_size '1000');
```


#### Extensions

Lists shared extensions. Without them, queries involving unlisted extension functions or operators may fail or omit references.

```sql
alter server "<foreign_server_name>"
options (extensions 'vector, postgis');
```

For more server options, check the extension's [official documentation](https://www.postgresql.org/docs/current/postgres-fdw.html#POSTGRES-FDW)


## Resources

*   Official [`postgres_fdw` documentation](https://www.postgresql.org/docs/current/postgres-fdw.html#POSTGRES-FDW)


# RUM: improved inverted index for full-text search based on GIN index



[RUM](https://github.com/postgrespro/rum) is an extension which adds a RUM index to Postgres.

RUM index is based on GIN that stores additional per-entry information in a posting tree. For example, positional information of lexemes or timestamps. In comparison to GIN it can use this information to make faster index-only scans for:

*   Phrase search
*   Text search with ranking by text distance operator
*   Text `SELECT`s with ordering by some non-indexed additional column e.g. by timestamp.

RUM works best in scenarios when the possible keys are highly repeatable. I.e. all texts are composed of a
limited amount of words, so per-lexeme indexing gives significant speed-up in searching texts containing word
combinations or phrases.

Main operators for ordering are:

`tsvector` `<=>` `tsquery` | `float4` | Distance between `tsvector` and `tsquery`.
value `<=>` value | `float8` | Distance between two values.

Where value is `timestamp`, `timestamptz`, `int2`, `int4`, `int8`, `float4`, `float8`, `money` and `oid`


## Usage


### Enable the extension

You can get started with rum by enabling the extension in your Supabase dashboard.


### Syntax


#### For type: `tsvector`

To understand the following you may need first to see [Official Postgres documentation on text
search](https://www.postgresql.org/docs/current/functions-textsearch.html)

`rum_tsvector_ops`

```sql
CREATE TABLE test_rum(t text, a tsvector);

CREATE TRIGGER tsvectorupdate
BEFORE UPDATE OR INSERT ON test_rum
FOR EACH ROW EXECUTE PROCEDURE tsvector_update_trigger('a', 'pg_catalog.english', 't');

INSERT INTO test_rum(t) VALUES ('The situation is most beautiful');
INSERT INTO test_rum(t) VALUES ('It is a beautiful');
INSERT INTO test_rum(t) VALUES ('It looks like a beautiful place');

CREATE INDEX rumidx ON test_rum USING rum (a rum_tsvector_ops);
```

And we can execute `tsvector` selects with ordering by text distance operator:

```sql
SELECT t, a `<=>` to_tsquery('english', 'beautiful | place') AS rank
    FROM test_rum
    WHERE a @@ to_tsquery('english', 'beautiful | place')
    ORDER BY a `<=>` to_tsquery('english', 'beautiful | place');
                t                |  rank
---------------------------------+---------
 It looks like a beautiful place | 8.22467
 The situation is most beautiful | 16.4493
 It is a beautiful               | 16.4493
(3 rows)
```

`rum_tsvector_addon_ops`

```sql
CREATE TABLE tsts (id int, t tsvector, d timestamp);
CREATE INDEX tsts_idx ON tsts USING rum (t rum_tsvector_addon_ops, d)
    WITH (attach = 'd', to = 't');
```

Now we can execute the selects with ordering distance operator on attached column:

```sql
SELECT id, d, d `<=>` '2016-05-16 14:21:25' FROM tsts WHERE t @@ 'wr&qh' ORDER BY d `<=>` '2016-05-16 14:21:25' LIMIT 5;
 id  |                d                |   ?column?
-----+---------------------------------+---------------
 355 | Mon May 16 14:21:22.326724 2016 |      2.673276
 354 | Mon May 16 13:21:22.326724 2016 |   3602.673276
 371 | Tue May 17 06:21:22.326724 2016 |  57597.326724
 406 | Wed May 18 17:21:22.326724 2016 | 183597.326724
 415 | Thu May 19 02:21:22.326724 2016 | 215997.326724
(5 rows)
```


#### For type: `anyarray`

`rum_anyarray_ops`

This operator class stores `anyarray` elements with length of the array. It supports operators `&&`, `@>`, `<@`, `=`, `%` operators. It also supports ordering by `<=>` operator.

```sql
CREATE TABLE test_array (i int2[]);
INSERT INTO test_array VALUES ('{}'), ('{0}'), ('{1,2,3,4}'), ('{1,2,3}'), ('{1,2}'), ('{1}');
CREATE INDEX idx_array ON test_array USING rum (i rum_anyarray_ops);
```

Now we can execute the query using index scan:

```sql
SELECT * FROM test_array WHERE i && '{1}' ORDER BY i `<=>` '{1}' ASC;
     i
-----------
 {1}
 {1,2}
 {1,2,3}
 {1,2,3,4}
(4 rows)
```

`rum_anyarray_addon_ops`

The does the same with `anyarray` index as `rum_tsvector_addon_ops` i.e. allows to order select results using distance
operator by attached column.


## Limitations

`RUM` has slower build and insert times than `GIN` due to:

1.  It is bigger due to the additional attributes stored in the index.
2.  It uses generic WAL records.


## Resources

*   [Official RUM documentation](https://github.com/postgrespro/rum)


# timescaledb: Time-Series data



[`timescaledb`](https://docs.timescale.com/timescaledb/latest/) is a Postgres extension designed for improved handling of time-series data. It provides a scalable, high-performance solution for storing and querying time-series data on top of a standard Postgres database.

`timescaledb` uses a time-series-aware storage model and indexing techniques to improve performance of Postgres in working with time-series data. The extension divides data into chunks based on time intervals, allowing it to scale efficiently, especially for large data sets. The data is then compressed, optimized for write-heavy workloads, and partitioned for parallel processing. `timescaledb` also includes a set of functions, operators, and indexes that work with time-series data to reduce query times, and make data easier to work with.


## Enable the extension


## Usage

To demonstrate how `timescaledb` works, let's consider a simple example where we have a table that stores temperature data from different sensors. We will create a table named "temperatures" and store data for two sensors.

First we create a hypertable, which is a virtual table that is partitioned into chunks based on time intervals. The hypertable acts as a proxy for the actual table and makes it easy to query and manage time-series data.

```sql
create table temperatures (
  time timestamptz not null,
  sensor_id int not null,
  temperature double precision not null
);

select create_hypertable('temperatures', 'time');
```

Next, we can populate some values

```sql
insert into temperatures (time, sensor_id, temperature)
values
    ('2023-02-14 09:00:00', 1, 23.5),
    ('2023-02-14 09:00:00', 2, 21.2),
    ('2023-02-14 09:05:00', 1, 24.5),
    ('2023-02-14 09:05:00', 2, 22.3),
    ('2023-02-14 09:10:00', 1, 25.1),
    ('2023-02-14 09:10:00', 2, 23.9),
    ('2023-02-14 09:15:00', 1, 24.9),
    ('2023-02-14 09:15:00', 2, 22.7),
    ('2023-02-14 09:20:00', 1, 24.7),
    ('2023-02-14 09:20:00', 2, 23.5);
```

And finally we can query the table using `timescaledb`'s `time_bucket` function to divide the time-series into intervals of the specified size (in this case, 1 hour) averaging the `temperature` reading within each group.

```sql
select
    time_bucket('1 hour', time) AS hour,
    avg(temperature) AS average_temperature
from
    temperatures
where
    sensor_id = 1
    and time > NOW() - interval '1 hour'
group by
    hour;
```


## Resources

*   Official [`timescaledb` documentation](https://docs.timescale.com/timescaledb/latest/)


# uuid-ossp: Unique Identifiers



The `uuid-ossp` extension can be used to generate a `UUID`.


## Overview

A `UUID` is a "Universally Unique Identifier" and it is, for practical purposes, unique.
This makes them particularly well suited as Primary Keys. It is occasionally referred to as a `GUID`, which stands for "Globally Unique Identifier".


## Enable the extension

**Note**:
Currently `uuid-ossp` extension is enabled by default and cannot be disabled.


## The `uuid` type

Once the extension is enabled, you now have access to a `uuid` type.


## `uuid_generate_v1()`

Creates a UUID value based on the combination of computer’s MAC address, current timestamp, and a random value.


## `uuid_generate_v4()`

Creates UUID values based solely on random numbers. You can also use Postgres's built-in [`gen_random_uuid()`](https://www.postgresql.org/docs/current/functions-uuid.html) function to generate a UUIDv4.


## Examples


### Within a query

```sql
select uuid_generate_v4();
```


### As a primary key

Automatically create a unique, random ID in a table:

```sql
create table contacts (
  id uuid default uuid_generate_v4(),
  first_name text,
  last_name text,
  primary key (id)
);
```


## Resources

*   [Choosing a Postgres Primary Key](https://supabase.com/blog/choosing-a-postgres-primary-key)
*   [The Basics Of Postgres `UUID` Data Type](https://www.postgresqltutorial.com/postgresql-uuid/)


# Foreign Data Wrappers

Connecting to external systems using Postgres Foreign Data Wrappers.

Foreign Data Wrappers (FDW) are a core feature of Postgres that allow you to access and query data stored in external data sources as if they were native Postgres tables.

Postgres includes several built-in foreign data wrappers, such as [`postgres_fdw`](https://www.postgresql.org/docs/current/postgres-fdw.html) for accessing other Postgres databases, and [`file_fdw`](https://www.postgresql.org/docs/current/file-fdw.html) for reading data from files. Supabase extends this feature to query other databases or any other external systems. We do this with our open source [Wrappers](https://github.com/supabase/wrappers) framework. In these guides we'll refer to them as "Wrappers", Foreign Data Wrappers, or FDWs. They are conceptually the same thing.


## Concepts

Wrappers introduce some new terminology and different workflows.


### Remote servers

A Remote Server is an external database, API, or any system containing data that you want to query from your Postgres database. Examples include:

*   An external database, like Postgres or Firebase.
*   A remote data warehouse, like ClickHouse, BigQuery, or Snowflake.
*   An API, like Stripe or GitHub.

It's possible to connect to multiple remote servers of the same type. For example, you can connect to two different Firebase projects within the same Supabase database.


### Foreign tables

A table in your database which maps to some data inside a Remote Server.

Examples:

*   An `analytics` table which maps to a table inside your data warehouse.
*   A `subscriptions` table which maps to your Stripe subscriptions.
*   A `collections` table which maps to a Firebase collection.

Although a foreign table behaves like any other table, the data is not stored inside your database. The data remains inside the Remote Server.


### ETL with Wrappers

ETL stands for Extract, Transform, Load. It's an established process for moving data from one system to another. For example, it's common to move data from a production database to a data warehouse.

There are many popular ETL tools, such as [Fivetran](https://fivetran.com/) and [Airbyte](https://airbyte.io/).

Wrappers provide an alternative to these tools. You can use SQL to move data from one table to another:

```sql
-- Copy data from your production database to your
-- data warehouse for the last 24 hours:

insert into warehouse.analytics
select * from public.analytics
where ts > (now() - interval '1 DAY');
```

This approach provides several benefits:

1.  **Simplicity:** the Wrappers API is just SQL, so data engineers don't need to learn new tools and languages.
2.  **Save on time:** avoid setting up additional data pipelines.
3.  **Save on Data Engineering costs:** less infrastructure to be managed.

One disadvantage is that Wrappers are not as feature-rich as ETL tools. They also couple the ETL process to your database.


### On-demand ETL with Wrappers

Supabase extends the ETL concept with real-time data access. Instead of moving gigabytes of data from one system to another before you can query it, you can instead query the data directly from the remote server. This additional option, "Query", extends the ETL process and is called [QETL](https://www.sciencedirect.com/science/article/abs/pii/S0169023X1730438X) (pronounced "kettle"): Query, Extract, Transform, Load.

```sql
-- Get all purchases for a user from your data warehouse:
select
  auth.users.id as user_id,
  warehouse.orders.id as order_id
from
  warehouse.orders
join 
  auth.users on auth.users.id = warehouse.orders.user_id
where 
  auth.users.id = '<some_user_id>';
```

This approach has several benefits:

1.  **On-demand:** analytical data is immediately available within your application with no additional infrastructure.
2.  **Always in sync:** since the data is queried directly from the remote server, it's always up-to-date.
3.  **Integrated:** large datasets are available within your application, and can be joined with your operational/transactional data.
4.  **Save on bandwidth:** only extract/load what you need.


### Batch ETL with Wrappers

A common use case for Wrappers is to extract data from a production database and load it into a data warehouse. This can be done within your database using [pg\_cron](/docs/guides/database/extensions/pg_cron). For example, you can schedule a job to run every night to extract data from your production database and load it into your data warehouse.

```sql
-- Every day at 3am, copy data from your
-- production database to your data warehouse:
select cron.schedule(
  'nightly-etl',
  '0 3 * * *',
  $$
    insert into warehouse.analytics
    select * from public.analytics
    where ts > (now() - interval '1 DAY');
  $$
);
```

This process can be taxing on your database if you are moving large amounts of data. Often, it's better to use an external tool for batch ETL, such as [Fivetran](https://fivetran.com/) or [Airbyte](https://airbyte.io/).


### WebAssembly Wrappers

WebAssembly (Wasm) is a binary instruction format that enables high-performance execution of code on the web. Wrappers now includes a Wasm runtime, which provides a sandboxed execution environment, to run Wasm foreign data wrappers. Combined Wrappers with Wasm, developing and distributing new FDW becomes much easier and you can even build your own Wasm FDW and use it on Supabase platform.

To learn more about Wasm FDW, visit [Wrappers official documentation](https://supabase.github.io/wrappers/).


## Security

Foreign Data Wrappers do not provide Row Level Security, thus it is not advised to expose them via your API. Wrappers should *always* be stored in a private schema. For example, if you are connecting to your Stripe account, you should create a `stripe` schema to store all of your foreign tables inside. This schema should *not* be added to the “Additional Schemas” setting in the API section.

If you want to expose any of the foreign table columns to your public API, you can create a [Database Function with security definer](https://supabase.com/docs/guides/database/functions#security-definer-vs-invoker) in the `public` schema, and then you can interact with your foreign table through API. For better access control, the function should have appropriate filters on the foreign table to apply security rules based on your business needs.

As an example, go to [SQL Editor](https://supabase.com/dashboard/project/_/sql/new) and then follow below steps,

1.  Create a Stripe Products foreign table:

    ```sql
    create foreign table stripe.stripe_products (
      id text,
      name text,
      active bool,
      default_price text,
      description text,
      created timestamp,
      updated timestamp,
      attrs jsonb
    )
      server stripe_fdw_server
      options (
        object 'products',
        rowid_column 'id'
      );
    ```

2.  Create a security definer function that queries the foreign table and filters on the name prefix parameter:

    ```sql
    create function public.get_stripe_products(name_prefix text)
    returns table (
      id text,
      name text,
      active boolean,
      default_price text,
      description text
    )
    language plpgsql
    security definer set search_path = ''
    as $$
    begin
      return query
      select
        t.id,
        t.name,
        t.active,
        t.default_price,
        t.description
      from
        stripe.stripe_products t
      where
        t.name like name_prefix || '%'
      ;
    end;
    $$;
    ```

3.  Restrict the function execution to a specific role only, for example, the authenticated users:

    ```sql
    -- revoke public execute permission
    revoke execute on function public.get_stripe_products from public;
    revoke execute on function public.get_stripe_products from anon;

    -- grant execute permission to a specific role only
    grant execute on function public.get_stripe_products to authenticated;
    ```

Once the preceding steps are finished, the function can be invoked from Supabase client to query the foreign table:

```js
const { data, error } = await supabase
  .rpc('get_stripe_products', { name_prefix: 'Test' })
  .select('*')
if (error) console.error(error)
else console.log(data)
```


## Resources

*   Official [`supabase/wrappers` documentation](https://supabase.github.io/wrappers/)


# Full Text Search

How to use full text search in PostgreSQL.

Postgres has built-in functions to handle `Full Text Search` queries. This is like a "search engine" within Postgres.


## Preparation

For this guide we'll use the following example data:


## Usage

The functions we'll cover in this guide are:


### `to_tsvector()` \[#to-tsvector]

Converts your data into searchable tokens. `to_tsvector()` stands for "to text search vector." For example:

```sql
select to_tsvector('green eggs and ham');
-- Returns 'egg':2 'green':1 'ham':4
```

Collectively these tokens are called a "document" which Postgres can use for comparisons.


### `to_tsquery()` \[#to-tsquery]

Converts a query string into tokens to match. `to_tsquery()` stands for "to text search query."

This conversion step is important because we will want to "fuzzy match" on keywords.
For example if a user searches for `eggs`, and a column has the value `egg`, we probably still want to return a match.


### Match: `@@` \[#match]

The `@@` symbol is the "match" symbol for Full Text Search. It returns any matches between a `to_tsvector` result and a `to_tsquery` result.

Take the following example:

The equality symbol above (`=`) is very "strict" on what it matches. In a full text search context, we might want to find all "Harry Potter" books and so we can rewrite the
example above:


## Basic full text queries


### Search a single column

To find all `books` where the `description` contain the word `big`:


### Search multiple columns

Right now there is no direct way to use JavaScript or Dart to search through multiple columns but you can do it by creating [computed columns](https://postgrest.org/en/stable/api.html#computed-virtual-columns) on the database.

To find all `books` where `description` or `title` contain the word `little`:


### Match all search words

To find all `books` where `description` contains BOTH of the words `little` and `big`, we can use the `&` symbol:


### Match any search words

To find all `books` where `description` contain ANY of the words `little` or `big`, use the `|` symbol:

Notice how searching for `big` includes results with the word `bigger` (or `biggest`, etc).


## Partial search

Partial search is particularly useful when you want to find matches on substrings within your data.


### Implementing partial search

You can use the `:*` syntax with `to_tsquery()`. Here's an example that searches for any book titles beginning with "Lit":

```sql
select title from books where to_tsvector(title) @@ to_tsquery('Lit:*');
```


### Extending functionality with RPC

To make the partial search functionality accessible through the API, you can wrap the search logic in a stored procedure.

After creating this function, you can invoke it from your application using the SDK for your platform. Here's an example:

This function takes a prefix parameter and returns all books where the title contains a word starting with that prefix. The `:*` operator is used to denote a prefix match in the `to_tsquery()` function.


## Handling spaces in queries

When you want the search term to include a phrase or multiple words, you can concatenate words using a `+` as a placeholder for space:

```sql
select * from search_books_by_title_prefix('Little+Puppy');
```


## Creating indexes

Now that we have Full Text Search working, let's create an `index`. This will allow Postgres to "build" the documents preemptively so that they
don't need to be created at the time we execute the query. This will make our queries much faster.


### Searchable columns

Let's create a new column `fts` inside the `books` table to store the searchable index of the `title` and `description` columns.

We can use a special feature of Postgres called
[Generated Columns](https://www.postgresql.org/docs/current/ddl-generated-columns.html)
to ensure that the index is updated any time the values in the `title` and `description` columns change.


### Search using the new column

Now that we've created and populated our index, we can search it using the same techniques as before:


## Query operators

Visit [Postgres: Text Search Functions and Operators](https://www.postgresql.org/docs/current/functions-textsearch.html)
to learn about additional query operators you can use to do more advanced `full text queries`, such as:


### Proximity: `<->` \[#proximity]

The proximity symbol is useful for searching for terms that are a certain "distance" apart.
For example, to find the phrase `big dreams`, where the a match for "big" is followed immediately by a match for "dreams":

We can also use the `<->` to find words within a certain distance of each other. For example to find `year` and `school` within 2 words of each other:


### Negation: `!` \[#negation]

The negation symbol can be used to find phrases which *don't* contain a search term.
For example, to find records that have the word `big` but not `little`:


## Resources

*   [Postgres: Text Search Functions and Operators](https://www.postgresql.org/docs/12/functions-textsearch.html)


# Database Functions



Postgres has built-in support for [SQL functions](https://www.postgresql.org/docs/current/sql-createfunction.html).
These functions live inside your database, and they can be [used with the API](../../reference/javascript/rpc).


## Quick demo


## Getting started

Supabase provides several options for creating database functions. You can use the Dashboard or create them directly using SQL.
We provide a SQL editor within the Dashboard, or you can [connect](../../guides/database/connecting-to-postgres) to your database
and run the SQL queries yourself.

1.  Go to the "SQL editor" section.
2.  Click "New Query".
3.  Enter the SQL to create or replace your Database function.
4.  Click "Run" or cmd+enter (ctrl+enter).


## Simple functions

Let's create a basic Database Function which returns a string "hello world".

```sql
create or replace function hello_world() -- 1
returns text -- 2
language sql -- 3
as $$  -- 4
  select 'hello world';  -- 5
$$; --6

```

After the Function is created, we have several ways of "executing" the function - either directly inside the database using SQL, or with one of the client libraries.


## Returning data sets

Database Functions can also return data sets from [Tables](../../guides/database/tables) or Views.

For example, if we had a database with some Star Wars data inside:

We could create a function which returns all the planets:

```sql
create or replace function get_planets()
returns setof planets
language sql
as $$
  select * from planets;
$$;
```

Because this function returns a table set, we can also apply filters and selectors. For example, if we only wanted the first planet:


## Passing parameters

Let's create a Function to insert a new planet into the `planets` table and return the new ID. Note that this time we're using the `plpgsql` language.

```sql
create or replace function add_planet(name text)
returns bigint
language plpgsql
as $$
declare
  new_row bigint;
begin
  insert into planets(name)
  values (add_planet.name)
  returning id into new_row;

  return new_row;
end;
$$;
```

Once again, you can execute this function either inside your database using a `select` query, or with the client libraries:


## Suggestions


### Database Functions vs Edge Functions

For data-intensive operations, use Database Functions, which are executed within your database
and can be called remotely using the [REST and GraphQL API](../api).

For use-cases which require low-latency, use [Edge Functions](../../guides/functions), which are globally-distributed and can be written in Typescript.


### Security `definer` vs `invoker`

Postgres allows you to specify whether you want the function to be executed as the user *calling* the function (`invoker`), or as the *creator* of the function (`definer`). For example:

```sql
create function hello_world()
returns text
language plpgsql
security definer set search_path = ''
as $$
begin
  select 'hello world';
end;
$$;
```

It is best practice to use `security invoker` (which is also the default). If you ever use `security definer`, you *must* set the `search_path`.
If you use an empty search path (`search_path = ''`), you must explicitly state the schema for every relation in the function body (e.g. `from public.table`).
This limits the potential damage if you allow access to schemas which the user executing the function should not have.


### Function privileges

By default, database functions can be executed by any role. There are two main ways to restrict this:

1.  On a case-by-case basis. Specifically revoke permissions for functions you want to protect. Execution needs to be revoked for both `public` and the role you're restricting:

    ```sql
    revoke execute on function public.hello_world from public;
    revoke execute on function public.hello_world from anon;
    ```

2.  Restrict function execution by default. Specifically *grant* access when you want a function to be executable by a specific role.

    To restrict all existing functions, revoke execution permissions from both `public` *and* the role you want to restrict:

    ```sql
    revoke execute on all functions in schema public from public;
    revoke execute on all functions in schema public from anon, authenticated;
    ```

    To restrict all new functions, change the default privileges for both `public` *and* the role you want to restrict:

    ```sql
    alter default privileges in schema public revoke execute on functions from public;
    alter default privileges in schema public revoke execute on functions from anon, authenticated;
    ```

    You can then regrant permissions for a specific function to a specific role:

    ```sql
    grant execute on function public.hello_world to authenticated;
    ```


### Debugging functions

You can add logs to help you debug functions. This is especially recommended for complex functions.

Good targets to log include:

*   Values of (non-sensitive) variables
*   Returned results from queries


#### General logging

To create custom logs in the [Dashboard's Postgres Logs](https://supabase.com/dashboard/project/_/logs/postgres-logs), you can use the `raise` keyword. By default, there are 3 observed severity levels:

*   `log`
*   `warning`
*   `exception` (error level)

```sql
create function logging_example(
  log_message text,
  warning_message text,
  error_message text
)
returns void
language plpgsql
as $$
begin
  raise log 'logging message: %', log_message;
  raise warning 'logging warning: %', warning_message;

  -- immediately ends function and reverts transaction
  raise exception 'logging error: %', error_message;
end;
$$;

select logging_example('LOGGED MESSAGE', 'WARNING MESSAGE', 'ERROR MESSAGE');
```


#### Error handling

You can create custom errors with the `raise exception` keywords.

A common pattern is to throw an error when a variable doesn't meet a condition:

```sql
create or replace function error_if_null(some_val text)
returns text
language plpgsql
as $$
begin
  -- error if some_val is null
  if some_val is null then
    raise exception 'some_val should not be NULL';
  end if;
  -- return some_val if it is not null
  return some_val;
end;
$$;

select error_if_null(null);
```

Value checking is common, so Postgres provides a shorthand: the `assert` keyword. It uses the following format:

```sql
-- throw error when condition is false
assert <some condition>, 'message';
```

Below is an example

```sql
create function assert_example(name text)
returns uuid
language plpgsql
as $$
declare
  student_id uuid;
begin
  -- save a user's id into the user_id variable
  select
    id into student_id
  from attendance_table
  where student = name;

  -- throw an error if the student_id is null
  assert student_id is not null, 'assert_example() ERROR: student not found';

  -- otherwise, return the user's id
  return student_id;
end;
$$;

select assert_example('Harry Potter');
```

Error messages can also be captured and modified with the `exception` keyword:

```sql
create function error_example()
returns void
language plpgsql
as $$
begin
  -- fails: cannot read from nonexistent table
  select * from table_that_does_not_exist;

  exception
      when others then
          raise exception 'An error occurred in function <function name>: %', sqlerrm;
end;
$$;
```


#### Advanced logging

For more complex functions or complicated debugging, try logging:

*   Formatted variables
*   Individual rows
*   Start and end of function calls

```sql
create or replace function advanced_example(num int default 10)
returns text
language plpgsql
as $$
declare
    var1 int := 20;
    var2 text;
begin
    -- Logging start of function
    raise log 'logging start of function call: (%)', (select now());

    -- Logging a variable from a SELECT query
    select
      col_1 into var1
    from some_table
    limit 1;
    raise log 'logging a variable (%)', var1;

    -- It is also possible to avoid using variables, by returning the values of your query to the log
    raise log 'logging a query with a single return value(%)', (select col_1 from some_table limit 1);

    -- If necessary, you can even log an entire row as JSON
    raise log 'logging an entire row as JSON (%)', (select to_jsonb(some_table.*) from some_table limit 1);

    -- When using INSERT or UPDATE, the new value(s) can be returned
    -- into a variable.
    -- When using DELETE, the deleted value(s) can be returned.
    -- All three operations use "RETURNING value(s) INTO variable(s)" syntax
    insert into some_table (col_2)
    values ('new val')
    returning col_2 into var2;

    raise log 'logging a value from an INSERT (%)', var2;

    return var1 || ',' || var2;
exception
    -- Handle exceptions here if needed
    when others then
        raise exception 'An error occurred in function <advanced_example>: %', sqlerrm;
end;
$$;

select advanced_example();
```


## Resources

*   Official Client libraries: [JavaScript](../../reference/javascript/rpc) and [Flutter](../../reference/dart/rpc)
*   Community client libraries: [github.com/supabase-community](https://github.com/supabase-community)
*   Postgres Official Docs: [Chapter 9. Functions and Operators](https://www.postgresql.org/docs/current/functions.html)
*   Postgres Reference: [CREATE FUNCTION](https://www.postgresql.org/docs/9.1/sql-createfunction.html)


## Deep dive


### Create Database Functions


### Call Database Functions using JavaScript


### Using Database Functions to call an external API


# Hardening the Data API



Your database's automatically generated Data API exposes the `public` schema by default. If your `public` schema is used by other tools as a default space, you might want to lock down this schema. This helps prevent accidental exposure of data that's automatically added to `public`.

There are two levels of security hardening for the Data API:

*   Disabling the Data API entirely. This is recommended if you *never* need to access your database via Supabase client libraries or the REST and GraphQL endpoints.
*   Removing the `public` schema from the Data API and replacing it with a custom schema (such as `api`).


## Disabling the Data API

You can disable the Data API entirely if you never intend to use the Supabase client libraries or the REST and GraphQL data endpoints. For example, if you only access your database via a direct connection on the server, disabling the Data API gives you the greatest layer of protection.

1.  Go to [API Settings](/dashboard/project/_/settings/api) in the Supabase Dashboard.
2.  Under **Data API Settings**, toggle **Enable Data API** off.


## Exposing a custom schema instead of `public`

If you want to use the Data API but with increased security, you can expose a custom schema instead of `public`. By not using `public`, which is often used as a default space and has laxer default permissions, you get more conscious control over your exposed data.

Any data, views, or functions that should be exposed need to be deliberately put within your custom schema (which we will call `api`), rather than ending up there by default.


### Step 1: Remove `public` from exposed schemas

1.  Go to [**API Settings**](/dashboard/project/_/settings/api) in the Supabase Dashboard.
2.  Under **Data API Settings**, remove `public` from **Exposed schemas**. Also remove `public` from **Extra search path**.
3.  Click **Save**.
4.  Go to [**Database Extensions**](/dashboard/project/_/database/extensions) and disable the `pg_graphql` extension.


### Step 2: Create an `api` schema and expose it

1.  Connect to your database. You can use `psql`, the [Supabase SQL Editor](/dashboard/project/_/sql), or the Postgres client of your choice.

2.  Create a new schema named `api`:

    ```sql
    create schema if not exists api;
    ```

3.  Grant the `anon` and `authenticated` roles usage on this schema.

    ```sql
    grant usage on schema api to anon, authenticated;
    ```

4.  Go to [API Settings](/dashboard/project/_/settings/api) in the Supabase Dashboard.

5.  Under **Data API Settings**, add `api` to **Exposed schemas**. Make sure it is the first schema in the list, so that it will be searched first by default.

6.  Under these new settings, `anon` and `authenticated` can execute functions defined in the `api` schema, but they have no automatic permissions on any tables. On a table-by-table basis, you can grant them permissions. For example:

    ```sql
    grant select on table api.<your_table> to anon;
    grant select, insert, update, delete on table api.<your_table> to authenticated;
    ```


# Import data into Supabase



You can import data into Supabase in multiple ways. The best method depends on your data size and app requirements.

If you're working with small datasets in development, you can experiment quickly using CSV import in the Supabase dashboard. If you're working with a large dataset in production, you should plan your data import to minimize app latency and ensure data integrity.


## How to import data into Supabase

You have multiple options for importing your data into Supabase:

1.  [CSV import via the Supabase dashboard](#option-1-csv-import-via-supabase-dashboard)
2.  [Bulk import using `pgloader`](#option-2-bulk-import-using-pgloader)
3.  [Using the Postgres `COPY` command](#option-3-using-postgres-copy-command)
4.  [Using the Supabase API](#option-4-using-the-supabase-api)


### Option 1: CSV import via Supabase dashboard

Supabase dashboard provides a user-friendly way to import data. However, for very large datasets, this method may not be the most efficient choice, given the size limit is 100MB. It's generally better suited for smaller datasets and quick data imports. Consider using alternative methods like pgloader for large-scale data imports.

1.  Navigate to the relevant table in the [Table Editor.](/dashboard/project/_/editor)
2.  Click on “Insert” then choose "Import Data from CSV" and follow the on-screen instructions to upload your CSV file.


### Option 2: Bulk import using pgloader

[pgloader](https://pgloader.io/) is a powerful tool for efficiently importing data into a Postgres database that supports a wide range of source database engines, including MySQL and MS SQL.

You can use it in conjunction with Supabase by following these steps:

1.  Install pgloader on your local machine or a server. For more info, you can refer to the [official pgloader installation page](https://pgloader.readthedocs.io/en/latest/install.html).

    ```bash
    $ apt-get install pgloader
    ```

2.  Create a configuration file that specifies the source data and the target Supabase database (e.g., config.load).
    Here's an example configuration file:

    ```sql
    LOAD DATABASE
        FROM sourcedb://USER:PASSWORD@HOST/SOURCE_DB
        INTO postgres://postgres.xxxx:password@xxxx.pooler.supabase.com:6543/postgres
    ALTER SCHEMA 'public' OWNER TO 'postgres';
    set wal_buffers = '64MB', max_wal_senders = 0, statement_timeout = 0, work_mem to '2GB';
    ```

    Customize the source and Supabase database URL and options to fit your specific use case:

    *   `wal_buffers`: This parameter is set to '64MB' to allocate 64 megabytes of memory for write-ahead logging buffers. A larger value can help improve write performance by caching more data in memory before writing it to disk. This can be useful during data import operations to speed up the writing of transaction logs.
    *   `max_wal_senders`: It is set to 0, to disable replication connections. This is done during the data import process to prevent replication-related conflicts and issues.
    *   `statement_timeout`: The value is set to 0, which means it's disabled, allowing SQL statements to run without a time limit.
    *   `work_mem`: It is set to '2GB', allocating 2 GB of memory for query operations. This enhances the performance of complex queries by allowing larger in-memory datasets.

3.  Run pgloader with the configuration file.
    ```jsx
    pgloader config.load
    ```

For databases using the Postgres engine, we recommend using the [pg\_dump](https://www.postgresql.org/docs/current/app-pgdump.html) and [psql](https://www.postgresql.org/docs/current/app-psql.html) command line tools.


### Option 3: Using Postgres copy command

Read more about [Bulk data loading.](/docs/guides/database/tables#bulk-data-loading)


### Option 4: Using the Supabase API

The Supabase API allows you to programmatically import data into your tables. You can use various client libraries to interact with the API and perform data import operations. This approach is useful when you need to automate data imports, and it gives you fine-grained control over the process. Refer to our [API guide](/docs/guides/api) for more details.


## Preparing to import data

Large data imports can affect your database performance. Failed imports can also cause data corruption. Importing data is a safe and common operation, but you should plan ahead if you're importing a lot of data, or if you're working in a production environment.


### 1. Back up your data

Backups help you restore your data if something goes wrong. Databases on Pro, Team and Enterprise Plans are automatically backed up on schedule, but you can also take your own backup. See [Database Backups](/docs/guides/platform/backups) for more information.


### 2. Increase statement timeouts

By default, Supabase enforces query statement timeouts to ensure fair resource allocation and prevent long-running queries from affecting the overall system. When importing large datasets, you may encounter timeouts. To address this:

*   **Increase the Statement Timeout**: You can adjust the statement timeout for your session or connection to accommodate longer-running queries. Be cautious when doing this, as excessively long queries can negatively impact system performance. Read more about [Statement Timeouts](/docs/guides/database/postgres/configuration).


### 3. Estimate your required disk size

Large datasets consume disk space. Ensure your Supabase project has sufficient disk capacity to accommodate the imported data. If you know how big your database is going to be, you can manually increase the size in your [projects database settings](/dashboard/project/_/settings/database).

Read more about [disk management](/docs/guides/platform/database-size#disk-management).


### 4. Disable triggers

When importing large datasets, it's often beneficial to disable triggers temporarily. Triggers can significantly slow down the import process, especially if they involve complex logic or referential integrity checks. After the import, you can re-enable the triggers.

To disable triggers, use the following SQL commands:

```sql
-- Disable triggers on a specific table
ALTER TABLE table_name DISABLE TRIGGER ALL;

-- To re-enable triggers
ALTER TABLE table_name ENABLE TRIGGER ALL;
```


### 5. Rebuild indices after data import is complete

Indexing is crucial for query performance, but building indices while importing a large dataset can be time-consuming. Consider building or rebuilding indices after the data import is complete. This approach can significantly speed up the import process and reduce the overall time required.

To build an index after the data import:

```sql
-- Create an index on a table
create index index_name on table_name (column_name);
```

Read more about [Managing Indexes in Postgres](/docs/guides/database/postgres/indexes).


# Debugging and monitoring



Database performance is a large topic and many factors can contribute. Some of the most common causes of poor performance include:

*   An inefficiently designed schema
*   Inefficiently designed queries
*   A lack of indexes causing slower than required queries over large tables
*   Unused indexes causing slow `INSERT`, `UPDATE` and `DELETE` operations
*   Not enough compute resources, such as memory, causing your database to go to disk for results too often
*   Lock contention from multiple queries operating on highly utilized tables
*   Large amount of bloat on your tables causing poor query planning

You can examine your database and queries for these issues using either the [Supabase CLI](/docs/guides/local-development/cli/getting-started) or SQL.


## Using the CLI

The Supabase CLI comes with a range of tools to help inspect your Postgres instances for potential issues. The CLI gets the information from . Therefore, most tools provided are compatible with any Postgres databases regardless if they are a Supabase project or not.

You can find installation instructions for the the Supabase CLI .


### The `inspect db` command

The inspection tools for your Postgres database are under then `inspect db` command. You can get a full list of available commands by running `supabase inspect db help`.

    $ supabase inspect db help
    Tools to inspect your Supabase database

    Usage:
      supabase inspect db [command]

    Available Commands:
      bloat                Estimates space allocated to a relation that is full of dead tuples
      blocking             Show queries that are holding locks and the queries that are waiting for them to be released
      cache-hit            Show cache hit rates for tables and indices

    ...


### Connect to any Postgres database

Most inspection commands are Postgres agnostic. You can run inspection routines on any Postgres database even if it is not a Supabase project by providing a connection string via `--db-url`.

For example you can connect to your local Postgres instance:

    supabase --db-url postgresql://postgres:postgres@localhost:5432/postgres inspect db bloat


### Connect to a Supabase instance

Working with Supabase, you can link the Supabase CLI with your project:

    supabase link --project-ref <project-id>

Then the CLI will automatically connect to your Supabase project whenever you are in the project folder and you no longer need to provide `—db-url`.


### Inspection commands

Below are the `db` inspection commands provided, grouped by different use cases.


#### Disk storage

These commands are handy if you are running low on disk storage:

*   [bloat](/docs/reference/cli/supabase-inspect-db-bloat) - estimates the amount of wasted space
*   [vacuum-stats](/docs/reference/cli/supabase-inspect-db-vacuum-stats) - gives information on waste collection routines
*   [table-record-counts](/docs/reference/cli/supabase-inspect-db-table-record-counts) - estimates the number of records per table
*   [table-sizes](/docs/reference/cli/supabase-inspect-db-table-sizes) - shows the sizes of tables
*   [index-sizes](/docs/reference/cli/supabase-inspect-db-index-sizes) - shows the sizes of individual index
*   [table-index-sizes](/docs/reference/cli/supabase-inspect-db-table-index-sizes) - shows the sizes of indexes for each table


#### Query performance

The commands below are useful if your Postgres database consumes a lot of resources like CPU, RAM or Disk IO. You can also use them to investigate slow queries.

*   [cache-hit](/docs/reference/cli/supabase-inspect-db-cache-hit) - shows how efficient your cache usage is overall
*   [unused-indexes](/docs/reference/cli/supabase-inspect-db-unused-indexes) - shows indexes with low index scans
*   [index-usage](/docs/reference/cli/supabase-inspect-db-index-usage) - shows information about the efficiency of indexes
*   [seq-scans](/docs/reference/cli/supabase-inspect-db-seq-scans) - show number of sequential scans recorded against all tables
*   [long-running-queries](/docs/reference/cli/supabase-inspect-db-long-running-queries) - shows long running queries that are executing right now
*   [outliers](/docs/reference/cli/supabase-inspect-db-outliers) - shows queries with high execution time but low call count and queries with high proportion of execution time spent on synchronous I/O


#### Locks

*   [locks](/docs/reference/cli/supabase-inspect-db-locks) - shows statements which have taken out an exclusive lock on a relation
*   [blocking](/docs/reference/cli/supabase-inspect-db-blocking) - shows statements that are waiting for locks to be released


#### Connections

*   [role-connections](/docs/reference/cli/supabase-inspect-db-role-connections) - shows number of active connections for all database roles (Supabase-specific command)
*   [replication-slots](/docs/reference/cli/supabase-inspect-db-replication-slots) - shows information about replication slots on the database


### Notes on `pg_stat_statements`

Following commands require `pg_stat_statements` to be enabled: calls, locks, cache-hit, blocking, unused-indexes, index-usage, bloat, outliers, table-record-counts, replication-slots, seq-scans, vacuum-stats, long-running-queries.

When using `pg_stat_statements` also take note that it only stores the latest 5,000 statements. Moreover, consider resetting the analysis after optimizing any queries by running `select pg_stat_statements_reset();`

Learn more about pg\_stats [here](https://supabase.com/docs/guides/database/extensions/pg_stat_statements).


## Using SQL


### Postgres cumulative statistics system

Postgres collects data about its own operations using the [cumulative statistics system](https://www.postgresql.org/docs/current/monitoring-stats.html). In addition to this, every Supabase project has the [pg\_stat\_statements extension](/docs/guides/database/extensions/pg_stat_statements) enabled by default. This extension records query execution performance details and is the best way to find inefficient queries. This information can be combined with the Postgres query plan analyzer to develop more efficient queries.

Here are some example queries to get you started.


### Most frequently called queries

```sql
select
  auth.rolname,
  statements.query,
  statements.calls,
  -- -- Postgres 13, 14, 15
  statements.total_exec_time + statements.total_plan_time as total_time,
  statements.min_exec_time + statements.min_plan_time as min_time,
  statements.max_exec_time + statements.max_plan_time as max_time,
  statements.mean_exec_time + statements.mean_plan_time as mean_time,
  -- -- Postgres <= 12
  -- total_time,
  -- min_time,
  -- max_time,
  -- mean_time,
  statements.rows / statements.calls as avg_rows
from
  pg_stat_statements as statements
  inner join pg_authid as auth on statements.userid = auth.oid
order by statements.calls desc
limit 100;
```

This query shows:

*   query statistics, ordered by the number of times each query has been executed
*   the role that ran the query
*   the number of times it has been called
*   the average number of rows returned
*   the cumulative total time the query has spent running
*   the min, max and mean query times.

This provides useful information about the queries you run most frequently. Queries that have high `max_time` or `mean_time` times and are being called often can be good candidates for optimization.


### Slowest queries by execution time

```sql
select
  auth.rolname,
  statements.query,
  statements.calls,
  -- -- Postgres 13, 14, 15
  statements.total_exec_time + statements.total_plan_time as total_time,
  statements.min_exec_time + statements.min_plan_time as min_time,
  statements.max_exec_time + statements.max_plan_time as max_time,
  statements.mean_exec_time + statements.mean_plan_time as mean_time,
  -- -- Postgres <= 12
  -- total_time,
  -- min_time,
  -- max_time,
  -- mean_time,
  statements.rows / statements.calls as avg_rows
from
  pg_stat_statements as statements
  inner join pg_authid as auth on statements.userid = auth.oid
order by max_time desc
limit 100;
```

This query will show you statistics about queries ordered by the maximum execution time. It is similar to the query above ordered by calls, but this one highlights outliers that may have high executions times. Queries which have high or mean execution times are good candidates for optimization.


### Most time consuming queries

```sql
select
  auth.rolname,
  statements.query,
  statements.calls,
  statements.total_exec_time + statements.total_plan_time as total_time,
  to_char(
    (
      (statements.total_exec_time + statements.total_plan_time) / sum(
        statements.total_exec_time + statements.total_plan_time
      ) over ()
    ) * 100,
    'FM90D0'
  ) || '%' as prop_total_time
from
  pg_stat_statements as statements
  inner join pg_authid as auth on statements.userid = auth.oid
order by total_time desc
limit 100;
```

This query will show you statistics about queries ordered by the cumulative total execution time. It shows the total time the query has spent running as well as the proportion of total execution time the query has taken up.

Queries which are the most time consuming are not necessarily bad, you may have a very efficient and frequently ran queries that end up taking a large total % time, but it can be useful to help spot queries that are taking up more time than they should.


### Hit rate

Generally for most applications a small percentage of data is accessed more regularly than the rest. To make sure that your regularly accessed data is available, Postgres tracks your data access patterns and keeps this in its [shared\_buffers](https://www.postgresql.org/docs/15/runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-MEMORY) cache.

Applications with lower cache hit rates generally perform more poorly since they have to hit the disk to get results rather than serving them from memory. Very poor hit rates can also cause you to burst past your [Disk IO limits](./compute-add-ons#disk-io) causing significant performance issues.

You can view your cache and index hit rate by executing the following query:

```sql
select
  'index hit rate' as name,
  (sum(idx_blks_hit)) / nullif(sum(idx_blks_hit + idx_blks_read), 0) * 100 as ratio
from pg_statio_user_indexes
union all
select
  'table hit rate' as name,
  sum(heap_blks_hit) / nullif(sum(heap_blks_hit) + sum(heap_blks_read), 0) * 100 as ratio
from pg_statio_user_tables;
```

This shows the ratio of data blocks fetched from the Postgres [shared\_buffers](https://www.postgresql.org/docs/15/runtime-config-resource.html#RUNTIME-CONFIG-RESOURCE-MEMORY) cache against the data blocks that were read from disk/OS cache.

If either of your index or table hit rate are < 99% then this can indicate your compute plan is too small for your current workload and you would benefit from more memory. [Upgrading your compute](./compute-add-ons) is easy and can be done from your [project dashboard](https://supabase.com/dashboard/project/_/settings/compute-and-disk).


### Optimizing poor performing queries

Postgres has built in tooling to help you optimize poorly performing queries. You can use the [query plan analyzer](https://www.postgresql.org/docs/current/sql-explain.html) on any expensive queries that you have identified:

```sql
explain analyze <query-statement-here>;
```

When you include `analyze` in the explain statement, the database attempts to execute the query and provides a detailed query plan along with actual execution times. So, be careful using `explain analyze` with `insert`/`update`/`delete` queries, because the query will actually run, and could have unintended side-effects.

If you run just `explain` without the `analyze` keyword, the database will only perform query planning without actually executing the query. This approach can be beneficial when you want to inspect the query plan without affecting the database or if you encounter timeouts in your queries.

Using the query plan analyzer to optimize your queries is a large topic, with a number of online resources available:

*   [Official docs.](https://www.postgresql.org/docs/current/using-explain.html)
*   [The Art of PostgreSQL.](https://theartofpostgresql.com/explain-plan-visualizer/)
*   [Postgres Wiki.](https://wiki.postgresql.org/wiki/Using_EXPLAIN)
*   [Enterprise DB.](https://www.enterprisedb.com/blog/postgresql-query-optimization-performance-tuning-with-explain-analyze)

You can pair the information available from `pg_stat_statements` with the detailed system metrics available [via your metrics endpoint](../platform/metrics) to better understand the behavior of your DB and the queries you're executing against it.


# Querying Joins and Nested tables



The data APIs automatically detect relationships between Postgres tables. Since Postgres is a relational database, this is a very common scenario.


## One-to-many joins

Let's use an example database that stores `orchestral_sections` and `instruments`:

The APIs will automatically detect relationships based on the foreign keys:


## Many-to-many joins

The data APIs will detect many-to-many joins. For example, if you have a database which stored teams of users (where each user could belong to many teams):

```sql
create table users (
  "id" serial primary key,
  "name" text
);

create table teams (
  "id" serial primary key,
  "team_name" text
);

create table members (
  "user_id" int references users,
  "team_id" int references teams,
  primary key (user_id, team_id)
);
```

In these cases you don't need to explicitly define the joining table (members). If we wanted to fetch all the teams and the members in each team:


## Specifying the `ON` clause for joins with multiple foreign keys

For example, if you have a project that tracks when employees check in and out of work shifts:

```sql
-- Employees
create table users (
  "id" serial primary key,
  "name" text
);

-- Badge scans
create table scans (
  "id" serial primary key,
  "user_id" int references users,
  "badge_scan_time" timestamp
);

-- Work shifts
create table shifts (
  "id" serial primary key,
  "user_id" int references users,
  "scan_id_start" int references scans, -- clocking in
  "scan_id_end" int references scans, -- clocking out
  "attendance_status" text
);
```

In this case, you need to explicitly define the join because the joining column on `shifts` is ambiguous as they are both referencing the `scans` table.

To fetch all the `shifts` with `scan_id_start` and `scan_id_end` related to a specific `scan`, use the following syntax:


# Managing JSON and unstructured data

Using the JSON data type in Postgres.

Postgres supports storing and querying unstructured data.


## JSON vs JSONB

Postgres supports two types of JSON columns: `json` (stored as a string) and `jsonb` (stored as a binary). The recommended type is `jsonb` for almost all cases.

*   `json` stores an exact copy of the input text. Database functions must reparse the content on each execution.
*   `jsonb` stores database in a decomposed binary format. While this makes it slightly slower to input due to added conversion overhead, it is significantly faster to process, since no reparsing is needed.


## When to use JSON/JSONB

Generally you should use a `jsonb` column when you have data that is unstructured or has a variable schema. For example, if you wanted to store responses for various webhooks, you might not know the format of the response when creating the table. Instead, you could store the `payload` as a `jsonb` object in a single column.

Don't go overboard with `json/jsonb` columns. They are a useful tool, but most of the benefits of a relational database come from the ability to query and join structured data, and the referential integrity that brings.


## Create JSONB columns

`json/jsonb` is just another "data type" for Postgres columns. You can create a `jsonb` column in the same way you would create a `text` or `int` column:


## Inserting JSON data

You can insert JSON data in the same way that you insert any other data. The data must be valid JSON.


## Query JSON data

Querying JSON data is similar to querying other data, with a few other features to access nested values.

Postgres support a range of [JSON functions and operators](https://www.postgresql.org/docs/current/functions-json.html). For example, the `->` operator returns values as `jsonb` data. If you want the data returned as `text`, use the `->>` operator.


## Validating JSON data

Supabase provides the [`pg_jsonschema` extension](/docs/guides/database/extensions/pg_jsonschema) that adds the ability to validate `json` and `jsonb` data types against [JSON Schema](https://json-schema.org/) documents.

Once you have enabled the extension, you can add a "check constraint" to your table to validate the JSON data:

```sql
create table customers (
  id serial primary key,
  metadata json
);

alter table customers
add constraint check_metadata check (
  json_matches_schema(
    '{
        "type": "object",
        "properties": {
            "tags": {
                "type": "array",
                "items": {
                    "type": "string",
                    "maxLength": 16
                }
            }
        }
    }',
    metadata
  )
);
```


## Resources

*   [Postgres: JSON Functions and Operators](https://www.postgresql.org/docs/current/functions-json.html)
*   [Postgres JSON types](https://www.postgresql.org/docs/current/datatype-json.html)


# Connecting to Metabase



[`Metabase`](https://www.metabase.com/) is an Open Source data visualization tool. You can use it to explore your data stored in Supabase.


# OrioleDB Overview



The [OrioleDB](https://www.orioledb.com/) Postgres extension provides a drop-in replacement storage engine for the default heap storage method. It is designed to improve Postgres' scalability and performance.

OrioleDB addresses PostgreSQL's scalability limitations by removing bottlenecks in the shared memory cache under high concurrency. It also optimizes write-ahead-log (WAL) insertion through row-level WAL logging. These changes lead to significant improvements in the industry standard TPC-C benchmark, which approximates a real-world transactional workload. The following benchmark was performed on a c7g.metal instance and shows OrioleDB's performance outperforming the default Postgres heap method with a 3.3x speedup.


## Concepts


### Index-organized tables

OrioleDB uses index-organized tables, where table data is stored in the index structure. This design eliminates the need for separate heap storage, reduces overhead and improves lookup performance for primary key queries.


### No buffer mapping

In-memory pages are connected to the storage pages using direct links. This allows OrioleDB to bypass PostgreSQL's shared buffer pool and eliminate the associated complexity and contention in buffer mapping.


### Undo log

Multi-Version Concurrency Control (MVCC) is implemented using an undo log. The undo log stores previous row versions and transaction information, which enables consistent reads while removing the need for table vacuuming completely.


### Copy-on-write checkpoints

OrioleDB implements copy-on-write checkpoints to persist data efficiently. This approach writes only modified data during a checkpoint, reducing the I/O overhead compared to traditional Postgres checkpointing and allowing row-level WAL logging.


## Usage


### Creating OrioleDB project

You can get started with OrioleDB by enabling the extension in your Supabase dashboard.
To get started with OrioleDB you need to [create a new Supabase project](https://supabase.com/dashboard/new/_) and choose `OrioleDB Public Alpha` Postgres version.


### Creating tables

To create a table using the OrioleDB storage engine just execute the standard `CREATE TABLE` statement. By default it will create a table using OrioleDB storage engine. For example:

```sql
-- Create a table
create table blog_post (
  id int8 not null,
  title text not null,
  body text not null,
  author text not null,
  published_at timestamptz not null default CURRENT_TIMESTAMP,
  views bigint not null,
  primary key (id)
);
```


### Creating indexes

OrioleDB tables always have a primary key. If it wasn't defined explicitly, a hidden primary key is created using the `ctid` column.
Additionally you can create secondary indexes.

```sql
-- Create an index
create index blog_post_published_at on blog_post (published_at);

create index blog_post_views on blog_post (views) where (views > 1000);
```


### Data manipulation

You can query and modify data in OrioleDB tables using standard SQL statements, including `SELECT`, `INSERT`, `UPDATE`, `DELETE` and `INSERT ... ON CONFLICT`.

```sql
INSERT INTO blog_post (id, title, body, author, views)
VALUES (1, 'Hello, World!', 'This is my first blog post.', 'John Doe', 1000);

SELECT * FROM blog_post ORDER BY published_at DESC LIMIT 10;
 id │     title     │            body             │  author  │         published_at          │ views
────┼───────────────┼─────────────────────────────┼──────────┼───────────────────────────────┼───────
  1 │ Hello, World! │ This is my first blog post. │ John Doe │ 2024-11-15 12:04:18.756824+01 │  1000
```


### Viewing query plans

You can see the execution plan using standard `EXPLAIN` statement.

```sql
EXPLAIN SELECT * FROM blog_post ORDER BY published_at DESC LIMIT 10;
                                                 QUERY PLAN
────────────────────────────────────────────────────────────────────────────────────────────────────────────
 Limit  (cost=0.15..1.67 rows=10 width=120)
   ->  Index Scan Backward using blog_post_published_at on blog_post  (cost=0.15..48.95 rows=320 width=120)

EXPLAIN SELECT * FROM blog_post WHERE id = 1;
                                    QUERY PLAN
──────────────────────────────────────────────────────────────────────────────────
 Index Scan using blog_post_pkey on blog_post  (cost=0.15..8.17 rows=1 width=120)
   Index Cond: (id = 1)

EXPLAIN (ANALYZE, BUFFERS) SELECT * FROM blog_post ORDER BY published_at DESC LIMIT 10;
                                                                      QUERY PLAN
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 Limit  (cost=0.15..1.67 rows=10 width=120) (actual time=0.052..0.054 rows=1 loops=1)
   ->  Index Scan Backward using blog_post_published_at on blog_post  (cost=0.15..48.95 rows=320 width=120) (actual time=0.050..0.052 rows=1 loops=1)
 Planning Time: 0.186 ms
 Execution Time: 0.088 ms
```


## Resources

*   [Official OrioleDB documentation](https://www.orioledb.com/docs)
*   [OrioleDB GitHub repository](https://github.com/orioledb/orioledb)


# Database



Every Supabase project comes with a full [Postgres](https://www.postgresql.org/) database, a free and open source database which is considered one of the world's most stable and advanced databases.


## Features


### Table view

You don't have to be a database expert to start using Supabase. Our table view makes Postgres as easy to use as a spreadsheet.

![Table View.](/docs/img/table-view.png)


### Relationships

Dig into the relationships within your data.


### Clone tables

You can duplicate your tables, just like you would inside a spreadsheet.


### The SQL editor

Supabase comes with a SQL Editor. You can also save your favorite queries to run later!


### Additional features

*   Supabase extends Postgres with realtime functionality using our [Realtime Server](https://github.com/supabase/realtime).
*   Every project is a full Postgres database, with `postgres` level access.
*   Supabase manages your database backups.
*   Import data directly from a CSV or excel spreadsheet.


### Extensions

To expand the functionality of your Postgres database, you can use extensions.
You can enable Postgres extensions with the click of a button within the Supabase dashboard.

[Learn more](/docs/guides/database/extensions) about all the extensions provided on Supabase.


## Terminology


### Postgres or PostgreSQL?

PostgreSQL the database was derived from the POSTGRES Project, a package written at the University of California at Berkeley in 1986. This package included a query language called "PostQUEL".

In 1994, Postgres95 was built on top of POSTGRES code, adding an SQL language interpreter as a replacement for PostQUEL.

Eventually, Postgres95 was renamed to PostgreSQL to reflect the SQL query capability.
After this, many people referred to it as Postgres since it's less prone to confusion. Supabase is all about simplicity, so we also refer to it as Postgres.


## Tips

Read about resetting your database password [here](/docs/guides/database/managing-passwords) and changing the timezone of your server [here](/docs/guides/database/managing-timezones).


## Next steps

*   Read more about [Postgres](https://www.postgresql.org/about/)
*   Sign in: [supabase.com/dashboard](https://supabase.com/dashboard)


# Partitioning tables



Table partitioning is a technique that allows you to divide a large table into smaller, more manageable parts called “partitions”.

Each partition contains a subset of the data based on a specified criteria, such as a range of values or a specific condition. Partitioning can significantly improve query performance and simplify data management for large datasets.


## Benefits of table partitioning

*   **Improved query performance:** allows queries to target specific partitions, reducing the amount of data scanned and improving query execution time.
*   **Scalability:** With partitioning, you can add or remove partitions as your data grows or changes, enabling better scalability and flexibility.
*   **Efficient data management:** simplifies tasks such as data loading, archiving, and deletion by operating on smaller partitions instead of the entire table.
*   **Enhanced maintenance operations:** can optimize vacuuming and indexing, leading to faster maintenance tasks.


## Partitioning methods

Postgres supports various partitioning methods based on how you want to partition your data. The commonly used methods are:

1.  **Range Partitioning**: Data is divided into partitions based on a specified range of values. For example, you can partition a sales table by date, where each partition represents a specific time range (e.g., one partition for each month).
2.  **List Partitioning**: Data is divided into partitions based on a specified list of values. For instance, you can partition a customer table by region, where each partition contains customers from a specific region (e.g., one partition for customers in the US, another for customers in Europe).
3.  **Hash Partitioning**: Data is distributed across partitions using a hash function. This method provides a way to evenly distribute data among partitions, which can be useful for load balancing. However, it doesn't allow direct querying based on specific values.


## Creating partitioned tables

Let's consider an example of range partitioning for a sales table based on the order date. We'll create monthly partitions to store data for each month:

```sql
create table sales (
    id bigint generated by default as identity,
    order_date date not null,
    customer_id bigint,
    amount bigint,

    -- We need to include all the
    -- partitioning columns in constraints:
    primary key (order_date, id)
)
partition by range (order_date);

create table sales_2000_01
	partition of sales
  for values from ('2000-01-01') to ('2000-02-01');

create table sales_2000_02
	partition of sales
	for values from ('2000-02-01') to ('2000-03-01');

```

To create a partitioned table you append `partition by range (<column_name>)` to the table creation statement. The column that you are partitioning with *must* be included in any unique index, which is the reason why we specify a composite primary key here (`primary key (order_date, id)`).


## Querying partitioned tables

To query a partitioned table, you have two options:

1.  Querying the parent table
2.  Querying specific partitions


### Querying the parent table

When you query the parent table, Postgres automatically routes the query to the relevant partitions based on the conditions specified in the query. This allows you to retrieve data from all partitions simultaneously.

Example:

```sql
select *
from sales
where order_date >= '2000-01-01' and order_date < '2000-03-01';
```

This query will retrieve data from both the `sales_2000_01` and `sales_2000_02` partitions.


### Querying specific partitions

If you only need to retrieve data from a specific partition, you can directly query that partition instead of the parent table. This approach is useful when you want to target a specific range or condition within a partition.

```sql
select *
from sales_2000_02;
```

This query will retrieve data only from the `sales_2000_02` partition.


## When to partition your tables

There is no real threshold to determine when you should use partitions. Partitions introduce complexity, and complexity should be avoided until it's needed. A few guidelines:

*   If you are considering performance, avoid partitions until you see performance degradation on non-partitioned tables.
*   If you are using partitions as a management tool, it's fine to create the partitions any time.
*   If you don't know how you should partition your data, then it's probably too early.


## Examples

Here are simple examples for each of the partitioning types in Postgres.


### Range partitioning

Let's consider a range partitioning example for a table that stores sales data based on the order date. We'll create monthly partitions to store data for each month.

In this example, the **`sales`** table is partitioned into two partitions: **`sales_january`** and **`sales_february`**. The data in these partitions is based on the specified range of order dates:

```sql
create table sales (
    id bigint generated by default as identity,
    order_date date not null,
    customer_id bigint,
    amount bigint,

    -- We need to include all the
    -- partitioning columns in constraints:
    primary key (order_date, id)
)
partition by range (order_date);

create table sales_2000_01
	partition of sales
  for values from ('2000-01-01') to ('2000-02-01');

create table sales_2000_02
	partition of sales
	for values from ('2000-02-01') to ('2000-03-01');
```


### List partitioning

Let's consider a list partitioning example for a table that stores customer data based on their region. We'll create partitions to store customers from different regions.

In this example, the **`customers`** table is partitioned into two partitions: `customers_americas` and `customers_asia`. The data in these partitions is based on the specified list of regions:

```sql
-- Create the partitioned table
create table customers (
    id bigint generated by default as identity,
    name text,
    country text,

    -- We need to include all the
    -- partitioning columns in constraints:
    primary key (country, id)
)
partition by list(country);

create table customers_americas
	partition of customers
	for values in ('US', 'CANADA');

create table customers_asia
	partition of customers
  for values in ('INDIA', 'CHINA', 'JAPAN');
```


### Hash partitioning

You can use hash partitioning to evenly distribute data.

In this example, the **`products`** table is partitioned into two partitions: `products_one` and `products_two`. The data is distributed across these partitions using a hash function:

```sql
create table products (
    id bigint generated by default as identity,
    name text,
    category text,
    price bigint
)
partition by hash (id);

create table products_one
	partition of products
  for values with (modulus 2, remainder 1);

create table products_two
	partition of products
  for values with (modulus 2, remainder 0);
```


## Other tools

There are several other tools available for Postgres partitioning, most notably [pg\_partman](https://github.com/pgpartman/pg_partman). Native partitioning was introduced in Postgres 10 and is generally thought to have better performance.


# Connecting with pgAdmin



[`pgAdmin`](https://www.pgadmin.org/) is a GUI tool for managing Postgres databases. You can use it to connect to your database via SSL.


# Postgres.js



### Connecting with Postgres.js

[Postgres.js](https://github.com/porsager/postgres) is a full-featured Postgres client for Node.js and Deno.


# Cascade Deletes



There are 5 options for foreign key constraint deletes:

1.  **CASCADE:** When a row is deleted from the parent table, all related rows in the child tables are deleted as well.
2.  **RESTRICT:** When a row is deleted from the parent table, the delete operation is aborted if there are any related rows in the child tables.
3.  **SET NULL:** When a row is deleted from the parent table, the values of the foreign key columns in the child tables are set to NULL.
4.  **SET DEFAULT:** When a row is deleted from the parent table, the values of the foreign key columns in the child tables are set to their default values.
5.  **NO ACTION:** This option is similar to RESTRICT, but it also has the option to be “deferred” to the end of a transaction. This means that other cascading deletes can run first, and then this delete constraint will only throw an error if there is referenced data remaining *at the end of the transaction*.

These options can be specified when defining a foreign key constraint using the "ON DELETE" clause. For example, the following SQL statement creates a foreign key constraint with the `CASCADE` option:

```sql
alter table child_table
add constraint fk_parent foreign key (parent_id) references parent_table (id)
  on delete cascade;
```

This means that when a row is deleted from the `parent_table`, all related rows in the `child_table` will be deleted as well.


## `RESTRICT` vs `NO ACTION`

The difference between `NO ACTION` and `RESTRICT` is subtle and can be a bit confusing.

Both `NO ACTION` and `RESTRICT` are used to prevent deletion of a row in a parent table if there are related rows in a child table. However, there is a subtle difference in how they behave.

When a foreign key constraint is defined with the option `RESTRICT`, it means that if a row in the parent table is deleted, the database will immediately raise an error and prevent the deletion of the row in the parent table. The database will not delete, update or set to NULL any rows in the referenced tables.

When a foreign key constraint is defined with the option `NO ACTION`, it means that if a row in the parent table is deleted, the database will also raise an error and prevent the deletion of the row in the parent table. However unlike `RESTRICT`, `NO ACTION` has the option defer the check using `INITIALLY DEFERRED`. This will only raise the above error *if* the referenced rows still exist at the end of the transaction.

The difference from `RESTRICT` is that a constraint marked as `NO ACTION INITIALLY DEFERRED` is deferred until the end of the transaction, rather than running immediately. If, for example there is another foreign key constraint between the same tables marked as `CASCADE`, the cascade will occur first and delete the referenced rows, and no error will be thrown by the deferred constraint. Otherwise if there are still rows referencing the parent row by the end of the transaction, an error will be raised just like before. Just like `RESTRICT`, the database will not delete, update or set to NULL any rows in the referenced tables.

In practice, you can use either `NO ACTION` or `RESTRICT` depending on your needs. `NO ACTION` is the default behavior if you do not specify anything. If you prefer to defer the check until the end of the transaction, use `NO ACTION INITIALLY DEFERRED`.


## Example

Let's further illustrate the difference with an example. We'll use the following data:

`grandparent`

| id  | name      |
| --- | --------- |
| 1   | Elizabeth |

`parent`

| id  | name    | `parent_id` |
| --- | ------- | ----------- |
| 1   | Charles | 1           |
| 2   | Diana   | 1           |

`child`

| id  | name    | father | mother |
| --- | ------- | ------ | ------ |
| 1   | William | 1      | 2      |

To create these tables and their data, we run:

```sql
create table grandparent (
  id serial primary key,
  name text
);

create table parent (
  id serial primary key,
  name text,
  parent_id integer references grandparent (id)
    on delete cascade
);

create table child (
  id serial primary key,
  name text,
  father integer references parent (id)
    on delete restrict
);

insert into grandparent
  (id, name)
values
  (1, 'Elizabeth');

insert into parent
  (id, name, parent_id)
values
  (1, 'Charles', 1);

insert into parent
  (id, name, parent_id)
values
  (2, 'Diana', 1);

-- We'll just link the father for now
insert into child
  (id, name, father)
values
  (1, 'William', 1);
```


### `RESTRICT`

`RESTRICT` will prevent a delete and raise an error:

```shell
postgres=# delete from grandparent;
ERROR: update or delete on table "parent" violates foreign key constraint "child_father_fkey" on table "child"
DETAIL: Key (id)=(1) is still referenced from table "child".
```

Even though the foreign key constraint between parent and grandparent is `CASCADE`, the constraint between child and father is `RESTRICT`. Therefore an error is raised and no records are deleted.


### `NO ACTION`

Let's change the child-father relationship to `NO ACTION`:

```sql
alter table child
drop constraint child_father_fkey;

alter table child
add constraint child_father_fkey foreign key (father) references parent (id)
  on delete no action;
```

We see that `NO ACTION` will also prevent a delete and raise an error:

```shell
postgres=# delete from grandparent;
ERROR: update or delete on table "parent" violates foreign key constraint "child_father_fkey" on table "child"
DETAIL: Key (id)=(1) is still referenced from table "child".
```


### `NO ACTION INITIALLY DEFERRED`

We'll change the foreign key constraint between child and father to be `NO ACTION INITIALLY DEFERRED`:

```sql
alter table child
drop constraint child_father_fkey;

alter table child
add constraint child_father_fkey foreign key (father) references parent (id)
  on delete no action initially deferred;
```

Here you will see that `INITIALLY DEFFERED` seems to operate like `NO ACTION` or `RESTRICT`. When we run a delete, it seems to make no difference:

```shell
postgres=# delete from grandparent;
ERROR: update or delete on table "parent" violates foreign key constraint "child_father_fkey" on table "child"
DETAIL: Key (id)=(1) is still referenced from table "child".
```

But, when we combine it with *other* constraints, then any other constraints take precedence. For example, let's run the same but add a `mother` column that has a `CASCADE` delete:

```sql
alter table child
add column mother integer references parent (id)
  on delete cascade;

update child
set mother = 2
where id = 1;
```

Then let's run a delete on the `grandparent` table:

```shell
postgres=# delete from grandparent;
DELETE 1

postgres=# select * from parent;
 id | name | parent_id
----+------+-----------
(0 rows)

postgres=# select * from child;
 id | name | father | mother
----+------+--------+--------
(0 rows)
```

The `mother` deletion took precedence over the `father`, and so William was deleted. After William was deleted, there was no reference to “Charles” and so he was free to be deleted, even though previously he wasn't (without `INITIALLY DEFERRED`).


# Column Level Security



PostgreSQL's [Row Level Security (RLS)](https://www.postgresql.org/docs/current/ddl-rowsecurity.html) gives you granular control over who can access rows of data. However, it doesn't give you control over which columns they can access within rows. Sometimes you want to restrict access to specific columns in your database. Column Level Privileges allows you to do just that.


## Policies at the row level

Policies in Row Level Security (RLS) are used to restrict access to rows in a table. Think of them like adding a `WHERE` clause to every query.

For example, let's assume you have a `posts` table with the following columns:

*   `id`
*   `user_id`
*   `title`
*   `content`
*   `created_at`
*   `updated_at`

You can restrict updates to just the user who created it using [RLS](/docs/guides/auth#row-level-security), with the following policy:

```sql
create policy "Allow update for owners" on posts for
update
  using ((select auth.uid()) = user_id);
```

However, this gives the post owner full access to update the row, including all of the columns.


## Privileges at the column level

To restrict access to columns, you can use [Privileges](https://www.postgresql.org/docs/current/ddl-priv.html).

There are two types of privileges in Postgres:

1.  **table-level**: Grants the privilege on all columns in the table.
2.  **column-level** Grants the privilege on a specific column in the table.

You can have both types of privileges on the same table. If you have both, and you revoke the column-level privilege, the table-level privilege will still be in effect.

By default, our table will have a table-level `UPDATE` privilege, which means that the `authenticated` role can update all the columns in the table.

```sql
revoke
update
  on table public.posts
from
  authenticated;

grant
update
  (title, content) on table public.posts to authenticated;
```

In the above example, we are revoking the table-level `UPDATE` privilege from the `authenticated` role and granting a column-level `UPDATE` privilege on just the `title` and `content` columns.

If we want to restrict access to updating the `title` column:

```sql
revoke
update
  (title) on table public.posts
from
  authenticated;
```

This time, we are revoking the column-level `UPDATE` privilege of the `title` column from the `authenticated` role. We didn't need to revoke the table-level `UPDATE` privilege because it's already revoked.


## Manage column privileges in the Dashboard

You can view and edit the privileges in the [Supabase Studio](https://supabase.com/dashboard/project/_/database/column-privileges).

![Column level privileges](/docs/img/guides/privileges/column-level-privileges-2.png)


## Manage column privileges in migrations

While you can manage privileges directly from the Dashboard, as your project grows you may want to manage them in your migrations. Read about database migrations in the [Local Development](https://supabase.com/docs/guides/deployment/database-migrations) guide.


## Considerations when using column-level privileges

*   If you turn off a column privilege you won't be able to use that column at all.
*   All operations (insert, update, delete) as well as using `select *` will fail.


# Database configuration

Updating the default configuration for your Postgres database.

Postgres provides a set of sensible defaults for you database size. In some cases, these defaults can be updated. We do not recommend changing these defaults unless you know what you're doing.


## Timeouts

See the [Timeouts](/docs/guides/database/postgres/timeouts) section.


## Statement optimization

All Supabase projects come with the [`pg_stat_statements`](https://www.postgresql.org/docs/current/pgstatstatements.html) extension installed, which tracks planning and execution statistics for all statements executed against it. These statistics can be used in order to diagnose the performance of your project.

This data can further be used in conjunction with the [`explain`](https://www.postgresql.org/docs/current/using-explain.html) functionality of Postgres to optimize your usage.


## Managing timezones

Every Supabase database is set to UTC timezone by default. We strongly recommend keeping it this way, even if your users are in a different location.
This is because it makes it much easier to calculate differences between timezones if you adopt the mental model that everything in your database is in UTC time.


### Change timezone


### Full list of timezones

Get a full list of timezones supported by your database. This will return the following columns:

*   `name`: Time zone name
*   `abbrev`: Time zone abbreviation
*   `utc_offset`: Offset from UTC (positive means east of Greenwich)
*   `is_dst`: True if currently observing daylight savings


### Search for a specific timezone

Use `ilike` (case insensitive search) to find specific timezones.


# Custom Claims & Role-based Access Control (RBAC)



Custom Claims are special attributes attached to a user that you can use to control access to portions of your application. For example:

```json
{
  "user_role": "admin",
  "plan": "TRIAL",
  "user_level": 100,
  "group_name": "Super Guild!",
  "joined_on": "2022-05-20T14:28:18.217Z",
  "group_manager": false,
  "items": ["toothpick", "string", "ring"]
}
```

To implement Role-Based Access Control (RBAC) with `custom claims`, use a [Custom Access Token Auth Hook](/docs/guides/auth/auth-hooks#hook-custom-access-token). This hook runs before a token is issued. You can use it to add additional claims to the user's JWT.

This guide uses the [Slack Clone example](https://github.com/supabase/supabase/tree/master/examples/slack-clone/nextjs-slack-clone) to demonstrate how to add a `user_role` claim and use it in your [Row Level Security (RLS) policies](/docs/guides/database/postgres/row-level-security).


## Create a table to track user roles and permissions

In this example, you will implement two user roles with specific permissions:

*   `moderator`: A moderator can delete all messages but not channels.
*   `admin`: An admin can delete all messages and channels.

```sql supabase/migrations/init.sql
-- Custom types
create type public.app_permission as enum ('channels.delete', 'messages.delete');
create type public.app_role as enum ('admin', 'moderator');

-- USER ROLES
create table public.user_roles (
  id        bigint generated by default as identity primary key,
  user_id   uuid references auth.users on delete cascade not null,
  role      app_role not null,
  unique (user_id, role)
);
comment on table public.user_roles is 'Application roles for each user.';

-- ROLE PERMISSIONS
create table public.role_permissions (
  id           bigint generated by default as identity primary key,
  role         app_role not null,
  permission   app_permission not null,
  unique (role, permission)
);
comment on table public.role_permissions is 'Application permissions for each role.';
```

You can now manage your roles and permissions in SQL. For example, to add the mentioned roles and permissions from above, run:

```sql supabase/seed.sql
insert into public.role_permissions (role, permission)
values
  ('admin', 'channels.delete'),
  ('admin', 'messages.delete'),
  ('moderator', 'messages.delete');
```


## Create Auth Hook to apply user role

The [Custom Access Token Auth Hook](/docs/guides/auth/auth-hooks#hook-custom-access-token) runs before a token is issued. You can use it to edit the JWT.


### Enable the hook

In the dashboard, navigate to [`Authentication > Hooks (Beta)`](/dashboard/project/_/auth/hooks) and select the appropriate Postgres function from the dropdown menu.

When developing locally, follow the [local development](/docs/guides/auth/auth-hooks#local-development) instructions.


## Accessing custom claims in RLS policies

To utilize Role-Based Access Control (RBAC) in Row Level Security (RLS) policies, create an `authorize` method that reads the user's role from their JWT and checks the role's permissions:

```sql supabase/migrations/init.sql
create or replace function public.authorize(
  requested_permission app_permission
)
returns boolean as $$
declare
  bind_permissions int;
  user_role public.app_role;
begin
  -- Fetch user role once and store it to reduce number of calls
  select (auth.jwt() ->> 'user_role')::public.app_role into user_role;

  select count(*)
  into bind_permissions
  from public.role_permissions
  where role_permissions.permission = requested_permission
    and role_permissions.role = user_role;

  return bind_permissions > 0;
end;
$$ language plpgsql stable security definer set search_path = '';
```

You can then use the `authorize` method within your RLS policies. For example, to enable the desired delete access, you would add the following policies:

```sql
create policy "Allow authorized delete access" on public.channels for delete to authenticated using ( (SELECT authorize('channels.delete')) );
create policy "Allow authorized delete access" on public.messages for delete to authenticated using ( (SELECT authorize('messages.delete')) );
```


## Accessing custom claims in your application

The auth hook will only modify the access token JWT but not the auth response. Therefore, to access the custom claims in your application, e.g. your browser client, or server-side middleware, you will need to decode the `access_token` JWT on the auth session.

In a JavaScript client application you can for example use the [`jwt-decode` package](https://www.npmjs.com/package/jwt-decode):

```js
import { jwtDecode } from 'jwt-decode'

const { subscription: authListener } = supabase.auth.onAuthStateChange(async (event, session) => {
  if (session) {
    const jwt = jwtDecode(session.access_token)
    const userRole = jwt.user_role
  }
})
```

For server-side logic you can use packages like [`express-jwt`](https://github.com/auth0/express-jwt), [`koa-jwt`](https://github.com/stiang/koa-jwt), [`PyJWT`](https://github.com/jpadilla/pyjwt), [dart\_jsonwebtoken](https://pub.dev/packages/dart_jsonwebtoken), [Microsoft.AspNetCore.Authentication.JwtBearer](https://www.nuget.org/packages/Microsoft.AspNetCore.Authentication.JwtBearer), etc.


## Conclusion

You now have a robust system in place to manage user roles and permissions within your database that automatically propagates to Supabase Auth.


## More resources

*   [Auth Hooks](/docs/guides/auth/auth-hooks)
*   [Row Level Security](/docs/guides/database/postgres/row-level-security)
*   [RLS Functions](/docs/guides/database/postgres/row-level-security#using-functions)
*   [Next.js Slack Clone Example](https://github.com/supabase/supabase/tree/master/examples/slack-clone/nextjs-slack-clone)


# Drop all tables in a PostgreSQL schema



Execute the following query to drop all tables in a given schema.
Replace `my-schema-name` with the name of your schema. In Supabase, the default schema is `public`.

```sql
do $$ declare
    r record;
begin
    for r in (select tablename from pg_tables where schemaname = 'my-schema-name') loop
        execute 'drop table if exists ' || quote_ident(r.tablename) || ' cascade';
    end loop;
end $$;
```

This query works by listing out all the tables in the given schema and then executing a `drop table` for each (hence the `for... loop`).

You can run this query using the [SQL Editor](https://supabase.com/dashboard/project/_/sql) in the Supabase Dashboard, or via `psql` if you're [connecting directly to the database](/docs/guides/database/connecting-to-postgres#direct-connections).


# Managing Enums in Postgres



Enums in Postgres are a custom data type. They allow you to define a set of values (or labels) that a column can hold. They are useful when you have a fixed set of possible values for a column.


## Creating enums

You can define a Postgres Enum using the `create type` statement. Here's an example:

```sql
create type mood as enum (
  'happy',
  'sad',
  'excited',
  'calm'
);
```

In this example, we've created an Enum called "mood" with four possible values.


## When to use enums

There is a lot of overlap between Enums and foreign keys. Both can be used to define a set of values for a column. However, there are some advantages to using Enums:

*   Performance: You can query a single table instead of finding the value from a lookup table.
*   Simplicity: Generally the SQL is easier to read and write.

There are also some disadvantages to using Enums:

*   Limited Flexibility: Adding and removing values requires modifying the database schema (i.e.: using migrations) rather than adding data to a table.
*   Maintenance Overhead: Enum types require ongoing maintenance. If your application's requirements change frequently, maintaining enums can become burdensome.

In general you should only use Enums when the list of values is small, fixed, and unlikely to change often. Things like "a list of continents" or "a list of departments" are good candidates for Enums.


## Using enums in tables

To use the Enum in a table, you can define a column with the Enum type. For example:

```sql
create table person (
  id serial primary key,
  name text,
  current_mood mood
);
```

Here, the `current_mood` column can only have values from the "mood" Enum.


### Inserting data with enums

You can insert data into a table with Enum columns by specifying one of the Enum values:

```sql
insert into person
  (name, current_mood)
values
  ('Alice', 'happy');
```


### Querying data with enums

When querying data, you can filter and compare Enum values as usual:

```sql
select * 
from person 
where current_mood = 'sad';
```


## Managing enums

You can manage your Enums using the `alter type` statement. Here are some examples:


### Updating enum values

You can update the value of an Enum column:

```sql
update person
set current_mood = 'excited'
where name = 'Alice';
```


### Adding enum values

To add new values to an existing Postgres Enum, you can use the `ALTER TYPE` statement. Here's how you can do it:

Let's say you have an existing Enum called `mood`, and you want to add a new value, `content`:

```sql
alter type mood add value 'content';
```


### Removing enum values

Even though it is possible, it is unsafe to remove enum values once they have been created. It's better to leave the enum value in place.


### Getting a list of enum values

Check your existing Enum values by querying the enum\_range function:

```sql
select enum_range(null::mood);
```


## Resources

*   Official Postgres Docs: [Enumerated Types](https://www.postgresql.org/docs/current/datatype-enum.html)


# Select first row for each group in PostgreSQL



Given a table `seasons`:

| id  |   team    | points |
| --- | :-------: | -----: |
| 1   | Liverpool |     82 |
| 2   | Liverpool |     84 |
| 3   | Brighton  |     34 |
| 4   | Brighton  |     28 |
| 5   | Liverpool |     79 |

We want to find the rows containing the maximum number of points *per team*.

The expected output we want is:

| id  |   team    | points |
| --- | :-------: | -----: |
| 3   | Brighton  |     34 |
| 2   | Liverpool |     84 |

From the [SQL Editor](https://supabase.com/dashboard/project/_/sql), you can run a query like:

```sql
select distinct
  on (team) id,
  team,
  points
from
  seasons
order BY
  id,
  points desc,
  team;
```

The important bits here are:

*   The `desc` keyword to order the `points` from highest to lowest.
*   The `distinct` keyword that tells Postgres to only return a single row per team.

This query can also be executed via `psql` or any other query editor if you prefer to [connect directly to the database](/docs/guides/database/connecting-to-postgres#direct-connections).


# Managing Indexes in PostgreSQL



An index makes your Postgres queries faster. The index is like a "table of contents" for your data - a reference list which allows queries to quickly locate a row in a given table without needing to scan the entire table (which in large tables can take a long time).

Indexes can be structured in a few different ways. The type of index chosen depends on the values you are indexing. By far the most common index type, and the default in Postgres, is the B-Tree. A B-Tree is the generalized form of a binary search tree, where nodes can have more than two children.

Even though indexes improve query performance, the Postgres query planner may not always make use of a given index when choosing which optimizations to make. Additionally indexes come with some overhead - additional writes and increased storage - so it's useful to understand how and when to use indexes, if at all.


## Create an index

Let's take an example table:

```sql
create table persons (
  id bigint generated by default as identity primary key,
  age int,
  height int,
  weight int,
  name text,
  deceased boolean
);
```

We might want to frequently query users based on their age:

```sql
select name from persons where age = 32;
```

Without an index, Postgres will scan every row in the table to find equality matches on age.

You can verify this by doing an explain on the query:

```sql
explain select name from persons where age = 32;
```

Outputs:

    Seq Scan on persons  (cost=0.00..22.75 rows=x width=y)
    Filter: (age = 32)

To add a simple B-Tree index you can run:

```sql
create index idx_persons_age on persons (age);
```

Here is a simplified diagram of the index we just created (note that in practice, nodes actually have more than two children).

You can see that in any large data set, traversing the index to locate a given value can be done in much less operations (O(log n)) than compared to scanning the table one value at a time from top to bottom (O(n)).


## Partial indexes

If you are frequently querying a subset of rows then it may be more efficient to build a partial index. In our example, perhaps we only want to match on `age` where `deceased is false`. We could build a partial index:

```sql
create index idx_living_persons_age on persons (age)
where deceased is false;
```


## Ordering indexes

By default B-Tree indexes are sorted in ascending order, but sometimes you may want to provide a different ordering. Perhaps our application has a page featuring the top 10 oldest people. Here we would want to sort in descending order, and include `NULL` values last. For this we can use:

```sql
create index idx_persons_age_desc on persons (age desc nulls last);
```


## Reindexing

After a while indexes can become stale and may need rebuilding. Postgres provides a `reindex` command for this, but due to Postgres locks being placed on the index during this process, you may want to make use of the `concurrent` keyword.

```sql
reindex index concurrently idx_persons_age;
```

Alternatively you can reindex all indexes on a particular table:

```sql
reindex table concurrently persons;
```

Take note that `reindex` can be used inside a transaction, but `reindex [index/table] concurrently` cannot.


## Index Advisor

Indexes can improve query performance of your tables as they grow. The Supabase Dashboard offers an Index Advisor, which suggests potential indexes to add to your tables.

For more information on the Index Advisor and its suggestions, see the [`index_advisor` extension](/docs/guides/database/extensions/index_advisor).

To use the Dashboard Index Advisor:

1.  Go to the [Query Performance](/dashboard/project/_/advisors/query-performance) page.
2.  Click on a query to bring up the Details side panel.
3.  Select the Indexes tab.
4.  Enable Index Advisor if prompted.


### Understanding Index Advisor results

The Indexes tab shows the existing indexes used in the selected query. Note that indexes suggested in the "New Index Recommendations" section may not be used when you create them. Postgres' query planner may intentionally ignore an available index if it determines that the query will be faster without. For example, on a small table, a sequential scan might be faster than an index scan. In that case, the planner will switch to using the index as the table size grows, helping to future proof the query.

If additional indexes might improve your query, the Index Advisor shows the suggested indexes with the estimated improvement in startup and total costs:

*   Startup cost is the cost to fetch the first row
*   Total cost is the cost to fetch all the rows

Costs are in arbitrary units, where a single sequential page read costs 1.0 units.


# Roles, superuser access and unsupported operations



Supabase provides the default `postgres` role to all instances deployed. Superuser access is not given as it allows destructive operations to be performed on the database.

To ensure you are not impacted by this, additional privileges are granted to the `postgres` user to allow it to run some operations that are normally restricted to superusers.

However, this does mean that some operations, that typically require `superuser` privileges, are not available on Supabase. These are documented below:


## Unsupported operations

*   `CREATE SUBSCRIPTION`
*   `CREATE EVENT TRIGGER`
*   `COPY ... FROM PROGRAM`
*   `ALTER USER ... WITH SUPERUSER`


# Postgres Roles

Managing access to your Postgres database and configuring permissions.

Postgres manages database access permissions using the concept of roles. Generally you wouldn't use these roles for your own application - they are mostly for configuring *system access* to your database. If you want to configure *application access*, then you should use [Row Level Security](/docs/guides/database/postgres/row-level-security) (RLS). You can also implement [Role-based Access Control](/docs/guides/database/postgres/custom-claims-and-role-based-access-control-rbac) on top of RLS.


## Users vs roles

In Postgres, roles can function as users or groups of users. Users are roles with login privileges, while groups (also known as role groups) are roles that don't have login privileges but can be used to manage permissions for multiple users.


## Creating roles

You can create a role using the `create role` command:

```sql
create role "role_name";
```


## Creating users

Roles and users are essentially the same in Postgres, however if you want to use password-logins for a specific role, then you can use `WITH LOGIN PASSWORD`:

```sql
create role "role_name" with login password 'extremely_secure_password';
```


## Passwords

Your Postgres database is the core of your Supabase project, so it's important that every role has a strong, secure password at all times. Here are some tips for creating a secure password:

*   Use a password manager to generate it.
*   Make a long password (12 characters at least).
*   Don't use any common dictionary words.
*   Use both upper and lower case characters, numbers, and special symbols.


### Special symbols in passwords

If you use special symbols in your Postgres password, you must remember to [percent-encode](https://en.wikipedia.org/wiki/Percent-encoding) your password later if using the Postgres connection string, for example, `postgresql://postgres.projectref:p%3Dword@aws-0-us-east-1.pooler.supabase.com:6543/postgres`


### Changing your project password

When you created your project you were also asked to enter a password. This is actually the password for the `postgres` role in your database. You can update this from the Dashboard under the [database settings](https://supabase.com/dashboard/project/_/settings/database) page. You should *never* give this to third-party service unless you absolutely trust them. Instead, we recommend that you create a new user for every service that you want to give access too. This will also help you with debugging - you can see every query that each role is executing in your database within `pg_stat_statements`.

Changing the password does not result in any downtime. All connected services, such as PostgREST, PgBouncer, and other Supabase managed services, are automatically updated to use the latest password to ensure availability. However, if you have any external services connecting to the Supabase database using hardcoded username/password credentials, a manual update will be required.


## Granting permissions

Roles can be granted various permissions on database objects using the `GRANT` command. Permissions include `SELECT`, `INSERT`, `UPDATE`, and `DELETE`. You can configure access to almost any object inside your database - including tables, views, functions, and triggers.


## Revoking permissions

Permissions can be revoked using the `REVOKE` command:

```sql
REVOKE permission_type ON object_name FROM role_name;
```


## Role hierarchy

Roles can be organized in a hierarchy, where one role can inherit permissions from another. This simplifies permission management, as you can define permissions at a higher level and have them automatically apply to all child roles.


### Role inheritance

To create a role hierarchy, you first need to create the parent and child roles. The child role will inherit permissions from its parent. Child roles can be added using the INHERIT option when creating the role:

```sql
create role "child_role_name" inherit "parent_role_name";
```


### Preventing inheritance

In some cases, you might want to prevent a role from having a child relationship (typically superuser roles). You can prevent inheritance relations using `NOINHERIT`:

```sql
alter role "child_role_name" noinherit;
```


## Supabase roles

Postgres comes with a set of [predefined roles](https://www.postgresql.org/docs/current/predefined-roles.html). Supabase extends this with a default set of roles which are configured on your database when you start a new project:


### `postgres`

The default Postgres role. This has admin privileges.


### `anon`

For unauthenticated, public access. This is the role which the API (PostgREST) will use when a user *is not* logged in.


### `authenticator`

A special role for the API (PostgREST). It has very limited access, and is used to validate a JWT and then
"change into" another role determined by the JWT verification.


### `authenticated`

For "authenticated access." This is the role which the API (PostgREST) will use when a user *is* logged in.


### `service_role`

For elevated access. This role is used by the API (PostgREST) to bypass Row Level Security.


### `supabase_auth_admin`

Used by the Auth middleware to connect to the database and run migration. Access is scoped to the `auth` schema.


### `supabase_storage_admin`

Used by the Auth middleware to connect to the database and run migration. Access is scoped to the `storage` schema.


### `dashboard_user`

For running commands via the Supabase UI.


### `supabase_admin`

An internal role Supabase uses for administrative tasks, such as running upgrades and automations.


## Resources

*   Official Postgres docs: [Database Roles](https://www.postgresql.org/docs/current/database-roles.html)
*   Official Postgres docs: [Role Membership](https://www.postgresql.org/docs/current/role-membership.html)
*   Official Postgres docs: [Function Permissions](https://www.postgresql.org/docs/current/perm-functions.html)


# Row Level Security

Secure your data using Postgres Row Level Security.

When you need granular authorization rules, nothing beats Postgres's [Row Level Security (RLS)](https://www.postgresql.org/docs/current/ddl-rowsecurity.html).


## Row Level Security in Supabase

RLS is incredibly powerful and flexible, allowing you to write complex SQL rules that fit your unique business needs. RLS can be combined with [Supabase Auth](/docs/guides/auth) for end-to-end user security from the browser to the database.

RLS is a Postgres primitive and can provide "[defense in depth](https://en.wikipedia.org/wiki/Defense_in_depth_\(computing\))" to protect your data from malicious actors even when accessed through third-party tooling.


## Policies

[Policies](https://www.postgresql.org/docs/current/sql-createpolicy.html) are Postgres's rule engine. Policies are easy to understand once you get the hang of them. Each policy is attached to a table, and the policy is executed every time a table is accessed.

You can just think of them as adding a `WHERE` clause to every query. For example a policy like this ...

```sql
create policy "Individuals can view their own todos."
on todos for select
using ( (select auth.uid()) = user_id );
```

.. would translate to this whenever a user tries to select from the todos table:

```sql
select *
from todos
where auth.uid() = todos.user_id;
-- Policy is implicitly added.
```


## Enabling Row Level Security

You can enable RLS for any table using the `enable row level security` clause:

```sql
alter table "table_name" enable row level security;
```

Once you have enabled RLS, no data will be accessible via the [API](/docs/guides/api) when using the public `anon` key, until you create policies.


## Authenticated and unauthenticated roles

Supabase maps every request to one of the roles:

*   `anon`: an unauthenticated request (the user is not logged in)
*   `authenticated`: an authenticated request (the user is logged in)

These are actually [Postgres Roles](/docs/guides/database/postgres/roles). You can use these roles within your Policies using the `TO` clause:

```sql
create policy "Profiles are viewable by everyone"
on profiles for select
to authenticated, anon
using ( true );

-- OR

create policy "Public profiles are viewable only by authenticated users"
on profiles for select
to authenticated
using ( true );
```


## Creating policies

Policies are SQL logic that you attach to a Postgres table. You can attach as many policies as you want to each table.

Supabase provides some [helpers](#helper-functions) that simplify RLS if you're using Supabase Auth. We'll use these helpers to illustrate some basic policies:


### SELECT policies

You can specify select policies with the `using` clause.

Let's say you have a table called `profiles` in the public schema and you want to enable read access to everyone.

```sql
-- 1. Create table
create table profiles (
  id uuid primary key,
  user_id references auth.users,
  avatar_url text
);

-- 2. Enable RLS
alter table profiles enable row level security;

-- 3. Create Policy
create policy "Public profiles are visible to everyone."
on profiles for select
to anon         -- the Postgres Role (recommended)
using ( true ); -- the actual Policy
```

Alternatively, if you only wanted users to be able to see their own profiles:

```sql
create policy "User can see their own profile only."
on profiles
for select using ( (select auth.uid()) = user_id );
```


### INSERT policies

You can specify insert policies with the `with check` clause. The `with check` expression ensures that any new row data adheres to the policy constraints.

Let's say you have a table called `profiles` in the public schema and you only want users to be able to create a profile for themselves. In that case, we want to check their User ID matches the value that they are trying to insert:

```sql
-- 1. Create table
create table profiles (
  id uuid primary key,
  user_id uuid references auth.users,
  avatar_url text
);

-- 2. Enable RLS
alter table profiles enable row level security;

-- 3. Create Policy
create policy "Users can create a profile."
on profiles for insert
to authenticated                          -- the Postgres Role (recommended)
with check ( (select auth.uid()) = user_id );      -- the actual Policy
```


### UPDATE policies

You can specify update policies by combining both the `using` and `with check` expressions.

The `using` clause represents the condition that must be true for the update to be allowed, and `with check` clause ensures that the updates made adhere to the policy constraints.

Let's say you have a table called `profiles` in the public schema and you only want users to be able to update their own profile.

You can create a policy where the `using` clause checks if the user owns the profile being updated. And the `with check` clause ensures that, in the resultant row, users do not change the `user_id` to a value that is not equal to their User ID, maintaining that the modified profile still meets the ownership condition.

```sql
-- 1. Create table
create table profiles (
  id uuid primary key,
  user_id uuid references auth.users,
  avatar_url text
);

-- 2. Enable RLS
alter table profiles enable row level security;

-- 3. Create Policy
create policy "Users can update their own profile."
on profiles for update
to authenticated                    -- the Postgres Role (recommended)
using ( (select auth.uid()) = user_id )       -- checks if the existing row complies with the policy expression
with check ( (select auth.uid()) = user_id ); -- checks if the new row complies with the policy expression
```

If no `with check` expression is defined, then the `using` expression will be used both to determine which rows are visible (normal USING case) and which new rows will be allowed to be added (WITH CHECK case).


### DELETE policies

You can specify delete policies with the `using` clause.

Let's say you have a table called `profiles` in the public schema and you only want users to be able to delete their own profile:

```sql
-- 1. Create table
create table profiles (
  id uuid primary key,
  user_id uuid references auth.users,
  avatar_url text
);

-- 2. Enable RLS
alter table profiles enable row level security;

-- 3. Create Policy
create policy "Users can delete a profile."
on profiles for delete
to authenticated                     -- the Postgres Role (recommended)
using ( (select auth.uid()) = user_id );      -- the actual Policy
```


### Views

Views bypass RLS by default because they are usually created with the `postgres` user. This is a feature of Postgres, which automatically creates views with `security definer`.

In Postgres 15 and above, you can make a view obey the RLS policies of the underlying tables when invoked by `anon` and `authenticated` roles by setting `security_invoker = true`.

```sql
create view <VIEW_NAME>
with(security_invoker = true)
as select <QUERY>
```

In older versions of Postgres, protect your views by revoking access from the `anon` and `authenticated` roles, or by putting them in an unexposed schema.


## Helper functions

Supabase provides some helper functions that make it easier to write Policies.


### `auth.uid()`

Returns the ID of the user making the request.


### `auth.jwt()`

Returns the JWT of the user making the request. Anything that you store in the user's `raw_app_meta_data` column or the `raw_user_meta_data` column will be accessible using this function. It's important to know the distinction between these two:

*   `raw_user_meta_data` - can be updated by the authenticated user using the `supabase.auth.update()` function. It is not a good place to store authorization data.
*   `raw_app_meta_data` - cannot be updated by the user, so it's a good place to store authorization data.

The `auth.jwt()` function is extremely versatile. For example, if you store some team data inside `app_metadata`, you can use it to determine whether a particular user belongs to a team. For example, if this was an array of IDs:

```sql
create policy "User is in team"
on my_table
to authenticated
using ( team_id in (select auth.jwt() -> 'app_metadata' -> 'teams'));
```


### MFA

The `auth.jwt()` function can be used to check for [Multi-Factor Authentication](/docs/guides/auth/auth-mfa#enforce-rules-for-mfa-logins). For example, you could restrict a user from updating their profile unless they have at least 2 levels of authentication (Assurance Level 2):

```sql
create policy "Restrict updates."
on profiles
as restrictive
for update
to authenticated using (
  (select auth.jwt()->>'aal') = 'aal2'
);
```


## Bypassing Row Level Security

Supabase provides special "Service" keys, which can be used to bypass RLS. These should never be used in the browser or exposed to customers, but they are useful for administrative tasks.

You can also create new [Postgres Roles](/docs/guides/database/postgres/roles) which can bypass Row Level Security using the "bypass RLS" privilege:

```sql
alter role "role_name" with bypassrls;
```

This can be useful for system-level access. You should *never* share login credentials for any Postgres Role with this privilege.


## RLS performance recommendations

Every authorization system has an impact on performance. While row level security is powerful, the performance impact is important to keep in mind. This is especially true for queries that scan every row in a table - like many `select` operations, including those using limit, offset, and ordering.

Based on a series of [tests](https://github.com/GaryAustin1/RLS-Performance), we have a few recommendations for RLS:


### Add indexes

Make sure you've added [indexes](/docs/guides/database/postgres/indexes) on any columns used within the Policies which are not already indexed (or primary keys). For a Policy like this:

```sql
create policy "rls_test_select" on test_table
to authenticated
using ( (select auth.uid()) = user_id );
```

You can add an index like:

```sql
create index userid
on test_table
using btree (user_id);
```


#### Benchmarks

| Test                                                                                          | Before (ms) | After (ms) | % Improvement | Change                                                                                                   |
| --------------------------------------------------------------------------------------------- | ----------- | ---------- | ------------- | -------------------------------------------------------------------------------------------------------- |
| [test1-indexed](https://github.com/GaryAustin1/RLS-Performance/tree/main/tests/test1-indexed) | 171         | < 0.1      | 99.94%        |  |


### Call functions with `select`

You can use `select` statement to improve policies that use functions. For example, instead of this:

```sql
create policy "rls_test_select" on test_table
to authenticated
using ( auth.uid() = user_id );
```

You can do:

```sql
create policy "rls_test_select" on test_table
to authenticated
using ( (select auth.uid()) = user_id );
```

This method works well for JWT functions like `auth.uid()` and `auth.jwt()` as well as `security definer` Functions. Wrapping the function causes an `initPlan` to be run by the Postgres optimizer, which allows it to "cache" the results per-statement, rather than calling the function on each row.


#### Benchmarks

| Test                                                                                                                              | Before (ms) | After (ms) | % Improvement | Change                                                                                                                                                                    |
| --------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [test2a-wrappedSQL-uid](https://github.com/GaryAustin1/RLS-Performance/tree/main/tests/test2a-wrappedSQL-uid\(\))                 | 179         | 9          | 94.97%        |                                     |
| [test2b-wrappedSQL-isadmin](https://github.com/GaryAustin1/RLS-Performance/tree/main/tests/test2b-wrappedSQL-isadmin\(\))         | 11,000      | 7          | 99.94%        |                                 |
| [test2c-wrappedSQL-two-functions](https://github.com/GaryAustin1/RLS-Performance/tree/main/tests/test2c-wrappedSQL-two-functions) | 11,000      | 10         | 99.91%        |  |
| [test2d-wrappedSQL-sd-fun](https://github.com/GaryAustin1/RLS-Performance/tree/main/tests/test2d-wrappedSQL-sd-fun)               | 178,000     | 12         | 99.993%       |                                              |
| [test2e-wrappedSQL-sd-fun-array](https://github.com/GaryAustin1/RLS-Performance/tree/main/tests/test2e-wrappedSQL-sd-fun-array)   | 173000      | 16         | 99.991%       |                         |


### Add filters to every query

Policies are "implicit where clauses," so it's common to run `select` statements without any filters. This is a bad pattern for performance. Instead of doing this (JS client example):

```js
const { data } = supabase
  .from('table')
  .select()
```

You should always add a filter:

```js
const { data } = supabase
  .from('table')
  .select()
  .eq('user_id', userId)
```

Even though this duplicates the contents of the Policy, Postgres can use the filter to construct a better query plan.


#### Benchmarks

| Test                                                                                              | Before (ms) | After (ms) | % Improvement | Change                                                                                                                                 |
| ------------------------------------------------------------------------------------------------- | ----------- | ---------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| [test3-addfilter](https://github.com/GaryAustin1/RLS-Performance/tree/main/tests/test3-addfilter) | 171         | 9          | 94.74%        |  |


### Use security definer functions

A "security definer" function runs using the same role that *created* the function. This means that if you create a role with a superuser (like `postgres`), then that function will have `bypassrls` privileges. For example, if you had a policy like this:

```sql
create policy "rls_test_select" on test_table
to authenticated
using (
  exists (
    select 1 from roles_table
    where (select auth.uid()) = user_id and role = 'good_role'
  )
);
```

We can instead create a `security definer` function which can scan `roles_table` without any RLS penalties:

```sql
create function private.has_good_role()
returns boolean
language plpgsql
security definer -- will run as the creator
as $$
begin
  return exists (
    select 1 from roles_table
    where (select auth.uid()) = user_id and role = 'good_role'
  );
end;
$$;

-- Update our policy to use this function:
create policy "rls_test_select"
on test_table
to authenticated
using ( private.has_good_role() );
```


### Minimize joins

You can often rewrite your Policies to avoid joins between the source and the target table. Instead, try to organize your policy to fetch all the relevant data from the target table into an array or set, then you can use an `IN` or `ANY` operation in your filter.

For example, this is an example of a slow policy which joins the source `test_table` to the target `team_user`:

```sql
create policy "rls_test_select" on test_table
to authenticated
using (
  (select auth.uid()) in (
    select user_id
    from team_user
    where team_user.team_id = team_id -- joins to the source "test_table.team_id"
  )
);
```

We can rewrite this to avoid this join, and instead select the filter criteria into a set:

```sql
create policy "rls_test_select" on test_table
to authenticated
using (
  team_id in (
    select team_id
    from team_user
    where user_id = (select auth.uid()) -- no join
  )
);
```

In this case you can also consider [using a `security definer` function](#use-security-definer-functions) to bypass RLS on the join table:


#### Benchmarks

| Test                                                                                                | Before (ms) | After (ms) | % Improvement | Change                                                                                                                                            |
| --------------------------------------------------------------------------------------------------- | ----------- | ---------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| [test5-fixed-join](https://github.com/GaryAustin1/RLS-Performance/tree/main/tests/test5-fixed-join) | 9,000       | 20         | 99.78%        |  |


### Specify roles in your policies

Always use the Role of inside your policies, specified by the `TO` operator. For example, instead of this query:

```sql
create policy "rls_test_select" on rls_test
using ( auth.uid() = user_id );
```

Use:

```sql
create policy "rls_test_select" on rls_test
to authenticated
using ( (select auth.uid()) = user_id );
```

This prevents the policy `( (select auth.uid()) = user_id )` from running for any `anon` users, since the execution stops at the `to authenticated` step.


#### Benchmarks

| Test                                                                                          | Before (ms) | After (ms) | % Improvement | Change                                                                                                                           |
| --------------------------------------------------------------------------------------------- | ----------- | ---------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| [test6-To-role](https://github.com/GaryAustin1/RLS-Performance/tree/main/tests/test6-To-role) | 170         | < 0.1      | 99.78%        |  |


## More resources

*   [Testing your database](/docs/guides/database/testing)
*   [Row Level Security and Supabase Auth](/docs/guides/database/postgres/row-level-security)
*   [RLS Guide and Best Practices](https://github.com/orgs/supabase/discussions/14576)
*   Community repo on testing RLS using [pgTAP and dbdev](https://github.com/usebasejump/supabase-test-helpers/tree/main)


# Replicate to another Postgres database using Logical Replication



For this example, you will need:

*   A Supabase project
*   A Postgres database (running v10 or newer)

You will be running commands on both of these databases to publish changes from the Supabase database to the external database.

1.  Create a `publication` on the **Supabase database**:

```sql
CREATE PUBLICATION example_pub;
```

2.  Also on the **Supabase database**, create a `replication slot`:

```sql
select pg_create_logical_replication_slot('example_slot', 'pgoutput');
```

3.  Now we will connect to our **external database** and subscribe to our `publication` Note: ):

```sql
CREATE SUBSCRIPTION example_sub
CONNECTION 'host=db.oaguxblfdassqxvvwtfe.supabase.co user=postgres password=YOUR_PASS dbname=postgres'
PUBLICATION example_pub
WITH (copy_data = true, create_slot=false, slot_name=example_slot);
```

4.  Add all the tables that you want replicated to the publication.

```sql
ALTER PUBLICATION example_pub ADD TABLE example_table;
```

5.  Check the replication status using `pg_stat_replication`

```sql
select * from pg_stat_replication;
```


# Timeouts

Extend database timeouts to execute longer transactions

## Change Postgres timeout

You can change the Postgres timeout at the:

1.  [Session level](#session-level)
2.  [Function level](#function-level)
3.  [Global level](#global-level)
4.  [Role level](#role-level)


### Session level

Session level settings persist only for the duration of the connection.

Set the session timeout by running:

```sql
set statement_timeout = '10min';
```

Because it applies to sessions only, it can only be used with connections through Supavisor in session mode (port 5432) or a direct connection. It cannot be used in the Dashboard, with the Supabase Client API, nor with Supavisor in Transaction mode (port 6543).

This is most often used for single, long running, administrative tasks, such as creating an HSNW index. Once the setting is implemented, you can view it by executing:

```sql
SHOW statement_timeout;
```

See the full guide on [changing session timeouts](https://github.com/orgs/supabase/discussions/21133).


### Function level

This works with the Database REST API when called from the Supabase client libraries:

```sql
create or replace function myfunc()
returns void as $$
 select pg_sleep(3); -- simulating some long-running process
$$
language sql
set statement_timeout TO '4s'; -- set custom timeout
```

This is mostly for recurring functions that need a special exemption for runtimes.


### Role level

This sets the timeout for a specific role.

The default role timeouts are:

*   `anon`: 3s
*   `authenticated`: 8s
*   `service_role`: none (defaults to the `authenticator` role's 8s timeout if unset)
*   `postgres`: none (capped by default global timeout to be 2min)

Run the following query to change a role's timeout:

```sql
alter role example_role set statement_timeout = '10min'; -- could also use seconds '10s'
```

Unlike global settings, the result cannot be checked with `SHOW
statement_timeout`. Instead, run:

```sql
select
  rolname,
  rolconfig
from pg_roles
where
  rolname in (
    'anon',
    'authenticated',
    'postgres',
    'service_role'
    -- ,<ANY CUSTOM ROLES>
  );
```


### Global level

This changes the statement timeout for all roles and sessions without an explicit timeout already set.

```sql
alter database postgres set statement_timeout TO '4s';
```

Check if your changes took effect:

```sql
show statement_timeout;
```

Although not necessary, if you are uncertain if a timeout has been applied, you can run a quick test:

```sql
create or replace function myfunc()
returns void as $$
  select pg_sleep(601); -- simulating some long-running process
$$
language sql;
```


## Identifying timeouts

The Supabase Dashboard contains tools to help you identify timed-out and long-running queries.


### Using the Logs Explorer

Go to the [Logs Explorer](/dashboard/project/_/logs/explorer), and run the following query to identify timed-out events (`statement timeout`) and queries that successfully run for longer than 10 seconds (`duration`).

```sql
select
  cast(postgres_logs.timestamp as datetime) as timestamp,
  event_message,
  parsed.error_severity,
  parsed.user_name,
  parsed.query,
  parsed.detail,
  parsed.hint,
  parsed.sql_state_code,
  parsed.backend_type
from
  postgres_logs
  cross join unnest(metadata) as metadata
  cross join unnest(metadata.parsed) as parsed
where
  regexp_contains(event_message, 'duration|statement timeout')
  -- (OPTIONAL) MODIFY OR REMOVE
  and parsed.user_name = 'authenticator' -- <--------CHANGE
order by timestamp desc
limit 100;
```


### Using the Query Performance page

Go to the [Query Performance page](/dashboard/project/_/advisors/query-performance?preset=slowest_execution) and filter by relevant role and query speeds. This only identifies slow-running but successful queries. Unlike the Log Explorer, it does not show you timed-out queries.


### Understanding roles in logs

Each API server uses a designated user for connecting to the database:

| Role                         | API/Tool                                                                  |
| ---------------------------- | ------------------------------------------------------------------------- |
| `supabase_admin`             | Used by Realtime and for project configuration                            |
| `authenticator`              | PostgREST                                                                 |
| `supabase_auth_admin`        | Auth                                                                      |
| `supabase_storage_admin`     | Storage                                                                   |
| `supabase_replication_admin` | Synchronizes Read Replicas                                                |
| `postgres`                   | Supabase Dashboard and External Tools (e.g., Prisma, SQLAlchemy, PSQL...) |
| Custom roles                 | External Tools (e.g., Prisma, SQLAlchemy, PSQL...)                        |

Filter by the `parsed.user_name` field to only retrieve logs made by specific users:

```sql
-- find events based on role/server
... query
where
  -- find events from the relevant role
  parsed.user_name = '<ROLE>'
```


# Postgres Triggers

Automatically execute SQL on table events.

In Postgres, a trigger executes a set of actions automatically on table events such as INSERTs, UPDATEs, DELETEs, or TRUNCATE operations.


## Creating a trigger

Creating triggers involve 2 parts:

1.  A [Function](/docs/guides/database/functions) which will be executed (called the Trigger Function)
2.  The actual Trigger object, with parameters around when the trigger should be run.

An example of a trigger is:

```sql
create trigger "trigger_name"
after insert on "table_name"
for each row
execute function trigger_function();
```


## Trigger functions

A trigger function is a user-defined [Function](/docs/guides/database/functions) that Postgres executes when the trigger is fired.


### Example trigger function

Here is an example that updates `salary_log` whenever an employee's salary is updated:

```sql
-- Example: Update salary_log when salary is updated
create function update_salary_log()
returns trigger
language plpgsql
as $$
begin
  insert into salary_log(employee_id, old_salary, new_salary)
  values (new.id, old.salary, new.salary);
  return new;
end;
$$;

create trigger salary_update_trigger
after update on employees
for each row
execute function update_salary_log();
```


### Trigger variables

Trigger functions have access to several special variables that provide information about the context of the trigger event and the data being modified. In the example above you can see the values inserted into the salary log are `old.salary` and `new.salary` - in this case `old` specifies the previous values and `new` specifies the updated values.

Here are some of the key variables and options available within trigger functions:

*   `TG_NAME`: The name of the trigger being fired.
*   `TG_WHEN`: The timing of the trigger event (`BEFORE` or `AFTER`).
*   `TG_OP`: The operation that triggered the event (`INSERT`, `UPDATE`, `DELETE`, or `TRUNCATE`).
*   `OLD`: A record variable holding the old row's data in `UPDATE` and `DELETE` triggers.
*   `NEW`: A record variable holding the new row's data in `UPDATE` and `INSERT` triggers.
*   `TG_LEVEL`: The trigger level (`ROW` or `STATEMENT`), indicating whether the trigger is row-level or statement-level.
*   `TG_RELID`: The object ID of the table on which the trigger is being fired.
*   `TG_TABLE_NAME`: The name of the table on which the trigger is being fired.
*   `TG_TABLE_SCHEMA`: The schema of the table on which the trigger is being fired.
*   `TG_ARGV`: An array of string arguments provided when creating the trigger.
*   `TG_NARGS`: The number of arguments in the `TG_ARGV` array.


## Types of triggers

There are two types of trigger, `BEFORE` and `AFTER`:


### Trigger before changes are made

Executes before the triggering event.

```sql
create trigger before_insert_trigger
before insert on orders
for each row
execute function before_insert_function();
```


### Trigger after changes are made

Executes after the triggering event.

```sql
create trigger after_delete_trigger
after delete on customers
for each row
execute function after_delete_function();
```


## Execution frequency

There are two options available for executing triggers:

*   `for each row`: specifies that the trigger function should be executed once for each affected row.
*   `for each statement`: the trigger is executed once for the entire operation (for example, once on insert). This can be more efficient than `for each row` when dealing with multiple rows affected by a single SQL statement, as they allow you to perform calculations or updates on groups of rows at once.


## Dropping a trigger

You can delete a trigger using the `drop trigger` command:

```sql
drop trigger "trigger_name" on "table_name";
```


## Resources

*   Official Postgres Docs: [Triggers](https://www.postgresql.org/docs/current/triggers.html)
*   Official Postgres Docs: [Overview of Trigger Behavior](https://www.postgresql.org/docs/current/trigger-definition.html)
*   Official Postgres Docs: [CREATE TRIGGER](https://www.postgresql.org/docs/current/sql-createtrigger.html)


# Print PostgreSQL version



It's important to know which version of Postgres you are running as each major version has different features and may cause breaking changes. You may also need to update your schema when [upgrading](https://www.postgresql.org/docs/current/pgupgrade.html) or downgrading to a major Postgres version.

Run the following query using the [SQL Editor](https://supabase.com/dashboard/project/_/sql) in the Supabase Dashboard:

```sql
select
  version();
```

Which should return something like:

```sql
PostgreSQL 15.1 on aarch64-unknown-linux-gnu, compiled by gcc (Ubuntu 10.3.0-1ubuntu1~20.04) 10.3.0, 64-bit
```

This query can also be executed via `psql` or any other query editor if you prefer to [connect directly to the database](/docs/guides/database/connecting-to-postgres#direct-connections).


# Prisma



This quickly shows how to connect your Prisma application to Supabase Postgres. If you encounter any problems, reference the [Prisma troubleshooting docs](/docs/guides/database/prisma/prisma-troubleshooting).


# Troubleshooting prisma errors



This guide addresses common Prisma errors that you might encounter while using Supabase.


## Understanding connection string parameters: \[#start]

Unlike other libraries, Prisma lets you configure [its settings](https://www.prisma.io/docs/orm/overview/databases/postgresql#arguments) through special options appended to your connection string.

These options, called "query parameters," can be used to address specific errors.

```md
# Example of query parameters

connection_string.../postgres?KEY1=VALUE&KEY2=VALUE&KEY3=VALUE
```


# Errors


## ... prepared statement already exists

Supavisor in transaction mode (port 6543) does not support [prepared statements](https://www.postgresql.org/docs/current/sql-prepare.html), which Prisma will try to create in the background.


### Solution: \[#solution-prepared-statement-exists]

*   Add `pgbouncer=true` to the connection string. This turns off prepared statements in Prisma.

```md
.../postgres?pgbouncer=true
```

***


## Can't reach database server at:

Prisma couldn't establish a connection with Postgres or Supavisor before the timeout


### Possible causes: \[#possible-causes-cant-reach-database-server-at]

*   **Database overload**: The database server is under heavy load, causing Prisma to struggle to connect.
*   **Malformed connection string**: The connection string used by Prisma is incorrect or incomplete.
*   **Transient network issues**: Temporary network problems are disrupting the connection.


### Solutions: \[#solution-cant-reach-database-server-at]

*   **Check database health**: Use the [Reports Dashboard](https://supabase.com/dashboard/project/_/reports/database) to monitor CPU, memory, and I/O usage. If the database is overloaded, consider increasing your [compute size](https://supabase.com/docs/guides/platform/compute-add-ons) or [optimizing your queries](https://supabase.com/docs/guides/database/query-optimization).
*   **Verify connection string**: Double-check the connection string in your Prisma configuration to ensure it matches one in your [Database Settings](https://supabase.com/dashboard/project/_/settings/database).
*   **Increase connection timeout**: Try increasing the `connect_timeout` parameter in your Prisma configuration to give it more time to establish a connection.

```md
.../postgres?connect_timeout=30
```

***


## Timed out fetching a new connection from the connection pool:

Prisma is unable to allocate connections to pending queries fast enough to meet demand.


### Possible causes: \[#possible-causes-timed-out-fetching-a-new-connection]

*   **Overwhelmed server**: The server hosting Prisma is under heavy load, limiting its ability to manage connections. By default, Prisma will create the default `num_cpus * 2 + 1` worth of connections. A common cause for server strain is increasing the `connection_limit` significantly past the default.
*   **Insufficient pool size**: The Supavisor pooler does not have enough connections available to quickly satisfy Prisma's requests.
*   **Slow queries**: Prisma's queries are taking too long to execute, preventing it from releasing connections for reuse.


### Solutions: \[#solution-timed-out-fetching-a-new-connection]

*   **Increase the pool timeout**: Increase the `pool_timeout` parameter in your Prisma configuration to give the pooler more time to allocate connections.
*   **Reduce the connection limit**: If you've explicitly increased the `connection_limit` parameter in your Prisma configuration, try reducing it to a more reasonable value.
*   **Increase pool size**: If you are connecting with Supavisor, try increasing the pool size in the [Database Settings](https://supabase.com/dashboard/project/_/settings/database).
*   **Optimize queries**: [Improve the efficiency of your queries](https://supabase.com/docs/guides/database/query-optimization) to reduce execution time.
*   **Increase compute size**: Like the preceding option, this is a strategy to reduce query execution time.

***


## Server has closed the connection

According to this [GitHub Issue for Prisma](https://github.com/prisma/prisma/discussions/7389), this error may be related to large return values for queries. It may also be caused by significant database strain.


### Solutions: \[#solution-server-has-closed-the-connection]

*   **Limit row return sizes**: Try to limit the total amount of rows returned for particularly large requests.
*   **Minimize database strain**:Check the Reports Page for database strain. If there is obvious strain, consider [optimizing](https://supabase.com/docs/guides/database/query-optimization) or increasing compute size

***


## Drift detected: Your database schema is not in sync with your migration history

Prisma relies on migration files to ensure your database aligns with Prisma's model. External schema changes are detected as "drift", which Prisma will try to overwrite, potentially causing data loss.


### Possible causes: \[#possible-causes-your-database-schema-is-not-in-sync]

*   **Supabase Managed Schemas**: Supabase may update managed schemas like auth and storage to introduce new features. Granting Prisma access to these schemas can lead to drift during updates.
*   **External Schema Modifications**: Your team or another tool might have modified the database schema outside of Prisma, causing drift.


### Solution: \[#solution-your-database-schema-is-not-in-sync]

*   **Baselining migrations**: [baselining](https://www.prisma.io/docs/orm/prisma-migrate/workflows/baselining) re-syncs Prisma by capturing the current database schema as the starting point for future migrations.

***


## Max client connections reached

Postgres or Supavisor rejected a request for more connections


### Possible causes:\[#possible-causes-max-client-connections-reached]

*   **When working in transaction mode (port 6543):** The error "Max client connections reached" occurs when clients try to form more connections with the pooler than it can support.
*   **When working in session mode (port 5432):** The max amount of clients is restricted to the "Pool Size" value in the [Database Settings](https://supabase.com/dashboard/project/_/settings/database). If the "Pool Size" is set to 15, even if the pooler can handle 200 client connections, it will still be effectively capped at 15 for each unique ["database-role+database" combination](https://github.com/orgs/supabase/discussions/21566).
*   **When working with direct connections**: Postgres is already servicing the max amount of connections


### Solutions \[#solutions-causes-max-client-connections-reached]

*   **Transaction Mode for serverless apps**: If you are using serverless functions (Supabase Edge, Vercel, AWS Lambda), switch to transaction mode (port 6543). It handles more connections than session mode or direct connections.
*   **Reduce the number of Prisma connections**: A single client-server can establish multiple connections with a pooler. Typically, serverless setups do not need many connections. Starting with fewer, like five or three, or even just one, is often sufficient. In serverless setups, begin with `connection_limit=1`, increasing cautiously if needed to avoid maxing out connections.
*   **Increase pool size**: If you are connecting with Supavisor, try increasing the pool size in the [Database Settings](https://supabase.com/dashboard/project/_/settings/database).
*   **Disconnect appropriately**: Close Prisma connections when they are no longer needed.
*   **Decrease query time**: Reduce query complexity or add [strategic indexes](https://supabase.com/docs/guides/database/postgres/indexes) to your tables to speed up queries.
*   **Increase compute size**: Sometimes the best option is to increase your compute size, which also increases your max client size and query execution speed

***


## Cross schema references are only allowed when the target schema is listed in the schemas property of your data-source

A Prisma migration is referencing a schema it is not permitted to manage.


### Possible causes: \[#possible-causes-cross-schema-references]

*   A migration references a schema that Prisma is not permitted to manage


### Solutions: \[#solutions-cross-schema-references]

*   Multi-Schema support: If the external schema isn't Supabase managed, modify your `prisma.schema` file to enable the multi-Schema preview

```ts prisma.schema
generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["multiSchema"]  //Add line
}

datasource db {
  provider  = "postgresql"
  url       = env("DATABASE_URL")
  directUrl = env("DIRECT_URL")
  schemas   = ["public", "other_schema"] //list out relevant schemas
}
```

*   Supabase managed schemas: Schemas managed by Supabase, such as `auth` and `storage`, may be changed to support new features. Referencing these schemas directly will cause schema drift in the future. It is best to remove references to these schemas from your migrations.

An alternative strategy to reference these tables is to duplicate values into Prisma managed table with triggers. Below is an example for duplicating values from `auth.users` into a table called `profiles`.


# Connecting with PSQL



[`psql`](https://www.postgresql.org/docs/current/app-psql.html) is a command-line tool that comes with Postgres.


## Connecting with SSL

You should connect to your database using SSL wherever possible, to prevent snooping and man-in-the-middle attacks.

You can obtain your connection info and Server root certificate from your application's dashboard:

![Connection Info and Certificate.](/docs/img/database/database-settings-ssl.png)

Download your [SSL certificate](#connecting-with-ssl) to `/path/to/prod-supabase.cer`.

Find your connection settings. Go to your [`Database Settings`](https://supabase.com/dashboard/project/_/settings/database) and make sure `Use connection pooling` is checked. Change the connection mode to `Session`, and copy the parameters into the connection string:

```shell
psql "sslmode=verify-full sslrootcert=/path/to/prod-supabase.cer host=[CLOUD_PROVIDER]-0-[REGION].pooler.supabase.com dbname=postgres user=postgres.[PROJECT_REF]"
```


# Query Optimization

Choosing indexes to improve your query performance.

When working with Postgres, or any relational database, indexing is key to improving query performance. Aligning indexes with common query patterns can speed up data retrieval by an order of magnitude.

This guide is intended to:

*   help identify parts of a query that have the potential to be improved by indexes
*   introduce tooling to help identify useful indexes

This is not a comprehensive resource, but rather a helpful starting point for your optimization journey.

If you're new to query optimization, you may be interested in [`index_advisor`](/docs/guides/database/extensions/index_advisor), our tool for automatically detecting indexes that improve performance on a given query.


## Example query

Consider the following example query that retrieves customer names and purchase dates from two tables:

```sql
select
  a.name,
  b.date_of_purchase
from
  customers as a
  join orders as b on a.id = b.customer_id
where a.sign_up_date > '2023-01-01' and b.status = 'shipped'
order by b.date_of_purchase
limit 10;
```

In this query, there are several parts that indexes could likely help in optimizing the performance:


### `where` clause:

The `where` clause filters rows based on certain conditions, and indexing the columns involved can improve this process:

*   `a.sign_up_date`: If filtering by `sign_up_date` is common, indexing this column can speed up the query.
*   `b.status`: Indexing the status may be beneficial if the column has diverse values.

```sql
create index idx_customers_sign_up_date on customers (sign_up_date);

create index idx_orders_status on orders (status);
```


### `join` columns

Indexes on the columns used for joining tables can help Postgres avoid scanning tables in their entirety when connecting tables.

*   Indexing `a.id` and `b.customer_id` would likely improve the performance of the join in this query.
*   Note that if `a.id` is the primary key of the `customers` table it is already indexed

```sql
create index idx_orders_customer_id on orders (customer_id);
```


### `order by` clause

Sorting can also be optimized by indexing:

*   An index on `b.date_of_purchase` can improve the sorting process, and is particularly beneficial when a subset of rows is being returned with a `limit` clause.

```sql
create index idx_orders_date_of_purchase on orders (date_of_purchase);
```


## Key concepts

Here are some concepts and tools to keep in mind to help you identify the best index for the job, and measure the impact that your index had:


### Analyze the query plan

Use the `explain` command to understand the query's execution. Look for slow parts, such as Sequential Scans or high cost numbers. If creating an index does not reduce the cost of the query plan, remove it.

For example:

```sql
explain select * from customers where sign_up_date > 25;
```


### Use appropriate index types

Postgres offers various index types like [B-tree, Hash, GIN, etc](https://www.postgresql.org/docs/current/indexes-types.html). Select the type that best suits your data and query pattern. Using the right index type can make a significant difference. For example, using a BRIN index on a field that always increases and lives within a table that updates infrequently - like `created_at` on an `orders` table - routinely results in indexes that are +10x smaller than the equivalent default B-tree index. That translates into better scalability.

```sql
create index idx_orders_created_at ON customers using brin(created_at);
```


### Partial indexes

For queries that frequently target a subset of data, a partial index could be faster and smaller than indexing the entire column. A partial index contains a `where` clause to filter the values included in the index. Note that a query's `where` clause must match the index for it to be used.

```sql
create index idx_orders_status on orders (status)
where status = 'shipped';
```


### Composite indexes

If filtering or joining on multiple columns, a composite index prevents Postgres from referring to multiple indexes when identifying the relevant rows.

```sql
create index idx_customers_sign_up_date_priority on customers (sign_up_date, priority);
```


### Over-Indexing

Avoid the urge to index columns you operate on infrequently. While indexes can speed up reads, they also slow down writes, so it's important to balance those factors when making indexing decisions.


### Statistics

Postgres maintains a set of statistics about the contents of your tables. Those statistics are used by the query planner to decide when it's is more efficient to use an index vs scanning the entire table. If the collected statistics drift too far from reality, the query planner may make poor decisions. To avoid this risk, you can periodically `analyze` tables.

```sql
analyze customers;
```

***

By following this guide, you'll be able to discern where indexes can optimize queries and enhance your Postgres performance. Remember that each database is unique, so always consider the specific context and use case of your queries.


# Replication



Replication is a technique for copying the data from one database to another. Supabase uses replication functionality to provide a real-time API. Replication is useful for:

*   Spreading out the "load." For example, if your database has a lot of reads, you might want to split it between two databases.
*   Reducing latency. For example, you may want one database in London to serve your European customers, and one in New York to serve the US.

Replication is done through *publications*, a method of choosing which changes to send to other systems (usually another Postgres database). Publications can be managed in the [Dashboard](https://supabase.com/dashboard) or with SQL.


## Manage publications in the dashboard

1.  Go to the [Database](https://supabase.com/dashboard/project/_/database/tables) page in the Dashboard.
2.  Click on **Publications** in the sidebar.
3.  Control which database events are sent by toggling **Insert**, **Update**, and **Delete**.
4.  Control which tables broadcast changes by selecting **Source** and toggling each table.


## Create a publication

This publication contains changes to all tables.

```sql
create publication publication_name
for all tables;
```


## Create a publication to listen to individual tables

```sql
create publication publication_name
for table table_one, table_two;
```


## Add tables to an existing publication

```sql
alter publication publication_name
add table table_name;
```


## Listen to `insert`

```sql
create publication publication_name
for all tables
with (publish = 'insert');
```


## Listen to `update`

```sql
create publication publication_name
for all tables
with (publish = 'update');
```


## Listen to `delete`

```sql
create publication publication_name
for all tables
with (publish = 'delete');
```


## Remove a publication

```sql
drop publication if exists publication_name;
```


## Recreate a publication

If you're recreating a publication, it's best to do it in a transaction to ensure the operation succeeds.

```sql
begin;
  -- remove the realtime publication
  drop publication if exists publication_name;

  -- re-create the publication but don't enable it for any tables
  create publication publication_name;
commit;
```


# Securing your data



Supabase helps you control access to your data. With access policies, you can protect sensitive data and make sure users only access what they're allowed to see.


## Connecting your app securely

Supabase allows you to access your database using the auto-generated [Data APIs](/docs/guides/database/connecting-to-postgres#data-apis). This speeds up the process of building web apps, since you don't need to write your own backend services to pass database queries and results back and forth.

You can keep your data secure while accessing the Data APIs from the frontend, so long as you:

*   Turn on [Row Level Security](/docs/guides/database/postgres/row-level-security) (RLS) for your tables
*   Use your Supabase **anon key** when you create a Supabase client

Your anon key is safe to expose with RLS enabled, because row access permission is checked against your access policies and the user's [JSON Web Token (JWT)](/docs/learn/auth-deep-dive/auth-deep-dive-jwts). The JWT is automatically sent by the Supabase client libraries if the user is logged in using Supabase Auth.


## More information

Supabase and Postgres provide you with multiple ways to manage security, including but not limited to Row Level Security. See the Access and Security pages for more information:

*   [Row Level Security](/docs/guides/database/postgres/row-level-security)
*   [Column Level Security](/docs/guides/database/postgres/column-level-security)
*   [Hardening the Data API](/docs/guides/database/hardening-data-api)
*   [Managing Postgres roles](/docs/guides/database/postgres/roles)
*   [Managing secrets with Vault](/docs/guides/database/vault)


# Supavisor

Troubleshooting Supavisor errors

Supavisor logs are available under [Pooler Logs](/dashboard/project/_/logs/pooler-logs) in the Dashboard. The following are common errors and their solutions:

| Error Type                                                                | Description                                                                                                                                                                                                                                                                 | Resolution Link                                                                     |
| ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| Max client connections reached                                            | This error happens when the number of connections to Supavisor is more than [the allowed limit of your compute add-on](https://supabase.com/docs/guides/platform/compute-add-ons).                                                                                          | Follow this [guide](https://github.com/orgs/supabase/discussions/22305) to resolve. |
| Connection failed `{:error, :eaddrnotavail}` to 'db.xxx.supabase.co':5432 | Supavisor cannot connect to the customer database. This is usually caused if the target database is unable to respond.                                                                                                                                                      | N/A                                                                                 |
| Connection failed `{:error, :nxdomain}` to 'db.xxx.supabase.co':5432      | Supavisor cannot connect to the customer database. This is usually caused if the target database is unable to respond.                                                                                                                                                      | N/A                                                                                 |
| Connection closed when state was authentication                           | This error happens when either the database doesn’t exist or if the user doesn't have the right credentials.                                                                                                                                                                | N/A                                                                                 |
| Subscribe error: `{:error, :worker_not_found}`                            | This log event is emitted when the client tries to connect to the database, but Supavisor does not have the necessary information to route the connection. Try reconnecting to the database as it can take some time for the project information to propagate to Supavisor. | N/A                                                                                 |
| Subscribe error: `{:error, {:badrpc, {:error, {:erpc, :timeout}}}}`       | This is a timeout error when the communication between different Supavisor nodes takes longer than expected. Try reconnecting to the database.                                                                                                                              | N/A                                                                                 |
| Terminating with reason :client\_termination when state was :busy          | This error happens when the client terminates the connection before the connection with the database is completed.                                                                                                                                                          | N/A                                                                                 |
| Error: received invalid response to GSSAPI negotiation: S                 | This error happens due to `gssencmode` parameter not set to disabled.                                                                                                                                                                                                       | Follow this [guide](https://github.com/orgs/supabase/discussions/30173) to resolve. |


# Tables and Data



Tables are where you store your data.

Tables are similar to excel spreadsheets. They contain columns and rows.
For example, this table has 3 "columns" (`id`, `name`, `description`) and 4 "rows" of data:

| `id` | `name`               | `description`                                                                                                                                                 |
| ---- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1    | The Phantom Menace   | Two Jedi escape a hostile blockade to find allies and come across a young boy who may bring balance to the Force.                                             |
| 2    | Attack of the Clones | Ten years after the invasion of Naboo, the Galactic Republic is facing a Separatist movement.                                                                 |
| 3    | Revenge of the Sith  | As Obi-Wan pursues a new threat, Anakin acts as a double agent between the Jedi Council and Palpatine and is lured into a sinister plan to rule the galaxy.   |
| 4    | Star Wars            | Luke Skywalker joins forces with a Jedi Knight, a cocky pilot, a Wookiee and two droids to save the galaxy from the Empire's world-destroying battle station. |

There are a few important differences from a spreadsheet, but it's a good starting point if you're new to Relational databases.


## Creating tables

When creating a table, it's best practice to add columns at the same time.

You must define the "data type" of each column when it is created. You can add and remove columns at any time after creating a table.

Supabase provides several options for creating tables. You can use the Dashboard or create them directly using SQL.
We provide a SQL editor within the Dashboard, or you can [connect](../../guides/database/connecting-to-postgres) to your database
and run the SQL queries yourself.


## Columns

You must define the "data type" when you create a column.


### Data types

Every column is a predefined type. Postgres provides many [default types](https://www.postgresql.org/docs/current/datatype.html), and you can even design your own (or use extensions) if the default types don't fit your needs. You can use any data type that Postgres supports via the SQL editor. We only support a subset of these in the Table Editor in an effort to keep the experience simple for people with less experience with databases.

You can "cast" columns from one type to another, however there can be some incompatibilities between types.
For example, if you cast a `timestamp` to a `date`, you will lose all the time information that was previously saved.


### Primary keys

A table can have a "primary key" - a unique identifier for every row of data. A few tips for Primary Keys:

*   It's recommended to create a Primary Key for every table in your database.
*   You can use any column as a primary key, as long as it is unique for every row.
*   It's common to use a `uuid` type or a numbered `identity` column as your primary key.

```sql
create table movies (
  id bigint generated always as identity primary key
);
```

In the example above, we have:

1.  created a column called `id`
2.  assigned the data type `bigint`
3.  instructed the database that this should be `generated always as identity`, which means that Postgres will automatically assign a unique number to this column.
4.  Because it's unique, we can also use it as our `primary key`.

We could also use `generated by default as identity`, which would allow us to insert our own unique values.

```sql
create table movies (
  id bigint generated by default as identity primary key
);
```


## Loading data

There are several ways to load data in Supabase. You can load data directly into the database or using the [APIs](../../guides/database/api).
Use the "Bulk Loading" instructions if you are loading large data sets.


### Basic data loading


### Bulk data loading

When inserting large data sets it's best to use PostgreSQL's [COPY](https://www.postgresql.org/docs/current/sql-copy.html) command.
This loads data directly from a file into a table. There are several file formats available for copying data: text, CSV, binary, JSON, etc.

For example, if you wanted to load a CSV file into your movies table:

```text ./movies.csv
"The Empire Strikes Back", "After the Rebels are brutally overpowered by the Empire on the ice planet Hoth, Luke Skywalker begins Jedi training with Yoda."
"Return of the Jedi", "After a daring mission to rescue Han Solo from Jabba the Hutt, the Rebels dispatch to Endor to destroy the second Death Star."
```

You would [connect](../../guides/database/connecting-to-postgres#direct-connections) to your database directly and load the file with the COPY command:

```bash
psql -h DATABASE_URL -p 5432 -d postgres -U postgres \
  -c "\COPY movies FROM './movies.csv';"
```

Additionally use the `DELIMITER`, `HEADER` and `FORMAT` options as defined in the Postgres [COPY](https://www.postgresql.org/docs/current/sql-copy.html) docs.

```bash
psql -h DATABASE_URL -p 5432 -d postgres -U postgres \
  -c "\COPY movies FROM './movies.csv' WITH DELIMITER ',' CSV HEADER"
```

If you receive an error `FATAL:  password authentication failed for user "postgres"`, reset your database password in the Database Settings and try again.


## Joining tables with foreign keys

Tables can be "joined" together using Foreign Keys.

This is where the "Relational" naming comes from, as data typically forms some sort of relationship.

In our "movies" example above, we might want to add a "category" for each movie (for example, "Action", or "Documentary").
Let's create a new table called `categories` and "link" our `movies` table.

```sql
create table categories (
  id bigint generated always as identity primary key,
  name text -- category name
);

alter table movies
  add column category_id bigint references categories;
```

You can also create "many-to-many" relationships by creating a "join" table.
For example if you had the following situations:

*   You have a list of `movies`.
*   A movie can have several `actors`.
*   An `actor` can perform in several movies.


## Schemas

Tables belong to `schemas`. Schemas are a way of organizing your tables, often for security reasons.

If you don't explicitly pass a schema when creating a table, Postgres will assume that you want to create the table in the `public` schema.

We can create schemas for organizing tables. For example, we might want a private schema which is hidden from our API:

```sql
create schema private;
```

Now we can create tables inside the `private` schema:

```sql
create table private.salaries (
  id bigint generated by default as identity primary key,
  salary bigint not null,
  actor_id bigint not null references public.actors
);
```


## Views

A View is a convenient shortcut to a query. Creating a view does not involve new tables or data. When run, an underlying query is executed, returning its results to the user.

Say we have the following tables from a database of a university:

**`students`**

| id  | name             | type          |
| --- | ---------------- | ------------- |
| 1   | Princess Leia    | undergraduate |
| 2   | Yoda             | graduate      |
| 3   | Anakin Skywalker | graduate      |

**`courses`**

| id  | title                    | code    |
| --- | ------------------------ | ------- |
| 1   | Introduction to Postgres | PG101   |
| 2   | Authentication Theories  | AUTH205 |
| 3   | Fundamentals of Supabase | SUP412  |

**`grades`**

| id  | student\_id | course\_id | result |
| --- | ---------- | --------- | ------ |
| 1   | 1          | 1         | B+     |
| 2   | 1          | 3         | A+     |
| 3   | 2          | 2         | A      |
| 4   | 3          | 1         | A-     |
| 5   | 3          | 2         | A      |
| 6   | 3          | 3         | B-     |

Creating a view consisting of all the three tables will look like this:

```sql
create view transcripts as
    select
        students.name,
        students.type,
        courses.title,
        courses.code,
        grades.result
    from grades
    left join students on grades.student_id = students.id
    left join courses on grades.course_id = courses.id;

grant all on table transcripts to authenticated;
```

Once done, we can now access the underlying query with:

```sql
select * from transcripts;
```


### View security

By default, views are accessed with their creator's permission ("security definer"). If a privileged role creates a view, others accessing it will use that role's elevated permissions. To enforce row level security policies, define the view with the "security invoker" modifier.

```sql
-- alter a security_definer view to be security_invoker
alter view <view name>
set (security_invoker = true);

-- create a view with the security_invoker modifier
create view <view name> with(security_invoker=true) as (
  select * from <some table>
);
```


### When to use views

Views provide the several benefits:

*   Simplicity
*   Consistency
*   Logical Organization
*   Security


#### Simplicity

As a query becomes more complex, it can be a hassle to call it over and over - especially when we run it regularly. In the example above, instead of repeatedly running:

```sql
select
  students.name,
  students.type,
  courses.title,
  courses.code,
  grades.result
from
  grades
  left join students on grades.student_id = students.id
  left join courses on grades.course_id = courses.id;
```

We can run this instead:

```sql
select * from transcripts;
```

Additionally, a view behaves like a typical table. We can safely use it in table `JOIN`s or even create new views using existing views.


#### Consistency

Views ensure that the likelihood of mistakes decreases when repeatedly executing a query. In our example above, we may decide that we want to exclude the course *Introduction to Postgres*. The query would become:

```sql
select
  students.name,
  students.type,
  courses.title,
  courses.code,
  grades.result
from
  grades
  left join students on grades.student_id = students.id
  left join courses on grades.course_id = courses.id
where courses.code != 'PG101';
```

Without a view, we would need to go into every dependent query to add the new rule. This would increase in the likelihood of errors and inconsistencies, as well as introducing a lot of effort for a developer. With views, we can alter just the underlying query in the view **transcripts**. The change will be applied to all applications using this view.


#### Logical organization

With views, we can give our query a name. This is extremely useful for teams working with the same database. Instead of guessing what a query is supposed to do, a well-named view can explain it. For example, by looking at the name of the view **transcripts**, we can infer that the underlying query might involve the **students**, **courses**, and **grades** tables.


#### Security

Views can restrict the amount and type of data presented to a user. Instead of allowing a user direct access to a set of tables, we provide them a view instead. We can prevent them from reading sensitive columns by excluding them from the underlying query.


### Materialized views

A [materialized view](https://www.postgresql.org/docs/12/rules-materializedviews.html) is a form of view but it also stores the results to disk. In subsequent reads of a materialized view, the time taken to return its results would be much faster than a conventional view. This is because the data is readily available for a materialized view while the conventional view executes the underlying query each time it is called.

Using our example above, a materialized view can be created like this:

```sql
create materialized view transcripts as
  select
    students.name,
    students.type,
    courses.title,
    courses.code,
    grades.result
  from
    grades
    left join students on grades.student_id = students.id
    left join courses on grades.course_id = courses.id;
```

Reading from the materialized view is the same as a conventional view:

```sql
select * from transcripts;
```


### Refreshing materialized views

Unfortunately, there is a trade-off - data in materialized views are not always up to date. We need to refresh it regularly to prevent the data from becoming too stale. To do so:

```sql
refresh materialized view transcripts;
```

It's up to you how regularly refresh your materialized views, and it's probably different for each view depending on its use-case.


### Materialized views vs conventional views

Materialized views are useful when execution times for queries or views are too slow. These could likely occur in views or queries involving multiple tables and billions of rows. When using such a view, however, there should be tolerance towards data being outdated. Some use-cases for materialized views are internal dashboards and analytics.

Creating a materialized view is not a solution to inefficient queries. You should always seek to optimize a slow running query even if you are implementing a materialized view.


## Resources

*   [Official Docs: Create table](https://www.postgresql.org/docs/current/sql-createtable.html)
*   [Official Docs: Create view](https://www.postgresql.org/docs/12/sql-createview.html)
*   [Postgres Tutorial: Create tables](https://www.postgresqltutorial.com/postgresql-tutorial/postgresql-create-table/)
*   [Postgres Tutorial: Add column](https://www.postgresqltutorial.com/postgresql-tutorial/postgresql-add-column/)
*   [Postgres Tutorial: Views](https://www.postgresqltutorial.com/postgresql-views/)


# Testing Your Database



To ensure that queries return the expected data, RLS policies are correctly applied and etc., we encourage you to write automated tests. There are essentially two approaches to testing:

*   Firstly, you can write tests that interface with a Supabase client instance (same way you use Supabase client in your application code) in the programming language(s) you use in your application and using your favorite testing framework.

*   Secondly, you can test through the Supabase CLI, which is a more low-level approach where you write tests in SQL.


# Testing using the Supabase CLI

You can use the Supabase CLI to test your database. The minimum required version of the CLI is [v1.11.4](https://github.com/supabase/cli/releases). To get started:

*   [Install the Supabase CLI](/docs/guides/cli) on your local machine


## Creating a test

Create a tests folder inside the `supabase` folder:

```bash
mkdir -p ./supabase/tests/database
```

Create a new file with the `.sql` extension which will contain the test.

```bash
touch ./supabase/tests/database/hello_world.test.sql
```


## Writing tests

All `sql` files use [pgTAP](/docs/guides/database/extensions/pgtap) as the test runner.

Let's write a simple test to check that our `auth.users` table has an ID column. Open `hello_world.test.sql` and add the following code:

```sql
begin;
select plan(1); -- only one statement to run

SELECT has_column(
    'auth',
    'users',
    'id',
    'id should exist'
);

select * from finish();
rollback;
```


## Running tests

To run the test, you can use:

```bash
supabase test db
```

This will produce the following output:

```bash
$ supabase test db
supabase/tests/database/hello_world.test.sql .. ok
All tests successful.
Files=1, Tests=1,  1 wallclock secs ( 0.01 usr  0.00 sys +  0.04 cusr  0.02 csys =  0.07 CPU)
Result: PASS
```


## More resources

*   [Testing RLS policies](/docs/guides/database/extensions/pgtap#testing-rls-policies)
*   [pgTAP extension](/docs/guides/database/extensions/pgtap)
*   Official [pgTAP documentation](https://pgtap.org/)


# Vault

Managing secrets in Postgres.

Vault is a Postgres extension and accompanying Supabase UI that makes it safe and easy to store encrypted secrets and other data in your database. This opens up a lot of possibilities to use Postgres in ways that go beyond what is available in a stock distribution.

Under the hood, the Vault is a table of Secrets and Encryption Keys that are stored using [Authenticated Encryption](https://en.wikipedia.org/wiki/Authenticated_encryption) on disk. They are then available in decrypted form through a Postgres view so that the secrets can be used by applications from SQL. Because the secrets are stored on disk encrypted and authenticated, any backups or replication streams also preserve this encryption in a way that can't be decrypted or forged.

Supabase provides a dashboard UI for the Vault that makes storing secrets easy. Click a button, type in your secret, and save. Optionally create your own keys you can use to encrypt your secret. Your secret will then be stored on disk encrypted using the specified key.

There are two main parts to the Vault UI, Secrets and Encryption Keys:


## Secrets

You can use the Vault to store secrets - everything from Environment Variables to API Keys. You can then use these secrets anywhere in your database: Postgres [Functions](/docs/guides/database/functions), Triggers, and [Webhooks](/docs/guides/database/webhooks). From a SQL perspective, accessing secrets is as easy as querying a table (or in this case, a view). The underlying secrets tables will be stored in encrypted form.


## Encryption keys

These are keys used to encrypt data inside your database. You can create different Encryption Keys for different purposes, for example: one for encrypting user-data, and another for application-data. Each key is encrypted itself using a root encryption key that lives outside of the database. See **[Encryption key location](#encryption-key-location)** for more details.


## Using the Vault

You can manage secrets and encryption keys from the UI or using SQL.


### Adding secrets

There is also a handy function for creating secrets called `vault.create_secret()`:

```sql
select vault.create_secret('my_s3kre3t');
```

The function returns the UUID of the new secret.

Secrets can also have an optional *unique* name and an optional description. These are also arguments to `vault.create_secret()`:

```sql
select vault.create_secret('another_s3kre3t', 'unique_name', 'This is the description');
```

Alternatively, you can create a secret by inserting data into the `vault.secret` table:

```sql
insert into vault.secrets (secret)
values ('s3kre3t_k3y') returning *;
```


### Viewing secrets

If you look in the `vault.secrets` table, you will see that your data is stored encrypted. To decrypt the data, there is an automatically created view `vault.decrypted_secrets`. This view will decrypt secret data on the fly:

```sql
select * 
from vault.decrypted_secrets 
order by created_at desc 
limit 3;
```

Notice how this view has a `decrypted_secret` column that contains the decrypted secrets. Views are not stored on disk, they are only run at query time, so the secret remains encrypted on disk, and in any backup dumps or replication streams.

You should ensure that you protect access to this view with the appropriate SQL privilege settings at all times, as anyone that has access to the view has access to decrypted secrets.


### Updating secrets

A secret can be updated with the `vault.update_secret()` function, this function makes updating secrets easy, just provide the secret UUID as the first argument, and then an updated secret, updated optional unique name, or updated description:

```sql
select
  vault.update_secret(
    '7095d222-efe5-4cd5-b5c6-5755b451e223',
    'n3w_upd@ted_s3kret',
    'updated_unique_name',
    'This is the updated description'
  );
```


## Deep dive

As we mentioned, the Vault uses `pgsodium`'s Transparent Column Encryption (TCE) to store secrets in an authenticated encrypted form. There are some details around that you may be curious about, what does authenticated mean, and where are encryption keys store? This section explains those details.


### Authenticated encryption with associated data

The first important feature of TCE is that it uses an [Authenticated Encryption with Associated Data](https://en.wikipedia.org/wiki/Authenticated_encryption#Authenticated_encryption_with_associated_data_\(AEAD\)) encryption algorithm (based on `libsodium`).


### Encryption key location

**Authenticated Encryption** means that in addition to the data being encrypted, it is also signed so that it cannot be forged. You can guarantee that the data was encrypted by someone you trust, which you wouldn't get with encryption alone. The decryption function verifies that the signature is valid *before decrypting the value*.

**Associated Data** means that you can include any other columns from the same row as part of the signature computation. This doesn't encrypt those other columns - rather it ensures that your encrypted value is only associated with columns from that row. If an attacker were to copy an encrypted value from another row to the current one, the signature would be rejected (assuming you used a unique column in the associated data).

Another important feature of `pgsodium` is that the encryption keys are never stored in the database alongside the encrypted data. Instead, only a **Key ID** is stored, which is a reference to the key that is only accessible outside of SQL. Even if an attacker can capture a dump of your entire database, they will see only encrypted data and key IDs, *never the raw key itself*.

This is an important safety precaution - there is little value in storing the encryption key in the database itself as this would be like locking your front door but leaving the key in the lock! Storing the key outside the database fixes this issue.

Where are the keys stored? Supabase creates and manages the root keys (from which all key IDs are derived) in our secured backend systems. We keep this root key safe and separate from your data. You remain in control of your keys - a separate API endpoint is available that you can use to access the key if you want to decrypt your data outside of Supabase.


### Internal details

To encrypt data, you need a *key id*. You can use the default key id created automatically for every project, or create your own key ids Using the `pgsodium.create_key()` function. Key ids are used to internally derive the encryption key used to encrypt secrets in the vault. Vault users typically do not have access to the key itself, only the key id.

Both `vault.create_secret()` and `vault.update_secret()` take an optional fourth `new_key_id` argument. This argument can be used to store a different key id for the secret instead of the default value.

```sql
select vault.create_secret(
  'another_s3kre3t_key', 
  'another_unique_name',
  'This is another description',
  (pgsodium.create_key()).id
);
```

Result:

```sh
-[ RECORD 1 ]-+-------------------------------------
create_secret | cec9e005-a44d-4b19-86e1-febf3cd40619
```

Which roles should have access to the `vault.secrets` table should be carefully considered. There are two ways to grant access, the first is that the `postgres` user can explicitly grant access to the vault table itself.


### Resources

*   Read more about Supabase Vault in the [blog post](https://supabase.com/blog/vault-now-in-beta)
*   [Supabase Vault on GitHub](https://github.com/supabase/vault)
*   [Column Encryption](/docs/guides/database/column-encryption)


# Database Webhooks

Trigger external payloads on database events.

Database Webhooks allow you to send real-time data from your database to another system whenever a table event occurs.

You can hook into three table events: `INSERT`, `UPDATE`, and `DELETE`. All events are fired *after* a database row is changed.


## Webhooks vs triggers

Database Webhooks are very similar to triggers, and that's because Database Webhooks are just a convenience wrapper around triggers using the [pg\_net](/docs/guides/database/extensions/pgnet) extension. This extension is asynchronous, and therefore will not block your database changes for long-running network requests.

This video demonstrates how you can create a new customer in Stripe each time a row is inserted into a `profiles` table:


## Creating a webhook

1.  Create a new [Database Webhook](https://supabase.com/dashboard/project/_/integrations/hooks) in the Dashboard.
2.  Give your Webhook a name.
3.  Select the table you want to hook into.
4.  Select one or more events (table inserts, updates, or deletes) you want to hook into.

Since webhooks are just database triggers, you can also create one from SQL statement directly.

```sql
create trigger "my_webhook" after insert
on "public"."my_table" for each row
execute function "supabase_functions"."http_request"(
  'http://host.docker.internal:3000',
  'POST',
  '{"Content-Type":"application/json"}',
  '{}',
  '1000'
);
```

We currently support HTTP webhooks. These can be sent as `POST` or `GET` requests with a JSON payload.


## Payload

The payload is automatically generated from the underlying table record:

```typescript
type InsertPayload = {
  type: 'INSERT'
  table: string
  schema: string
  record: TableRecord<T>
  old_record: null
}
type UpdatePayload = {
  type: 'UPDATE'
  table: string
  schema: string
  record: TableRecord<T>
  old_record: TableRecord<T>
}
type DeletePayload = {
  type: 'DELETE'
  table: string
  schema: string
  record: null
  old_record: TableRecord<T>
}
```


## Monitoring

Logging history of webhook calls is available under the `net` schema of your database. For more info, see the [GitHub Repo](https://github.com/supabase/pg_net).


## Local development

When using Database Webhooks on your local Supabase instance, you need to be aware that the Postgres database runs inside a Docker container. This means that `localhost` or `127.0.0.1` in your webhook URL will refer to the container itself, not your host machine where your application is running.

To target services running on your host machine, use `host.docker.internal`. If that doesn't work, you may need to use your machine's local IP address instead.

For example, if you want to trigger an edge function when a webhook fires, your webhook URL would be:

    http://host.docker.internal:54321/functions/v1/my-function-name

If you're experiencing connection issues with webhooks locally, verify you're using the correct hostname instead of `localhost`.


## Resources

*   [pg\_net](/docs/guides/database/extensions/pgnet): an async networking extension for Postgres


# Deployment



Deploying your app makes it live and accessible to users. Usually, you will deploy an app to at least two environments: a production environment for users and (one or multiple) staging or preview environments for developers.

Supabase provides several options for environment management and deployment.


## Environment management

You can maintain separate development, staging, and production environments for Supabase:

*   **Development**: Develop with a local Supabase stack using the [Supabase CLI](/docs/guides/local-development).
*   **Staging**: Use [branching](/docs/guides/deployment/branching) to create staging or preview environments. You can use persistent branches for a long-lived staging setup, or ephemeral branches for short-lived previews (which are often tied to a pull request).
*   **Production**: If you have branching enabled, you can use the Supabase GitHub integration to automatically push your migration files when you merge a pull request. Alternatively, you can set up your own continuous deployment pipeline using the Supabase CLI.


## Deployment

You can automate deployments using:

*   The [Supabase GitHub integration](/dashboard/project/_/settings/integrations) (with branching enabled)
*   The [Supabase CLI](/docs/guides/local-development) in your own continuous deployment pipeline
*   The [Supabase Terraform provider](/docs/guides/deployment/terraform)


# Branching

Use Supabase Branches to test and preview changes

Use branching to safely experiment with changes to your Supabase project.

Supabase branches work like Git branches. They let you create and test changes like new configurations, database schemas, or features in a separate, temporary instance without affecting your production setup.

When you're ready to ship your changes, merge your branch to update your production instance with the new changes.

If you understand Git, you already understand Supabase Branching.


## How branching works

*   **Separate Environments**: Each branch is a separate environment with its own Supabase instance and API credentials.
*   **Git Integration**: Branching works with Git, currently supporting GitHub repositories.
*   **Preview Branches**: You can create multiple Preview Branches for testing.
*   **Migrations and Seeding**: Branches run migrations from your repository and can seed data using a `seed.sql` file.


## Prerequisites

*   **Supabase Project**: You need an existing Supabase project.
*   **GitHub Repository**: Your project must be connected to a GitHub repository containing your Supabase directory.

You can run multiple Preview Branches for every Supabase project. Branches contain all the Supabase features with their own API credentials.

Preview Environments auto-pause after  minutes of inactivity. Upon receiving a new request to your database or REST API, the paused branch will automatically resume to serve the request. The implications of this architecture means

*   `pg_cron` jobs will not execute in an auto-paused database.
*   Larger variance in request latency due to database cold starts.

If you need higher performance guarantees on your Preview Environment, you can switch individual branches to [persistent](/docs/guides/deployment/branching#persistent-branches) so they are not auto-paused.


### Branching workflow

Preview Branch instances contain no data by default. You must include a seed file to seed your preview instance with sample data when the Preview Branch is created. Future versions of Branching may allow for automated data seeding and cloning after we are confident that we can provide safe data masking.


## Git providers

To manage code changes, your Supabase project must be connected to a Git repository. At this stage, we only support [GitHub](#branching-with-github). If you are interested in other Git providers, join the [discussion](https://github.com/orgs/supabase/discussions/18936) for GitLab, Bitbucket, and non-Git based Branching.


### Branching with GitHub

Supabase Branching uses the Supabase GitHub integration to read files from your GitHub repository. With this integration, Supabase watches all commits, branches, and pull requests of your GitHub repository.

You can create a corresponding Preview Branch for any Git branch in your repository. Each time a new Preview Branch is created and configured based on the [`config.toml`](/docs/guides/local-development/cli/config) configuration on this branch, the migrations from the corresponding Git branch are run on the Preview Branch.

The Preview Branch is also [seeded](/docs/guides/local-development/seeding-your-database) with sample data based on `./supabase/seed.sql` by default, if that file exists.

Supabase Branching follows the [Trunk Based Development](https://trunkbaseddevelopment.com/) workflow, with one main Production branch and multiple development branches:

When you merge your Git branch into the production branch, all new migrations will be applied to your Production environment. If you have declared Storage buckets or Edge Functions in `config.toml`, they will also be deployed automatically. All other configurations, including API, Auth, and seed files, will be ignored by default.


### Preparing your Git repository

You can use the [Supabase CLI](/docs/guides/cli) to manage changes inside a local `./supabase` directory:


### Enable Supabase branching

Once your repository is [correctly prepared](#preparing-your-git-repository), you can enable branching from the Supabase dashboard.


### Open a pull request

When you open a pull request on GitHub, the Supabase integration automatically checks for a matching preview branch. If one doesn't exist, it gets created.

A comment is added to your PR with the deployment status of your preview branch. Statuses are shown separately for Database, Services, and APIs.

Every time a new commit is pushed that changes the migration files in `./supabase/migrations`, the new migrations are run against the preview branch. You can check the status of these runs in the comment's Tasks table.


### Preventing migration failures

We highly recommend turning on a 'required check' for the Supabase integration. You can do this from your GitHub repository settings. This prevents PRs from being merged when migration checks fail, and stops invalid migrations from being merged into your production branch.


### Manually create a preview branch

Preview branches are automatically created for each pull request, but you can also manually create one.

The Git integration watches for changes in the `supabase` directory. This includes:

*   All SQL migration files, under the subdirectory `migrations`
*   An optional `seed.sql` file, used to seed preview instances with sample data

You can create new migrations either [locally](#develop-locally) or [remotely](#develop-remotely). Local development is recommended.


### Disable branching

You can disable branching at any time. Navigate to the [Branches](/dashboard/project/_/branches) page, which can be found via the Branches dropdown menu on the top navigation, then click "Manage Branches" in the menu. Click the 'Disable branching' button at the top of the Overview section.


### Persistent branches

Persistent branches are the type of branches that will remain active even after the underlying PR is closed.
You can change any branch to be persistent on the [Branches](/dashboard/project/_/branches) page by clicking the triple dots icon next to the branch you want to modify, and selecting "Switch to persistent".
All persistent branches can be toggled back to be an ephemeral branch in the exact same way.


## Migration and seeding behavior

Migrations are run in sequential order. Each migration builds upon the previous one.

The preview branch has a record of which migrations have been applied, and only applies new migrations for each commit. This can create an issue when rolling back migrations.


### Using ORM or custom seed scripts

If you want to use your own ORM for managing migrations and seed scripts, you will need to run them in GitHub Actions after the preview branch is ready. The branch credentials can be fetched using the following example GHA workflow.

```yaml
on:
  pull_request:
    types:
      - opened
      - reopened
      - synchronize
    branches:
      - main
    paths:
      - 'supabase/**'

jobs:
  wait:
    runs-on: ubuntu-latest
    outputs:
      status: ${{ steps.check.outputs.conclusion }}
    steps:
      - uses: fountainhead/action-wait-for-check@v1.2.0
        id: check
        with:
          checkName: Supabase Preview
          ref: ${{ github.event.pull_request.head.sha }}
          token: ${{ secrets.GITHUB_TOKEN }}

  migrate:
    needs:
      - wait
    if: ${{ needs.wait.outputs.status == 'success' }}
    runs-on: ubuntu-latest
    steps:
      - uses: supabase/setup-cli@v1
        with:
          version: latest
      - run: supabase --experimental branches get "$GITHUB_HEAD_REF" -o env >> $GITHUB_ENV
      - name: Custom ORM migration
        run: psql "$POSTGRES_URL_NON_POOLING" -c 'select 1'
```


## Branch configuration with remotes

When Branching is enabled, your `config.toml` settings automatically sync to all ephemeral branches through a one-to-one mapping between your Git and Supabase branches.


### Basic configuration

To update configuration for a Supabase branch, modify `config.toml` and push to git. The Supabase integration will detect the changes and apply them to the corresponding branch.


### Remote-specific configuration

For persistent branches that need specific settings, you can use the `[remotes]` block in your `config.toml`. Each remote configuration must reference an existing project ID.

Here's an example of configuring a separate seed script for a staging environment:

```toml
[remotes.staging]
project_id = "your-project-ref"

[remotes.staging.db.seed]
sql_paths = ["./seeds/staging.sql"]
```

Since the `project_id` field must reference an existing branch, you need to create the persistent branch before adding its configuration. Use the CLI to create a persistent branch first:

```bash
supabase --experimental branches create --persistent
# Do you want to create a branch named develop? [Y/n]
```


### Configuration merging

When merging a PR into a persistent branch, the Supabase integration:

1.  Checks for configuration changes
2.  Logs the changes
3.  Applies them to the target remote

If no remote is declared or the project ID is incorrect, the configuration step is skipped.


### Available configuration options

All standard configuration options are available in the `[remotes]` block. This includes:

*   Database settings
*   API configurations
*   Authentication settings
*   Edge Functions configuration
*   And more

You can use this to maintain different configurations for different environments while keeping them all in version control.


### Rolling back migrations

You might want to roll back changes you've made in an earlier migration change. For example, you may have pushed a migration file containing schema changes you no longer want.

To fix this, push your latest changes, then delete the preview branch in Supabase and reopen it.

The new preview branch is reseeded from your `./supabase/seed.sql` file by default. Any additional data changes you made on the old preview branch are lost. This is equivalent to running `supabase db reset` locally. All migrations are rerun in sequential order.


### Seeding behavior

Your Preview Branches are seeded with sample data using the same as [local seeding behavior](/docs/guides/local-development/seeding-your-database).

The database is only seeded once, when the preview branch is created. To rerun seeding, delete the preview branch and recreate it by closing, and reopening your pull request.


## Branching and hosting providers

Branching works with hosting providers that support preview deployments.

With the Supabase branching integration, you can sync the Git branch used by the hosting provider with the corresponding Supabase preview branch. This means that the preview deployment built by your hosting provider is matched to the correct database schema, edge functions, and other Supabase configurations.


### Vercel

Install the Vercel integration:

*   From the [Vercel marketplace](https://vercel.com/integrations/supabase) or
*   By clicking the blue `Deploy` button in a Supabase example app's `README` file

And make sure you have [connected](/dashboard/org/_/integrations) your Supabase project to your Vercel project.

Supabase automatically updates your Vercel project with the correct environment variables for the corresponding preview branches. The synchronization happens at the time of Pull Request being opened, not at the time of branch creation.

As branching integration is tied to the Preview Deployments feature in Vercel, there are possible race conditions between Supabase setting correct variables, and Vercel running a deployment process. Because of that, Supabase is always automatically re-deploying the most recent deployment of the given pull request.


## Other Git providers

There are multiple alternative Git providers under consideration. If you're interested in branching for GitLab, Bitbucket, or some other provider, [join the GitHub discussion](https://github.com/orgs/supabase/discussions/18938).


## Alternatives to branching

Under the hood, you can see Supabase branching as a way to programmatically "duplicate" your Supabase project via git flow. This allows spawning a new configured (via [`config.toml`](/docs/guides/local-development/cli/config)) and seeded instance of the database and the adjacent Supabase services (buckets, edge functions, etc.).

1.  A new project is deployed on behalf of the user on the Supabase side as the new "branch" if it doesn't already exist. This includes the database, storage, edge-function, and all Supabase-related services.
2.  The branch is cloned and the new project is configured based on the [`config.toml`](/docs/guides/local-development/cli/config) committed into this project branch.
3.  Migrations are applied and seeding scripts are run (the first time) for this branch.

You can make a similar setup with a distinct project for each environment. Or just have two environments, the localhost and the production one.


## Pricing

Branching is available on the Pro Plan and above. The price is:

*   Each Preview branch costs $0.32 per day
*   Each Preview branch is billed until it is removed


## Troubleshooting


### Rolling back migrations

You might want to roll back changes you've made in an earlier migration change. For example, you may have pushed a migration file containing schema changes you no longer want.

To fix this, push the latest changes, then delete the preview branch in Supabase and reopen it.

The new preview branch is reseeded from the `./supabase/seed.sql` file by default. Any additional data changes made on the old preview branch are lost. This is equivalent to running `supabase db reset` locally. All migrations are rerun in sequential order.


### Deployment failures

A deployment might fail for various reasons, including invalid SQL statements and schema conflicts in migrations, errors within the `config.toml` config, or something else.

To check the error message, see the Supabase workflow run for your branch under the [View logs](/dashboard/project/_/branches) section.


### Network restrictions

If you enable [network restrictions](/docs/guides/platform/network-restrictions) on your project, the branching cluster will be blocked from connecting to your project by default. This often results in database connection failures when migrating your production project after merging a development branch.

The workaround is to explicitly allow the IPv6 CIDR range of the branching cluster in your project's [database settings](https://supabase.com/dashboard/project/_/settings/database) page: `2600:1f18:2b7d:f600::/56`


### Schema drift between preview branches

If multiple preview branches exist, each preview branch might contain different schema changes. This is similar to Git branches, where each branch might contain different code changes.

When a preview branch is merged into the production branch, it creates a schema drift between the production branch and the preview branches that haven't been merged yet.

These conflicts can be resolved in the same way as normal Git Conflicts: merge or rebase from the production Git branch to the preview Git branch. Since migrations are applied sequentially, ensure that migration files are timestamped correctly after the rebase. Changes that build on top of earlier changes should always have later timestamps.


### Changing production branch

It's not possible to change the Git branch used as the Production branch for Supabase Branching. The only way to change it is to disable and re-enable branching. See [Disable Branching](#disable-branching).


## Feedback

Supabase branching is a new and exciting part of the Supabase development ecosystem. Feedback is welcome.

You can join the [conversation over in GitHub discussions](https://github.com/orgs/supabase/discussions/18937).


# Database Migrations

How to manage schema migrations for your Supabase project.

Database migrations are SQL statements that create, update, or delete your existing database schemas. They are a common way of tracking changes to your database over time.


## Schema migrations

For this guide, we'll create a table called `employees` and see how we can make changes to it.

You will need to [install](/docs/guides/local-development#quickstart) the Supabase CLI and start the local development stack.

Finally, you should see the `department` column added to your `employees` table in the local Dashboard.


### Seeding data

Now that you are managing your database with migrations scripts, it would be great have some seed data to use every time you reset the database.

You should now see the `employees` table, along with your seed data in the Dashboard! All of your database changes are captured in code, and you can reset to a known state at any time, complete with seed data.


### Diffing changes

This workflow is great if you know SQL and are comfortable creating tables and columns. If not, you can still use the Dashboard to create tables and columns, and then use the CLI to diff your changes and create migrations.

The last step is deploying these changes to a live Supabase project.


## Deploy your project

You've been developing your project locally, making changes to your tables via migrations. It's time to deploy your project to the Supabase Platform and start scaling up to millions of users!

Head over to [Supabase](https://supabase.com/dashboard) and create a new project to deploy to.

Visiting your live project on [Supabase](https://supabase.com/dashboard/project/_), you'll see a new `employees` table, complete with the `department` column you added in the second migration above.


# Production Checklist



After developing your project and deciding it's Production Ready, you should run through this checklist to ensure that your project:

*   is secure
*   won't falter under the expected load
*   remains available whilst in production


## Security

*   Ensure RLS is enabled
    *   Tables that do not have RLS enabled with reasonable policies allow any client to access and modify their data. This is unlikely to be what you want in the majority of cases.
    *   [Learn more about RLS](/docs/guides/database/postgres/row-level-security).
*   Enable replication on tables containing sensitive data by enabling Row Level Security (RLS) and setting row security policies:
    *   Go to the Authentication > Policies page in the Supabase Dashboard to enable RLS and create security policies.
    *   Go to the Database > Publications page in the Supabase Dashboard to manage replication tables.
*   Turn on [SSL Enforcement](/docs/guides/platform/ssl-enforcement)
*   Enable [Network Restrictions](/docs/guides/platform/network-restrictions) for your database.
*   Ensure that your Supabase Account is protected with multi-factor authentication (MFA).
    *   If using a GitHub signin, [enable 2FA on GitHub](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication). Since your GitHub account gives you administrative rights to your Supabase org, you should protect it with a strong password and 2FA using a U2F key or a TOTP app.
    *   If using email+password signin, set up [MFA for your Supabase account](https://supabase.com/docs/guides/platform/multi-factor-authentication#enable-mfa).
*   Consider [adding multiple owners on your Supabase org](https://supabase.com/dashboard/org/_/team). This ensures that if one of the owners is unreachable or loses access to their account, you still have Owner access to your org.
*   Ensure email confirmations are [enabled](https://supabase.com/dashboard/project/_/auth/providers) in the `Settings > Auth` page.
*   Ensure that you've [set the expiry](https://supabase.com/dashboard/project/_/auth/providers) for one-time passwords (OTPs) to a reasonable value that you are comfortable with. We recommend setting this to 3600 seconds (1 hour) or lower.
*   Increase the length of the OTP if you need a higher level of entropy.
*   If your application requires a higher level of security, consider setting up [multi-factor authentication](https://supabase.com/docs/guides/auth/auth-mfa) (MFA) for your users.
*   Use a custom SMTP server for auth emails so that your users can see that the mails are coming from a trusted domain (preferably the same domain that your app is hosted on). Grab SMTP credentials from any major email provider such as SendGrid, AWS SES, etc.
*   Think hard about how *you* would abuse your service as an attacker, and mitigate.
*   Review these [common cybersecurity threats](https://auth0.com/docs/security/prevent-threats).
*   Check and review issues in your database using [Security Advisor](https://supabase.com/dashboard/project/_/database/security-advisor).


## Performance

*   Ensure that you have suitable indices to cater to your common query patterns
    *   [Learn more about indexes in Postgres](https://www.enterprisedb.com/postgres-tutorials/overview-postgresql-indexes).
    *   `pg_stat_statements` can help you [identify hot or slow queries](https://www.virtual-dba.com/blog/postgresql-performance-identifying-hot-and-slow-queries/).
*   Perform load testing (preferably on a staging env)
    *   Tools like [k6](https://k6.io/) can simulate traffic from many different users.
*   Upgrade your database if you require more resources. If you need anything beyond what is listed, contact enterprise@supabase.io.
*   If you are expecting a surge in traffic (for a big launch) and are on a Team or Enterprise Plan, [contact support](https://supabase.com/dashboard/support/new) with more details about your launch and we'll help keep an eye on your project.
*   If you expect your database size to be > 4 GB, [enable](https://supabase.com/dashboard/project/_/settings/addons?panel=pitr) the Point in Time Recovery (PITR) add-on. Daily backups can take up resources from your database when the backup is in progress. PITR is more resource efficient, since only the changes to the database are backed up.
*   Check and review issues in your database using [Performance Advisor](https://supabase.com/dashboard/project/_/database/performance-advisor).


## Availability

*   Use your own SMTP credentials so that you have full control over the deliverability of your transactional auth emails (see Settings > Auth)
    *   you can grab SMTP credentials from any major email provider such as SendGrid, AWS SES, etc. You can refer to our [SMTP guide](/docs/guides/auth/auth-smtp) for more details.
    *   The default rate limit for auth emails when using a custom SMTP provider is 30 new users per hour, if doing a major public announcement you will likely require more than this.
*   Applications on the Free Plan that exhibit extremely low activity in a 7 day period may be paused by Supabase to save on server resources.
    *   You can restore paused projects from the Supabase dashboard.
    *   Upgrade to Pro to guarantee that your project will not be paused for inactivity.
*   Database backups are not available for download on the Free Plan.
    *   You can set up your own backup systems using tools like [pg\_dump](https://www.postgresqltutorial.com/postgresql-backup-database/) or [wal-g](https://github.com/wal-g/wal-g).
    *   Nightly backups for Pro Plan projects are available on the Supabase dashboard for up to 7 days.
    *   Point in Time Recovery (PITR) allows a project to be backed up at much shorter intervals. This provides users an option to restore to any chosen point of up to seconds in granularity. In terms of Recovery Point Objective (RPO), Daily Backups would be suitable for projects willing to lose up to 24 hours worth of data. If a lower RPO is required, enable PITR.
*   Supabase Projects use disks that offer 99.8-99.9% durability by default.
    *   Use Read Replicas if you require availability resilience to a disk failure event
    *   Use PITR if you require durability resilience to a disk failure event
*   Upgrading to the Supabase Pro Plan will give you [access to our support team](https://supabase.com/dashboard/support/new).


## Rate limiting, resource allocation, & abuse prevention

*   Supabase employs a number of safeguards against bursts of incoming traffic to prevent abuse and help maximize stability across the platform
    *   If you're on a Team or Enterprise Plan and expect high load events, such as production launches, heavy load testing, or prolonged high resource usage, open a ticket via the [support form](https://supabase.help) for help. Provide at least 2 weeks notice.


### Auth rate limits

*   The table below shows the rate limit quotas on the following authentication endpoints. You can configure the auth rate limits for your project [here](/dashboard/project/_/auth/rate-limits).

| Endpoint                                         | Path                                                           | Limited By               | Rate Limit                                                                                                                                                                                                                                     |
| ------------------------------------------------ | -------------------------------------------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| All endpoints that send emails                   | `/auth/v1/signup` `/auth/v1/recover` `/auth/v1/user`\[^1]       | Sum of combined requests | As of 3 Sep 2024, this has been updated to  emails per hour. You can only change this with your own [custom SMTP setup](/docs/guides/auth/auth-smtp). |
| All endpoints that send One-Time-Passwords (OTP) | `/auth/v1/otp`                                                 | Sum of combined requests | Defaults to 360 OTPs per hour. Is customizable.                                                                                                                                                                                                |
| Send OTPs or magic links                         | `/auth/v1/otp`                                                 | Last request             | Defaults to 60 seconds window before a new request is allowed. Is customizable.                                                                                                                                                                |
| Signup confirmation request                      | `/auth/v1/signup`                                              | Last request             | Defaults to 60 seconds window before a new request is allowed. Is customizable.                                                                                                                                                                |
| Password Reset Request                           | `/auth/v1/recover`                                             | Last request             | Defaults to 60 seconds window before a new request is allowed. Is customizable.                                                                                                                                                                |
| Verification requests                            | `/auth/v1/verify`                                              | IP Address               | 360 requests per hour (with bursts up to 30 requests)                                                                                                                                                                                          |
| Token refresh requests                           | `/auth/v1/token`                                               | IP Address               | 1800 requests per hour (with bursts up to 30 requests)                                                                                                                                                                                         |
| Create or Verify an MFA challenge                | `/auth/v1/factors/:id/challenge` `/auth/v1/factors/:id/verify` | IP Address               | 15 requests per minute (with bursts up to 30 requests)                                                                                                                                                                                         |
| Anonymous sign-ins                               | `/auth/v1/signup`\[^2]                                          | IP Address               | 30 requests per hour (with bursts up to 30 requests)                                                                                                                                                                                           |


### Realtime quotas

*   Review the [Realtime quotas](/docs/guides/realtime/quotas).
*   If you need quotas increased you can always [contact support](https://supabase.com/dashboard/support/new).


### Abuse prevention

*   Supabase provides CAPTCHA protection on the signup, sign-in and password reset endpoints. Refer to [our guide](/docs/guides/auth/auth-captcha) on how to protect against abuse using this method.


### Email link validity

*   When working with enterprise systems, email scanners may scan and make a `GET` request to the reset password link or sign up link in your email. Since links in Supabase Auth are single use, a user who opens an email post-scan to click on a link will receive an error. To get around this problem,
    consider altering the email template to replace the original magic link with a link to a domain you control. The domain can present the user with a "Sign-in" button which redirect the user to the original magic link URL when clicked.

*   When using a custom SMTP service, some services might have link tracking enabled which may overwrite or disform the email confirmation links sent by Supabase Auth. To prevent this from happening, we recommend that you disable link tracking when using a custom SMTP service.


## Subscribe to Supabase status page

Stay informed about Supabase service status by subscribing to the [Status Page](https://status.supabase.com/). We recommend setting up Slack notifications through an RSS feed to ensure your team receives timely updates about service status changes.


### Setting up Slack notifications

1.  Install the RSS app in Slack:

    *   Visit the [RSS app page](https://slack.com/marketplace/A0F81R7U7-rss) in the Slack marketplace
    *   Click `Add to Slack` if not already installed
    *   Otherwise you will get straight to next step, no need to reinstall the app

2.  Configure the Supabase status feed:

    *   Create a channel (e.g., `#supabase-status-alerts`) for status updates
    *   On the [RSS app page](https://slack.com/marketplace/A0F81R7U7-rss) go to *Add a Feed* section and set Feed URL to `https://status.supabase.com/history.rss`
    *   Select your designated channel and click "Subscribe to this feed"

Once configured, your team will receive automatic notifications in Slack whenever the Supabase Status Page is updated.

For detailed setup instructions, see the [Add RSS feeds to Slack](https://slack.com/intl/en-nz/help/articles/218688467-Add-RSS-feeds-to-Slack).


## Next steps

This checklist is always growing so be sure to check back frequently, and also feel free to suggest additions and amendments by making a PR on [GitHub](https://github.com/supabase/supabase).


# Managing Environments

Manage multiple environments using Database Migrations and GitHub Actions.

This guide shows you how to set up your local Supabase development environment that integrates with GitHub Actions to automatically test and release schema changes to staging and production Supabase projects.


## Set up a local environment

The first step is to set up your local repository with the Supabase CLI:

```bash
supabase init
```

You should see a new `supabase` directory. Then you need to link your local repository with your Supabase project:

```bash
supabase login
supabase link --project-ref $PROJECT_ID
```

You can get your `$PROJECT_ID` from your project's dashboard URL:

    https://supabase.com/dashboard/project/<project-id>

If you're using an existing Supabase project, you might have made schema changes through the Dashboard.
Run the following command to pull these changes before making local schema changes from the CLI:

```sql
supabase db pull
```

This command creates a new migration in `supabase/migrations/<timestamp>_remote_schema.sql` which reflects the schema changes you have made previously.

Now commit your local changes to Git and run the local development setup:

```bash
git add .
git commit -m "init supabase"
supabase start
```

You are now ready to develop schema changes locally and create your first migration.


## Create a new migration

There are two ways to make schema changes:

1.  Manual migration: Write DDL statements manually into a migration file
2.  Auto schema diff: Make changes through Studio UI and auto generate a schema diff


### Manual migration

Create a new migration script by running:

```bash
supabase migration new new_employee
```

You should see a new file created: `supabase/migrations/<timestamp>_new_employee.sql`. You can then write SQL statements in this script using a text editor:

```sql
create table public.employees (
  id integer primary key generated always as identity,
  name text
);
```

Apply the new migration to your local database:

```bash
supabase db reset
```

This command recreates your local database from scratch and applies all migration scripts under `supabase/migrations` directory. Now your local database is up to date.


### Auto schema diff

Unlike manual migrations, auto schema diff creates a new migration script from changes **already** applied to your local database.

Create an `employees` table under the `public` schema using Studio UI, accessible at [localhost:54323](http://localhost:54323/) by default.

Next, generate a schema diff by running the following command:

```bash
supabase db diff -f new_employee
```

You should see that a new file `supabase/migrations/<timestamp>_new_employee.sql` is created. Open the file and verify that the generated DDL statements are the same as below.

```sql
-- This script was generated by the Schema Diff utility in pgAdmin 4
-- For the circular dependencies, the order in which Schema Diff writes the objects is not very sophisticated
-- and may require manual changes to the script to ensure changes are applied in the correct order.
-- Please report an issue for any failure with the reproduction steps.

CREATE TABLE IF NOT EXISTS public.employees
(
    id integer NOT NULL GENERATED ALWAYS AS IDENTITY ( INCREMENT 1 START 1 MINVALUE 1 MAXVALUE 2147483647 CACHE 1 ),
    name text COLLATE pg_catalog."default",
    CONSTRAINT employees_pkey PRIMARY KEY (id)
)

TABLESPACE pg_default;

ALTER TABLE IF EXISTS public.employees
    OWNER to postgres;

GRANT ALL ON TABLE public.employees TO anon;

GRANT ALL ON TABLE public.employees TO authenticated;

GRANT ALL ON TABLE public.employees TO postgres;

GRANT ALL ON TABLE public.employees TO service_role;
```

You may notice that the auto-generated migration script is more verbose than the manually written one.
This is because the default schema diff tool does not account for default privileges added by the initial schema.

Commit the new migration script to git and you are ready to deploy.


## Deploy a migration

In a production environment, we recommend using a CI/CD pipeline to deploy new migrations with GitHub Actions rather than deploying from your local machine.

This example uses two Supabase projects, one for production and one for staging.

Prepare your environments by:

*   Creating separate Supabase projects for staging and production
*   Pushing your git repository to GitHub and enabling GitHub Actions


### Configure GitHub Actions

The Supabase CLI requires a few environment variables to run in non-interactive mode.

*   `SUPABASE_ACCESS_TOKEN` is your personal access token
*   `SUPABASE_DB_PASSWORD` is your project specific database password
*   `SUPABASE_PROJECT_ID` is your project specific reference string

We recommend adding these as [encrypted secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets) to your GitHub Actions runners.

Create the following files inside the `.github/workflows` directory:

The full example code is available in the [demo repository](https://github.com/supabase/supabase-action-example).

Commit these files to git and push to your `main` branch on GitHub. Update these environment variables to match your Supabase projects:

*   `SUPABASE_ACCESS_TOKEN`
*   `PRODUCTION_PROJECT_ID`
*   `PRODUCTION_DB_PASSWORD`
*   `STAGING_PROJECT_ID`
*   `STAGING_DB_PASSWORD`

When configured correctly, your repository will have CI and Release workflows that trigger on new commits pushed to `main` and `develop` branches.

![Correctly configured repo](/docs/img/guides/cli/ci-main.png)


### Open a PR with new migration

Follow the [migration steps](#create-a-new-migration) to create a `supabase/migrations/<timestamp>_new_employee.sql` file.

Checkout a new branch `feat/employee` from `develop` , commit the migration file, and push to GitHub.

```bash
git checkout -b feat/employee
git add supabase/migrations/<timestamp>_new_employee.sql
git commit -m "Add employee table"
git push --set-upstream origin feat/employee
```

Open a PR from `feat/employee` to the `develop` branch to see that the CI workflow has been triggered.

Once the test error is resolved, merge this PR and watch the deployment in action.


### Release to production

After verifying your staging project has successfully migrated, create another PR from `develop` to `main` and merge it to deploy the migration to the production project.

The `release` job applies all new migration scripts merged in `supabase/migrations` directory to a linked Supabase project. You can control which project the job links to via `PROJECT_ID` environment variable.


## Troubleshooting


### Sync production project to staging

When setting up a new staging project, you might need to sync the initial schema with migrations previously applied to the production project.

One way is to leverage the Release workflow:

*   Create a new branch `develop` and choose `main` as the branch source
*   Push the `develop` branch to GitHub

The GitHub Actions runner will deploy your existing migrations to the staging project.

Alternatively, you can also apply migrations through your local CLI to a linked remote database.

```sql
supabase db push
```

Once pushed, check that the migration version is up to date for both local and remote databases.

```sql
supabase migration list
```


### Permission denied on `db pull`

If you have been using Supabase hosted projects for a long time, you might encounter the following permission error when executing `db pull`.

```bash
Error: Error running pg_dump on remote database: pg_dump: error: query failed: ERROR:  permission denied for table _type

pg_dump: error: query was: LOCK TABLE "graphql"."_type" IN ACCESS SHARE MODE
```

To resolve this error, you need to grant `postgres` role permissions to `graphql` schema. You can do that by running the following query from Supabase dashboard's SQL Editor.

```sql
grant all on all tables in schema graphql to postgres, anon, authenticated, service_role;
grant all on all functions in schema graphql to postgres, anon, authenticated, service_role;
grant all on all sequences in schema graphql to postgres, anon, authenticated, service_role;
```


### Permission denied on `db push`

If you created a table through Supabase dashboard, and your new migration script contains `ALTER TABLE` statements, you might run into permission error when applying them on staging or production databases.

```bash
ERROR: must be owner of table employees (SQLSTATE 42501); while executing migration <timestamp>
```

This is because tables created through Supabase dashboard are owned by `supabase_admin` role while the migration scripts executed through CLI are under `postgres` role.

One way to solve this is to reassign the owner of those tables to `postgres` role. For example, if your table is named `users` in the public schema, you can run the following command to reassign owner.

```sql
ALTER TABLE users OWNER TO postgres;
```

Apart from tables, you also need to reassign owner of other entities using their respective commands, including [types](https://www.postgresql.org/docs/current/sql-altertype.html), [functions](https://www.postgresql.org/docs/current/sql-alterroutine.html), and [schemas](https://www.postgresql.org/docs/current/sql-alterschema.html).


### Rebasing new migrations

Sometimes your teammate may merge a new migration file to git main branch, and now you need to rebase your local schema changes on top.

We can handle this scenario gracefully by renaming your old migration file with a new timestamp.

```bash
git pull
supabase migration new dev_A
# Assume the new file is: supabase/migrations/<t+2>_dev_A.sql
mv <time>_dev_A.sql <t+2>_dev_A.sql
supabase db reset
```

In case [`reset`](/docs/reference/cli/usage#supabase-db-reset) fails, you can manually resolve conflicts by editing `<t+2>_dev_A.sql` file.

Once validated locally, commit your changes to Git and push to GitHub.


# Maturity Model



Supabase is great for building something very fast *and* for scaling up. However, it's important to note that as your application matures and your team expands, the practices you use for managing an application in production should not be the same as the practices you used for prototyping.


## Prototyping

The Dashboard is a quick and easy tool for building applications while you are prototyping. That said, we strongly recommend using [Migrations](/docs/guides/deployment/database-migrations) to manage your database changes. You can use our CLI to [capture any changes](/docs/reference/cli/supabase-db-diff) you have made on the Dashboard so that you can commit them a version control system, like git.


## Collaborating

As soon as you start collaborating with team members, all project changes should be in version control. At this point we strongly recommend moving away from using the Dashboard for schema changes. Use migrations to manage your database, and check them into your version control system to track every change.

Resources:

*   [Database migrations](/docs/guides/deployment/database-migrations)
*   [Managing access on the Dashboard](/docs/guides/platform/access-control)
*   [PGAudit for Postgres](/docs/guides/database/extensions/pgaudit)


## In production

Once your application is live, you should never change your database using the Dashboard - everything should be done with [Migrations](/docs/guides/cli/managing-environments#create-a-new-migration). Some other important things to consider at this point include:

*   The Dashboard has various [access levels](/docs/guides/platform/access-control) that can prevent changes being made via the UI.
*   Design a [safe workflow](/docs/guides/platform/shared-responsibility-model#you-decide-your-own-workflow) for managing your database. We strongly recommend running [multiple environments](/docs/guides/cli/managing-environments) as part of your development workflow (`local` -> `staging` -> `prod`).
*   Do not share any production passwords with your team, *especially* your `postgres` password. All changes should be made via version-controlled migrations which run via a bastion host or a CI platform (like [GitHub Actions](/docs/guides/cli/managing-environments#configure-github-actions). If you use GitHub Actions, use [approval workflows](https://docs.github.com/en/actions/managing-workflow-runs/reviewing-deployments) to prevent any migrations being run accidentally.
*   Restrict production access to your database using [Network Restrictions](/docs/guides/platform/network-restrictions).
*   As your database to grows, we strongly recommend moving to [Point-in-Time Recovery](/docs/guides/platform/backups#point-in-time-recovery). This is safer and has less impact on your database performance during maintenance windows.
*   Read the [Production Checklist](/docs/guides/platform/going-into-prod) and familiarize your team with the [Shared Responsibilities](/docs/guides/platform/shared-responsibility-model) between your organization and Supabase.

Resources:

*   [Database migrations](/docs/guides/deployment/database-migrations)
*   [Managing access on the Dashboard](/docs/guides/platform/access-control)
*   [PGAudit for Postgres](/docs/guides/database/extensions/pgaudit)
*   [Managing environments](/docs/guides/cli/managing-environments)


## Enterprise

For a more secure setup, consider running your workload across several organizations. It's a common pattern to have a Production organization which is restricted to only those team members who are qualified to have direct access to production databases.

Reach out to [growth](https://forms.supabase.com/enterprise) if you need help designing a secure development workflow for your organization.


# Shared Responsibility Model



Running databases is a shared responsibility between you and Supabase. There are some things that we can take care of for you, and some things that you are responsible for. This is by design: we want to give you the freedom to use your database however you want. While we *could* put many more restrictions in place to ensure that you can’t do anything wrong, you will eventually find those restrictions prohibitive.

To summarize, you are always responsible for:

*   Your Supabase account
*   Access management (Supabase account, database, tables, etc)
*   Data
*   Applying security controls

Generally, we aim to reduce your burden of managing infrastructure and knowing about Postgres internals, minimizing configuration as much as we can. Here are a few things that you should know:


## You share the security responsibility

We give you full access to the database. If you share that access with other people (either people on your team, or the public in general) then it is your responsibility to ensure that the access levels you provide are correctly managed.

If you have an inexperienced member on your team, then you probably shouldn’t give them access to Production. You should set internal workflows around what they should and should not be able to do, with restricted access to avoid anything that might be deemed dangerous.

You are also responsible for ensuring that tables with sensitive data have the right level of access. You are also responsible for managing your database secrets and API keys, storing them safely in an encrypted store.

Supabase provides controls for [securing your data](/docs/guides/database/secure-data), and it is recommended that you always apply [Row Level Security](/docs/guides/database/postgres/row-level-security) (RLS).

We will also provide you with security alerts through [Security Advisor](https://supabase.com/dashboard/project/_/database/security-advisor) and applying the recommendations are your responsibility.


## You decide your own workflow

There are *many* ways to work with Supabase.

You can use our Dashboard, our client libraries, external tools like Prisma and Drizzle, or migration tools like our CLI, Flyway, Sqitch, and anything else that is Postgres-compatible. You can develop directly on your database while you're getting started, run migrations from [local to production](/docs/guides/getting-started/local-development), or you can use [multiple environments](/docs/guides/cli/managing-environments).

None of these are right or wrong. It depends on the stage of your project. You *definitely* shouldn’t be developing on your database directly when you’re in production - but that’s absolutely fine when you’re prototyping and don’t have users.


## You are responsible for your application architecture

Supabase isn't a silver-bullet for bad architectural decisions. A poorly designed database will run poorly, no matter where it’s hosted.

You can get away with a poorly-designed database for a while by adding compute. After a while, things will start to break. The database schema is the area you want to spend *the most* time thinking about. That’s the benefit of Supabase - you can spend more time designing a scalable database system and less time thinking about the mundane tasks like implementing CRUD APIs.

If you don’t want to implement logic inside your database, that is 100% fine. You can use *any* tools which work with Postgres.


## You are responsible for third-party services

Supabase offers a lot of opportunities for flexibly integrating with third-party services, such as:

*   OAuth and SAML login providers
*   SMTP and SMS sending APIs
*   Calls to external APIs within Postgres functions or triggers
*   Calls to external APIs within Edge Functions

You are free to use and integrate with any service, but you're also responsible for ensuring that the performance, availability, and security of the services you use match up with your application's requirements. We do not monitor for outages or performance issues within integrations with third-party services. Depending on the implementation, an issue with such an integration could also result in performance degradation or an outage for your Supabase project.

If your application architecture relies on such integrations, you should monitor the relevant logs and metrics to ensure optimal performance.


## You choose your level of comfort with Postgres

Our goal at Supabase is to make *all* of Postgres easy to use. That doesn’t mean you have to use all of it. If you’re a Postgres veteran, you’ll probably love the tools that we offer. If you’ve never used Postgres before, then start smaller and grow into it. If you just want to treat Postgres like a simple table-store, that’s perfectly fine.


## You are in control of your database

Supabase places very few guard-rails around your database. That gives you a lot of control, but it also means you can break things. ”Break” is used liberally here. It refers to any situation that affects your application because of the way you're using the database.

You are responsible for using best-practices to optimize and manage your database: adding indexes, adding filters on large queries, using caching strategies, optimizing your database queries, and managing connections to the database.

You are responsible of provisioning enough compute to run the workload that your application requires. The Supabase Dashboard provides [observability tooling](https://supabase.com/dashboard/project/_/reports/database) to help with this.


## Before going to production

We recommend reviewing and applying the recommendations offered in our [Production Checklist](/docs/guides/platform/going-into-prod). This checklist covers the responsibilities discussed here and a few additional general production readiness best practices.


## SOC 2 and compliance

Supabase provides a SOC 2 compliant environment for hosting and managing sensitive data. We recommend reviewing the [SOC 2 compliance responsibilities document](/docs/guides/security/soc-2-compliance) alongside the aforementioned production checklist.


## Managing healthcare data

You can use Supabase to store and process Protected Health Information (PHI). You are responsible for the following

*   Signing a Business Associate Agreement (BAA) with Supabase. Submit a [HIPAA add-on request](https://forms.supabase.com/hipaa2) to get started. You will need to be at least on the [Team Plan](https://supabase.com/pricing) to sign a BAA with us.
*   [Marking specific projects as HIPAA projects](/docs/guides/platform/hipaa-projects) and addressing security issues raised by the advisor.
*   Ensuring [MFA is enabled](/docs/guides/platform/multi-factor-authentication) on all Supabase accounts.
*   Enabling [Point in Time Recovery](/docs/guides/platform/backups#point-in-time-recovery) which requires at least a [small compute add-on](/docs/guides/platform/compute-add-ons).
*   Turning on [SSL Enforcement](/docs/guides/platform/ssl-enforcement).
*   Enabling [Network Restrictions](/docs/guides/platform/network-restrictions).
*   Disabling data sharing for [Supabase AI editor](https://supabase.com/dashboard/org/_/general) in our dashboard.
    *   Specifically, "*Opt-in to sending anonymous data to OpenAI*" should be disabled (Opt-out).
*   Complying with encryption requirements in the HIPAA Security Rule. Data is encrypted at rest and in transit by Supabase. You can consider encrypting the data at your application layer.
*   Not using [Edge functions](/docs/guides/functions) to process PHI.
*   Not storing PHI in [public Storage buckets](/docs/guides/storage/buckets/fundamentals#public-buckets).
*   Not [transferring projects](/docs/guides/platform/project-transfer) to a non-HIPAA organization.

For more information on the shared responsibilities and rules under HIPAA, review the [HIPAA compliance responsibilities document](/docs/guides/security/hipaa-compliance).


# Edge Functions

Globally distributed TypeScript functions.

Edge Functions are server-side TypeScript functions, distributed globally at the edge—close to your users. They can be used for listening to webhooks or integrating your Supabase project with third-parties [like Stripe](https://github.com/supabase/supabase/tree/master/examples/edge-functions/supabase/functions/stripe-webhooks). Edge Functions are developed using [Deno](https://deno.com), which offers a few benefits to you as a developer:

*   It is open source.
*   It is portable. Supabase Edge Functions run locally, and on any other Deno-compatible platform (including self-hosted infrastructure).
*   It is TypeScript first and supports WASM.
*   Edge Functions are globally distributed for low-latency.


## Examples

Check out the [Edge Function Examples](https://github.com/supabase/supabase/tree/master/examples/edge-functions) in our GitHub repository.


# Running AI Models

How to run AI models in Edge Functions.

[Supabase Edge Runtime](https://github.com/supabase/edge-runtime) has a built-in API for running AI models. You can use this API to generate embeddings, build conversational workflows, and do other AI related tasks in your Edge Functions.


## Setup

There are no external dependencies or packages to install to enable the API.

You can create a new inference session by doing:

```ts
const model = new Supabase.ai.Session('model-name')
```


## Running a model inference

Once the session is instantiated, you can call it with inputs to perform inferences. Depending on the model you run, you may need to provide different options (discussed below).

```ts
const output = await model.run(input, options)
```


## How to generate text embeddings

Now let's see how to write an Edge Function using the `Supabase.ai` API to generate text embeddings. Currently, `Supabase.ai` API only supports the [gte-small](https://huggingface.co/Supabase/gte-small) model.

```ts
const model = new Supabase.ai.Session('gte-small')

Deno.serve(async (req: Request) => {
  const params = new URL(req.url).searchParams
  const input = params.get('input')
  const output = await model.run(input, { mean_pool: true, normalize: true })
  return new Response(JSON.stringify(output), {
    headers: {
      'Content-Type': 'application/json',
      Connection: 'keep-alive',
    },
  })
})
```


## Using Large Language Models (LLM)

Inference via larger models is supported via [Ollama](https://ollama.com/) and [Mozilla Llamafile](https://github.com/Mozilla-Ocho/llamafile). In the first iteration, you can use it with a self-managed Ollama or [Llamafile server](https://www.docker.com/blog/a-quick-guide-to-containerizing-llamafile-with-docker-for-ai-applications/). We are progressively rolling out support for the hosted solution. To sign up for early access, fill up [this form](https://forms.supabase.com/supabase.ai-llm-early-access).


### Running locally


### Deploying to production

Once the function is working locally, it's time to deploy to production.

Deploy an Ollama or Llamafile server and set a function secret called `AI_INFERENCE_API_HOST` to point to the deployed server

```bash
supabase secrets set AI_INFERENCE_API_HOST=https://path-to-your-llm-server/
```

Deploy the Supabase function

```bash
supabase functions deploy
```

Execute the function

```bash
curl --get "https://project-ref.supabase.co/functions/v1/ollama-test" \
 --data-urlencode "prompt=write a short rap song about Supabase, the Postgres Developer platform, as sung by Nicki Minaj" \
 -H "Authorization: $ANON_KEY"
```

As demonstrated in the video above, running Ollama locally is typically slower than running it in on a server with dedicated GPUs. We are collaborating with the Ollama team to improve local performance.

In the future, a hosted LLM API, will be provided as part of the Supabase platform. Supabase will scale and manage the API and GPUs for you. To sign up for early access, fill up [this form](https://forms.supabase.com/supabase.ai-llm-early-access).


# Integrating With Supabase Auth

Supabase Edge Functions and Auth.

Edge Functions work seamlessly with [Supabase Auth](/docs/guides/auth).


## Auth context

When a user makes a request to an Edge Function, you can use the Authorization header to set the Auth context in the Supabase client:

```js
import { createClient } from 'jsr:@supabase/supabase-js@2'

Deno.serve(async (req: Request) => {

  const supabaseClient = createClient(
    Deno.env.get('SUPABASE_URL') ?? '',
    Deno.env.get('SUPABASE_ANON_KEY') ?? '',
  );

  // Get the session or user object
  const authHeader = req.headers.get('Authorization')!;
  const token = authHeader.replace('Bearer ', '');
  const { data } = await supabaseClient.auth.getUser(token);

})
```

Importantly, this is done *inside* the `Deno.serve()` callback argument, so that the Authorization header is set for each request.


## Fetching the user

After initializing a Supabase client with the Auth context, you can use `getUser()` to fetch the user object, and run queries in the context of the user with [Row Level Security (RLS)](/docs/guides/database/postgres/row-level-security) policies enforced.

```js
import { createClient } from 'jsr:@supabase/supabase-js@2'

Deno.serve(async (req: Request) => {

  const supabaseClient = createClient(
    Deno.env.get('SUPABASE_URL') ?? '',
    Deno.env.get('SUPABASE_ANON_KEY') ?? '',
  )

  // Get the session or user object
  const authHeader = req.headers.get('Authorization')!
  const token = authHeader.replace('Bearer ', '')
  const { data } = await supabaseClient.auth.getUser(token)
  const user = data.user

  return new Response(JSON.stringify({ user }), {
    headers: { 'Content-Type': 'application/json' },
    status: 200,
  })

})
```


## Row Level Security

After initializing a Supabase client with the Auth context, all queries will be executed with the context of the user. For database queries, this means [Row Level Security](/docs/guides/database/postgres/row-level-security) will be enforced.

```js
import { createClient } from 'jsr:@supabase/supabase-js@2'

Deno.serve(async (req: Request) => {

  const supabaseClient = createClient(
    Deno.env.get('SUPABASE_URL') ?? '',
    Deno.env.get('SUPABASE_ANON_KEY') ?? '',
  );

  // Get the session or user object
  const authHeader = req.headers.get('Authorization')!;
  const token = authHeader.replace('Bearer ', '');
  const { data: userData } = await supabaseClient.auth.getUser(token);
  const { data, error } = await supabaseClient.from('profiles').select('*');

  return new Response(JSON.stringify({ data }), {
    headers: { 'Content-Type': 'application/json' },
    status: 200,
  })

})
```


## Example code

See a full [example on GitHub](https://github.com/supabase/supabase/blob/master/examples/edge-functions/supabase/functions/select-from-table-with-auth-rls/index.ts).


# Background Tasks

How to run background tasks in an Edge Function outside of the request handler

Edge Function instances can process background tasks outside of the request handler. Background tasks are useful for asynchronous operations like uploading a file to Storage, updating a database, or sending events to a logging service. You can respond to the request immediately and leave the task running in the background.


### How it works

You can use `EdgeRuntime.waitUntil(promise)` to explicitly mark background tasks. The Function instance continues to run until the promise provided to `waitUntil` completes.

The maximum duration is capped based on the wall-clock, CPU, and memory limits. The Function will shutdown when it reaches one of these [limits](/docs/guides/functions/limits).

You can listen to the `beforeunload` event handler to be notified when Function invocation is about to be shut down.


### Example

Here's an example of using `EdgeRuntime.waitUntil` to run a background task and using `beforeunload` event to be notified when the instance is about to be shut down.

```ts
async function longRunningTask() {
  // do work here
}

// Mark the longRunningTask's returned promise as a background task.
// note: we are not using await because we don't want it to block.
EdgeRuntime.waitUntil(longRunningTask())

// Use beforeunload event handler to be notified when function is about to shutdown
addEventListener('beforeunload', (ev) => {
  console.log('Function will be shutdown due to', ev.detail?.reason)

  // save state or log the current progress
})

// Invoke the function using a HTTP request.
// This will start the background task
Deno.serve(async (req) => {
  return new Response('ok')
})
```


### Starting a background task in the request handler

You can call `EdgeRuntime.waitUntil` in the request handler too. This will not block the request.

```ts
async function fetchAndLog(url: string) {
  const response = await fetch(url)
  console.log(response)
}

Deno.serve(async (req) => {
  // this will not block the request,
  // instead it will run in the background
  EdgeRuntime.waitUntil(fetchAndLog('https://httpbin.org/json'))

  return new Response('ok')
})
```


### Testing background tasks locally

When testing Edge Functions locally with Supabase CLI, the instances are terminated automatically after a request is completed. This will prevent background tasks from running to completion.

To prevent that, you can update the `supabase/config.toml` with the following settings:

```toml
[edge_runtime]
policy = "per_worker"
```

When running with `per_worker` policy, Function won't auto-reload on edits. You will need to manually restart it by running `supabase functions serve`.


# Deploying with CI / CD pipelines

Use GitHub Actions, Bitbucket, and GitLab CI to deploy your Edge Functions.

You can use popular CI / CD tools like GitHub Actions, Bitbucket, and GitLab CI to automate Edge Function deployments.


## GitHub Actions

You can use the official [`setup-cli` GitHub Action](https://github.com/marketplace/actions/supabase-cli-action) to run Supabase CLI commands in your GitHub Actions.

The following GitHub Action deploys all Edge Functions any time code is merged into the `main` branch:

```yaml
name: Deploy Function

on:
  push:
    branches:
      - main
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest

    env:
      SUPABASE_ACCESS_TOKEN: ${{ secrets.SUPABASE_ACCESS_TOKEN }}
      PROJECT_ID: your-project-id

    steps:
      - uses: actions/checkout@v4

      - uses: supabase/setup-cli@v1
        with:
          version: latest

      - run: supabase functions deploy --project-ref $PROJECT_ID
```


## GitLab CI

Here is the sample pipeline configuration to deploy via GitLab CI.

```yaml
image: node:20

# List of stages for jobs, and their order of execution
stages:
  - setup
  - deploy

# This job runs in the setup stage, which runs first.
setup-npm:
  stage: setup
  script:
    - npm i supabase
  cache:
    paths:
      - node_modules/
  artifacts:
    paths:
      - node_modules/

# This job runs in the deploy stage, which only starts when the job in the build stage completes successfully.
deploy-function:
  stage: deploy
  script:
    - npx supabase init
    - npx supabase functions deploy --debug
  services:
    - docker:dind
  variables:
    DOCKER_HOST: tcp://docker:2375
```


## Bitbucket Pipelines

Here is the sample pipeline configuration to deploy via Bitbucket.

```yaml
image: node:20

pipelines:
  default:
    - step:
        name: Setup
        caches:
          - node
        script:
          - npm i supabase
    - parallel:
        - step:
            name: Functions Deploy
            script:
              - npx supabase init
              - npx supabase functions deploy --debug
            services:
              - docker
```


## Declarative configuration

Individual function configuration like [JWT verification](/docs/guides/cli/config#functions.function_name.verify_jwt) and [import map location](/docs/guides/cli/config#functions.function_name.import_map) can be set via the `config.toml` file.

```toml
[functions.hello-world]
verify_jwt = false
```


## Resources

*   See the [example on GitHub](https://github.com/supabase/supabase/blob/master/examples/edge-functions/.github/workflows/deploy.yaml).


# Handling Compressed Requests

Handling Gzip compressed requests.

To decompress Gzip bodies, you can use `gunzipSync` from the `node:zlib` API to decompress and then read the body.

```ts
import { gunzipSync } from 'node:zlib'

Deno.serve(async (req) => {
  try {
    // Check if the request body is gzip compressed
    const contentEncoding = req.headers.get('content-encoding')
    if (contentEncoding !== 'gzip') {
      return new Response('Request body is not gzip compressed', {
        status: 400,
      })
    }

    // Read the compressed body
    const compressedBody = await req.arrayBuffer()

    // Decompress the body
    const decompressedBody = gunzipSync(new Uint8Array(compressedBody))

    // Convert the decompressed body to a string
    const decompressedString = new TextDecoder().decode(decompressedBody)
    const data = JSON.parse(decompressedString)

    // Process the decompressed body as needed
    console.log(`Received: ${JSON.stringify(data)}`)

    return new Response('ok', {
      headers: { 'Content-Type': 'text/plain' },
    })
  } catch (error) {
    console.error('Error:', error)
    return new Response('Error processing request', { status: 500 })
  }
})
```


# Connecting directly to Postgres

Connecting to Postgres from Edge Functions.

Connect to your Postgres database from an Edge Function by using the `supabase-js` client.
You can also use other Postgres clients like [Deno Postgres](https://deno.land/x/postgres)


## Using supabase-js

The `supabase-js` client is a great option for connecting to your Supabase database since it handles authorization with Row Level Security, and it automatically formats your response as JSON.

```ts index.ts
import { createClient } from 'jsr:@supabase/supabase-js@2'

Deno.serve(async (req) => {
  try {
    const supabase = createClient(
      Deno.env.get('SUPABASE_URL') ?? '',
      Deno.env.get('SUPABASE_ANON_KEY') ?? '',
      { global: { headers: { Authorization: req.headers.get('Authorization')! } } }
    )

    const { data, error } = await supabase.from('countries').select('*')

    if (error) {
      throw error
    }

    return new Response(JSON.stringify({ data }), {
      headers: { 'Content-Type': 'application/json' },
      status: 200,
    })
  } catch (err) {
    return new Response(String(err?.message ?? err), { status: 500 })
  }
})
```


## Using a Postgres client

Because Edge Functions are a server-side technology, it's safe to connect directly to your database using any popular Postgres client. This means you can run raw SQL from your Edge Functions.

Here is how you can connect to the database using Deno Postgres driver and run raw SQL.

Check out the [full example](https://github.com/supabase/supabase/tree/master/examples/edge-functions/supabase/functions/postgres-on-the-edge).

```ts index.ts
import * as postgres from 'https://deno.land/x/postgres@v0.17.0/mod.ts'

// Get the connection string from the environment variable "SUPABASE_DB_URL"
const databaseUrl = Deno.env.get('SUPABASE_DB_URL')!

// Create a database pool with three connections that are lazily established
const pool = new postgres.Pool(databaseUrl, 3, true)

Deno.serve(async (_req) => {
  try {
    // Grab a connection from the pool
    const connection = await pool.connect()

    try {
      // Run a query
      const result = await connection.queryObject`SELECT * FROM animals`
      const animals = result.rows // [{ id: 1, name: "Lion" }, ...]

      // Encode the result as pretty printed JSON
      const body = JSON.stringify(
        animals,
        (key, value) => (typeof value === 'bigint' ? value.toString() : value),
        2
      )

      // Return the response with the correct content type header
      return new Response(body, {
        status: 200,
        headers: { 'Content-Type': 'application/json; charset=utf-8' },
      })
    } finally {
      // Release the connection back into the pool
      connection.release()
    }
  } catch (err) {
    console.error(err)
    return new Response(String(err?.message ?? err), { status: 500 })
  }
})
```


## Using Drizzle

You can use Drizzle together with [Postgres.js](https://github.com/porsager/postgres). Both can be loaded directly from npm:

```json supabase/functions/import_map.json
{
  "imports": {
    "drizzle-orm": "npm:drizzle-orm@0.29.1",
    "drizzle-orm/": "npm:/drizzle-orm@0.29.1/",
    "postgres": "npm:postgres@3.4.3"
  }
}
```

```ts supabase/functions/drizzle/index.ts
import { drizzle } from 'drizzle-orm/postgres-js'
import postgres from 'postgres'
import { countries } from '../_shared/schema.ts'

const connectionString = Deno.env.get('SUPABASE_DB_URL')!

Deno.serve(async (_req) => {
  // Disable prefetch as it is not supported for "Transaction" pool mode
  const client = postgres(connectionString, { prepare: false })
  const db = drizzle(client)
  const allCountries = await db.select().from(countries)

  return Response.json(allCountries)
})
```

You can find the full example on [GitHub](https://github.com/thorwebdev/edgy-drizzle).


## SSL connections

Deployed edge functions are pre-configured to use SSL for connections to the Supabase database. You don't need to add any extra configurations.

If you want to use SSL connections during local development, follow these steps:

*   Download the SSL certificate from [Database settings](https://supabase.com/dashboard/project/_/settings/database)

*   In your [local .env file](https://supabase.com/docs/guides/functions/secrets), add these two variables:

```bash
SSL_CERT_FILE=/path/to/cert.crt # set the path to the downloaded cert
DENO_TLS_CA_STORE=mozilla,system
```


# CORS (Cross-Origin Resource Sharing) support for Invoking from the browser



To invoke edge functions from the browser, you need to handle [CORS Preflight](https://developer.mozilla.org/en-US/docs/Glossary/Preflight_request) requests.

See the [example on GitHub](https://github.com/supabase/supabase/blob/master/examples/edge-functions/supabase/functions/browser-with-cors/index.ts).


### Recommended setup

We recommend adding a `cors.ts` file within a [`_shared` folder](/docs/guides/functions/quickstart#organizing-your-edge-functions) which makes it easy to reuse the CORS headers across functions:

```ts cors.ts
export const corsHeaders = {
  'Access-Control-Allow-Origin': '*',
  'Access-Control-Allow-Headers': 'authorization, x-client-info, apikey, content-type',
}
```

You can then import and use the CORS headers within your functions:

```ts index.ts
import { corsHeaders } from '../_shared/cors.ts'

console.log(`Function "browser-with-cors" up and running!`)

Deno.serve(async (req) => {
  // This is needed if you're planning to invoke your function from a browser.
  if (req.method === 'OPTIONS') {
    return new Response('ok', { headers: corsHeaders })
  }

  try {
    const { name } = await req.json()
    const data = {
      message: `Hello ${name}!`,
    }

    return new Response(JSON.stringify(data), {
      headers: { ...corsHeaders, 'Content-Type': 'application/json' },
      status: 200,
    })
  } catch (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      headers: { ...corsHeaders, 'Content-Type': 'application/json' },
      status: 400,
    })
  }
})
```


# Dart Edge



[Dart Edge](https://docs.dartedge.dev/) is an experimental project that enables you to write Supabase Edge Functions using Dart. It's built and maintained by [Invertase](https://invertase.io/).

For detailed information on how to set up and use Dart Edge with Supabase, refer to the [official Dart Edge documentation for Supabase](https://invertase.docs.page/dart_edge/platform/supabase).


# Local Debugging with DevTools

How to use Chrome DevTools to debug Edge Functions.

Since [v1.171.0](https://github.com/supabase/cli/releases/tag/v1.171.0) the Supabase CLI supports debugging Edge Functions via the v8 inspector protocol, allowing for debugging via [Chrome DevTools](https://developer.chrome.com/docs/devtools/) and other Chromium-based browsers.


### Inspect with Chrome Developer Tools

You can use the [Chrome DevTools](https://developer.chrome.com/docs/devtools/) to set breakpoints and inspect the execution of your Edge Functions.

1.  Serve your functions in [inspect mode](/docs/reference/cli/supabase-functions-serve): `supabase functions serve --inspect-mode brk`. This will set a breakpoint at the first line to pause script execution before any code runs.
2.  In your Chrome browser navigate to `chrome://inspect`.
3.  Click the "Configure..."" button to the right of the Discover network targets checkbox.
4.  In the Target discovery settings dialog box that opens, enter `127.0.0.1:8083` in the blank space and click the "Done" button to exit the dialog box.
5.  Click "Open dedicated DevTools for Node" to complete the preparation for debugging. The opened DevTools window will now listen to any incoming requests to edge-runtime.
6.  Send a request to your function running locally, e.g. via curl or Postman. The DevTools window will now pause script execution at first line.
7.  In the "Sources" tab navigate to `file://` > `home/deno/functions/<your-function-name>/index.ts`.
8.  Use the DevTools to set breakpoints and inspect the execution of your Edge Function.

![Debugging in Chrome DevTools.](/docs/img/guides/functions/debug-chrome-devtools.png)


# Using Deno 2

Everything you need to know about the Deno 2 runtime

### What is Deno 2?

Deno 2 is a major upgrade to the Deno runtime that powers Supabase Edge Functions. It focuses on scalability and seamless ecosystem compatibility while maintaining Deno's core principles of security, simplicity, and developer experience.

**Key improvements include**

*   **Node.js and npm compatibility**: Dramatically improved support for npm packages and Node.js code
*   **Better dependency management**: New tools like `deno install`, `deno add`, and `deno remove` for simplified package management
*   **Improved performance**: Enhanced runtime execution and startup times
*   **Workspace and monorepo support**: Better handling of complex project structures
*   **Framework compatibility**: Support for Next.js, SvelteKit, Remix, and other popular frameworks
*   **Full package.json support**: Works seamlessly with existing Node.js projects and npm workspaces

While these improvements are exciting, they come with some changes that may affect your existing functions. We'll support Deno 1.x functions for a limited time, but we recommend migrating to Deno 2 within the next few months to ensure continued functionality.


### How to use Deno 2

Deno 2 will soon become the default choice for creating new functions. For now, Deno 2 is available in preview mode for local development.

Here's how you can build and deploy a function with Deno 2:

*   [Install Deno 2.1](https://docs.deno.com/runtime/getting_started/installation/) or newer version on your machine

*   Go to your Supabase project. `cd my-supabase-project`

*   Open `supabase/config.toml` and set `deno_version = 2`

```toml
[edge_runtime]
deno_version = 2
```

*   All your existing functions should work as before.

To scaffold a new function as a Deno 2 project:

```bash
deno init --serve hello-world
```

*   Open `supabase/config.toml` and add the following:

<!---->

    [functions.hello-world]
    entrypoint = "./functions/hello-world/main.ts"

*   Open supabase/functions/hello-world/main.ts and modify line 10 to:

```typescript
if (url.pathname === "/hello-world") {
```

*   Use `npx supabase@beta functions serve --no-verify-jwt` to start the dev server.

*   Visit http://localhost:54321/functions/v1/hello-world.

*   To run built-in tests, `cd supabase/functions/hello-world; deno test`


### How to migrate existing functions from Deno 1 to Deno 2

For a comprehensive migration guide, see the [official Deno 1.x to 2.x migration guide](https://docs.deno.com/runtime/reference/migration_guide/#content).

Most Deno 1 Edge Functions will be compatible out of the box with Deno 2, and no action needs to be taken. When we upgrade our hosted runtime, your functions will automatically be deployed on a Deno 2 cluster.

However, for a small number of functions, this may break existing functionality.

The most common issue to watch for is that some Deno 1 API calls are incompatible with Deno 2 runtime.

For instance if you are using:

*   `Deno.Closer`

Use [`Closer`](https://jsr.io/@std/io/doc/types/~/Closer) from the Standard Library instead.

```tsx
+ import type { Closer } from "jsr:@std/io/types";
- function foo(closer: Deno.Closer) {
+ function foo(closer: Closer) {
  // ...
}
```

The best way to validate your APIs are up to date is to use the Deno lint, which has [rules to disallow deprecated APIs](https://docs.deno.com/lint/rules/no-deprecated-deno-api/).

```bash
deno lint
```

For a full list of API changes, see the [official Deno 2 list](https://docs.deno.com/runtime/reference/migration_guide/#api-changes).


# Managing dependencies

Managing packages and dependencies.

## Importing dependencies

Supabase Edge Functions support several ways to import dependencies:

*   JavaScript modules from npm (https://docs.deno.com/examples/npm/)
*   Built-in [Node APIs](https://docs.deno.com/runtime/manual/node/compatibility)
*   Modules published to [JSR](https://jsr.io/) or [deno.land/x](https://deno.land/x)


### NPM modules

You can import npm modules using the `npm:` specifier:

```ts
import { createClient } from 'npm:@supabase/supabase-js@2'
```


### Node.js built-ins

For Node.js built-in APIs, use the `node:` specifier:

```ts
import process from 'node:process'
```

Learn more about npm specifiers and Node built-in APIs in [Deno's documentation](https://docs.deno.com/runtime/manual/node/npm_specifiers).


### JSR

You can import JS modules published to [JSR](https://jsr.io/) (e.g.: Deno's standard library), using the `jsr:` specifier:

```ts
import path from 'jsr:@std/path@1.0.8'
```


## Managing dependencies

Developing with Edge Functions is similar to developing with Node.js, but with a few key differences.

In the Deno ecosystem, each function should be treated as an independent project with its own set of dependencies and configurations. This "isolation by design" approach:

*   Ensures each function has explicit control over its dependencies
*   Prevents unintended side effects between functions
*   Makes deployments more predictable and maintainable
*   Allows for different versions of the same dependency across functions

For these reasons, we recommend maintaining separate configuration files (`deno.json`, `.npmrc`, or `import_map.json`) within each function's directory, even if it means duplicating some configurations.

There are two ways to manage your dependencies in Supabase Edge Functions:


### Using deno.json (recommended)

Each function should have its own `deno.json` file to manage dependencies and configure Deno-specific settings. This ensures proper isolation between functions and is the recommended approach for deployment. For a complete list of supported options, see the [official Deno configuration documentation](https://docs.deno.com/runtime/manual/getting_started/configuration_file).

```json supabase/functions/my-function/deno.json
{
  "imports": {
    "lodash": "https://cdn.skypack.dev/lodash"
  }
}
```

The recommended file structure for deployment:

```bash
└── supabase
    ├── functions
    │   ├── function-one
    │   │   ├── index.ts
    │   │   ├─- deno.json    # Function-specific Deno configuration
    │   │   └── .npmrc       # Function-specific npm configuration (if needed)
    │   └── function-two
    │       ├── index.ts
    │       ├─- deno.json    # Function-specific Deno configuration
    │       └── .npmrc       # Function-specific npm configuration (if needed)
    └── config.toml
```


### Using import maps (legacy)

Import Maps are a legacy way to manage dependencies, similar to a `package.json` file. While still supported, we recommend using `deno.json`. If both exist, `deno.json` takes precedence.

Each function should have its own `import_map.json` file for proper isolation:

```json supabase/functions/my-function/import_map.json
{
  "imports": {
    "lodash": "https://cdn.skypack.dev/lodash"
  }
}
```

The recommended file structure:

```bash
└── supabase
    ├── functions
    │   ├── function-one
    │   │   ├── index.ts
    │   │   └── import_map.json    # Function-specific import map
    │   └── function-two
    │       ├── index.ts
    │       └── import_map.json    # Function-specific import map
    └── config.toml
```

If using import maps with VSCode, update your `.vscode/settings.json` to point to your function-specific import map:

```json settings.json
{
  "deno.enable": true,
  "deno.unstable": [
    "bare-node-builtins",
    "byonm"
    // ... other flags ...
  ],
  "deno.importMap": "./supabase/functions/my-function/import_map.json"
}
```

You can override the default import map location using the `--import-map <string>` flag with `serve` and `deploy` commands, or by setting the `import_map` property in your `config.toml` file:

```toml supabase/config.toml
[functions.my-function]
import_map = "./supabase/functions/my-function/import_map.json"
```


### Importing from private registries

To use private npm packages, create a `.npmrc` file within your function directory. This ensures proper isolation and dependency management for each function.

```bash
└── supabase
    └── functions
        └── my-function
            ├── index.ts
            ├── deno.json
            └── .npmrc       # Function-specific npm configuration
```

Add your registry details in the `.npmrc` file. Follow [this guide](https://docs.npmjs.com/cli/v10/configuring-npm/npmrc) to learn more about the syntax of npmrc files.

```plaintext
@myorg:registry=https://npm.registryhost.com
//npm.registryhost.com/:_authToken=VALID_AUTH_TOKEN
```

After configuring your `.npmrc`, you can import the private package in your function code:

```ts
import MyPackage from 'npm:@myorg/private-package@v1.0.1'

// use MyPackage
```


### Using a custom NPM registry

Some organizations require a custom NPM registry for security and compliance purposes. In such instances, you can specify the custom NPM registry to use via `NPM_CONFIG_REGISTRY` environment variable.

You can define it in the project's `.env` file or directly specify it when running the deploy command:

```bash
NPM_CONFIG_REGISTRY=https://custom-registry/ supabase functions deploy my-function
```


## Importing types

If your [environment is set up properly](/docs/guides/functions/local-development) and the module you're importing is exporting types, the import will have types and autocompletion support.

Some npm packages may not ship out of the box types and you may need to import them from a separate package. You can specify their types with a `@deno-types` directive:

```ts
// @deno-types="npm:@types/express@^4.17"
import express from 'npm:express@^4.17'
```

To include types for built-in Node APIs, add the following line to the top of your imports:

```ts
/// <reference types="npm:@types/node" />
```


# Deploy to Production

Deploy your Edge Functions to your remote Supabase Project.

Once you have developed your Edge Functions locally, you can deploy them to your Supabase project.


## Login to the CLI

Log in to the Supabase CLI if necessary:

```bash
supabase login
```


## Get your project ID

Get the project ID associated with your function by running:

```bash
supabase projects list
```


## Link your local project

[Link](/docs/reference/cli/usage#supabase-link) your local project to your remote Supabase project using the ID you just retrieved:

```bash
supabase link --project-ref your-project-id
```


## Deploy your Edge Functions

You can deploy all of your Edge Functions with a single command:

```bash
supabase functions deploy
```

You can deploy individual Edge Functions by specifying the name of the function in the deploy command:

```bash
supabase functions deploy hello-world
```

By default, Edge Functions require a valid JWT in the authorization header. If you want to use Edge Functions without Authorization checks (commonly used for Stripe webhooks), you can pass the `--no-verify-jwt` flag when deploying your Edge Functions.

```bash
supabase functions deploy hello-world --no-verify-jwt
```

Be careful when using this flag, as it will allow anyone to invoke your Edge Function without a valid JWT. The Supabase client libraries automatically handle authorization.


## Invoking remote functions

You can now invoke your Edge Function using the project's `ANON_KEY`, which can be found in the [API settings](https://supabase.com/dashboard/project/_/settings/api) of the Supabase Dashboard.

You should receive the response `{ "message":"Hello Functions!" }`.


# Development tips

Tips for getting started with Edge Functions.

Here are a few recommendations when you first start developing Edge Functions.


### Skipping authorization checks

By default, Edge Functions require a valid JWT in the authorization header. If you want to use Edge Functions without Authorization checks (commonly used for Stripe webhooks), you can pass the `--no-verify-jwt` flag when serving your Edge Functions locally.

```bash
supabase functions serve hello-world --no-verify-jwt
```

Be careful when using this flag, as it will allow anyone to invoke your Edge Function without a valid JWT. The Supabase client libraries automatically handle authorization.


### Using HTTP methods

Edge Functions support `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, and `OPTIONS`. A Function can be designed to perform different actions based on a request's HTTP method. See the [example on building a RESTful service](https://github.com/supabase/supabase/tree/master/examples/edge-functions/supabase/functions/restful-tasks) to learn how to handle different HTTP methods in your Function.


### Naming Edge Functions

We recommend using hyphens to name functions because hyphens are the most URL-friendly of all the naming conventions (snake\_case, camelCase, PascalCase).


### Organizing your Edge Functions

We recommend developing "fat functions". This means that you should develop few large functions, rather than many small functions. One common pattern when developing Functions is that you need to share code between two or more Functions. To do this, you can store any shared code in a folder prefixed with an underscore (`_`). We also recommend a separate folder for [Unit Tests](/docs/guides/functions/unit-test) including the name of the function followed by a `-test` suffix.
We recommend this folder structure:

```bash
└── supabase
    ├── functions
    │   ├── import_map.json # A top-level import map to use across functions.
    │   ├── _shared
    │   │   ├── supabaseAdmin.ts # Supabase client with SERVICE_ROLE key.
    │   │   └── supabaseClient.ts # Supabase client with ANON key.
    │   │   └── cors.ts # Reusable CORS headers.
    │   ├── function-one # Use hyphens to name functions.
    │   │   └── index.ts
    │   └── function-two
    │   │   └── index.ts
    │   └── tests
    │       └── function-one-test.ts
    │       └── function-two-test.ts
    ├── migrations
    └── config.toml
```


### Using config.toml

Individual function configuration like [JWT verification](/docs/guides/cli/config#functions.function_name.verify_jwt) and [import map location](/docs/guides/cli/config#functions.function_name.import_map) can be set via the `config.toml` file.

```toml supabase/config.toml
[functions.hello-world]
verify_jwt = false
import_map = './import_map.json'
```


### Not using TypeScript

When you create a new Edge Function, it will use TypeScript by default. However, it is possible to write and deploy Edge Functions using pure JavaScript.

Save your Function as a JavaScript file (e.g. `index.js`) and then update the `supabase/config.toml` as follows:

```toml supabase/config.toml
[functions.hello-world]
# other entries
entrypoint = './functions/hello-world/index.js' # path must be relative to config.toml
```

You can use any `.ts`, `.js`, `.tsx`, `.jsx` or `.mjs` file as the `entrypoint` for a Function.


### Error handling

The `supabase-js` library provides several error types that you can use to handle errors that might occur when invoking Edge Functions:

```js
import { FunctionsHttpError, FunctionsRelayError, FunctionsFetchError } from '@supabase/supabase-js'

const { data, error } = await supabase.functions.invoke('hello', {
  headers: { 'my-custom-header': 'my-custom-header-value' },
  body: { foo: 'bar' },
})

if (error instanceof FunctionsHttpError) {
  const errorMessage = await error.context.json()
  console.log('Function returned an error', errorMessage)
} else if (error instanceof FunctionsRelayError) {
  console.log('Relay error:', error.message)
} else if (error instanceof FunctionsFetchError) {
  console.log('Fetch error:', error.message)
}
```


### Database Functions vs Edge Functions

For data-intensive operations we recommend using [Database Functions](/docs/guides/database/functions), which are executed within your database and can be called remotely using the [REST and GraphQL API](/docs/guides/api).

For use-cases which require low-latency we recommend [Edge Functions](/docs/guides/functions), which are globally-distributed and can be written in TypeScript.


# Ephemeral Storage

Read and write from temporary directory

Edge Functions provides ephemeral file storage. You can read and write files to the `/tmp` directory.

Ephemeral storage will reset on each function invocation. This means the files you write during an invocation can only be read within the same invocation.


### Use cases

Here are some use cases where ephemeral storage can be useful:

*   Unzip an archive of CSVs and then add them as records to the DB
*   Custom image manipulation workflows (using [`magick-wasm`](https://supabase.com/docs/guides/functions/examples/image-manipulation))

You can use [Background Tasks](https://supabase.com/docs/guides/functions/background-tasks) to handle slow file processing outside of a request.


### How to use

You can use [Deno File System APIs](https://docs.deno.com/api/deno/file-system) or the [`node:fs` module](https://docs.deno.com/api/node/fs/) to access the `/tmp` path.


### Example

Here is an example of how to write a user-uploaded zip file into temporary storage for further processing.

```js
Deno.serve(async (req) => {
  if (req.headers.get('content-type') !== 'application/zip') {
    return new Response('file must be a zip file', {
      status: 400,
    })
  }

  const uploadId = crypto.randomUUID()
  await Deno.writeFile('/tmp/' + uploadId, req.body)

  // do something with the written zip file

  return new Response('ok')
})
```


### Unavailable APIs

Currently, the synchronous APIs (e.g. `Deno.writeFileSync` or `Deno.mkdirSync`) for creating or writing files are not supported.

You can use sync variations of read APIs (e.g. `Deno.readFileSync`).


### Limits

In the hosted platform, a free project can write up to 256MB of data to ephemeral storage. A paid project can write up to 512MB.


# Generate Images with Amazon Bedrock



[Amazon Bedrock](https://aws.amazon.com/bedrock) is a fully managed service that offers a choice of high-performing foundation models (FMs) from leading AI companies like AI21 Labs, Anthropic, Cohere, Meta, Mistral AI, Stability AI, and Amazon. Each model is accessible through a common API which implements a broad set of features to help build generative AI applications with security, privacy, and responsible AI in mind.

This guide will walk you through an example using the Amazon Bedrock JavaScript SDK in Supabase Edge Functions to generate images using the [Amazon Titan Image Generator G1](https://aws.amazon.com/blogs/machine-learning/use-amazon-titan-models-for-image-generation-editing-and-searching/) model.


## Setup

*   In your AWS console, navigate to Amazon Bedrock and under "Request model access", select the Amazon Titan Image Generator G1 model.
*   In your Supabase project, create a `.env` file in the `supabase` directory with the following contents:

```txt
AWS_DEFAULT_REGION="<your_region>"
AWS_ACCESS_KEY_ID="<replace_your_own_credentials>"
AWS_SECRET_ACCESS_KEY="<replace_your_own_credentials>"
AWS_SESSION_TOKEN="<replace_your_own_credentials>"

# Mocked config files
AWS_SHARED_CREDENTIALS_FILE="./aws/credentials"
AWS_CONFIG_FILE="./aws/config"
```


### Configure Storage

*   \[locally] Run `supabase start`
*   Open Studio URL: [locally](http://127.0.0.1:54323/project/default/storage/buckets) | [hosted](https://app.supabase.com/project/_/storage/buckets)
*   Navigate to Storage
*   Click "New bucket"
*   Create a new public bucket called "images"


## Code

Create a new function in your project:

```bash
supabase functions new amazon-bedrock
```

And add the code to the `index.ts` file:

```ts index.ts
// We need to mock the file system for the AWS SDK to work.
import { prepareVirtualFile } from 'https://deno.land/x/mock_file@v1.1.2/mod.ts'

import { BedrockRuntimeClient, InvokeModelCommand } from 'npm:@aws-sdk/client-bedrock-runtime'
import { createClient } from 'npm:@supabase/supabase-js'
import { decode } from 'npm:base64-arraybuffer'

console.log('Hello from Amazon Bedrock!')

Deno.serve(async (req) => {
  prepareVirtualFile('./aws/config')
  prepareVirtualFile('./aws/credentials')

  const client = new BedrockRuntimeClient({
    region: Deno.env.get('AWS_DEFAULT_REGION') ?? 'us-west-2',
    credentials: {
      accessKeyId: Deno.env.get('AWS_ACCESS_KEY_ID') ?? '',
      secretAccessKey: Deno.env.get('AWS_SECRET_ACCESS_KEY') ?? '',
      sessionToken: Deno.env.get('AWS_SESSION_TOKEN') ?? '',
    },
  })

  const { prompt, seed } = await req.json()
  console.log(prompt)
  const input = {
    contentType: 'application/json',
    accept: '*/*',
    modelId: 'amazon.titan-image-generator-v1',
    body: JSON.stringify({
      taskType: 'TEXT_IMAGE',
      textToImageParams: { text: prompt },
      imageGenerationConfig: {
        numberOfImages: 1,
        quality: 'standard',
        cfgScale: 8.0,
        height: 512,
        width: 512,
        seed: seed ?? 0,
      },
    }),
  }

  const command = new InvokeModelCommand(input)
  const response = await client.send(command)
  console.log(response)

  if (response.$metadata.httpStatusCode === 200) {
    const { body, $metadata } = response

    const textDecoder = new TextDecoder('utf-8')
    const jsonString = textDecoder.decode(body.buffer)
    const parsedData = JSON.parse(jsonString)
    console.log(parsedData)
    const image = parsedData.images[0]

    const supabaseClient = createClient(
      // Supabase API URL - env var exported by default.
      Deno.env.get('SUPABASE_URL')!,
      // Supabase API ANON KEY - env var exported by default.
      Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!
    )

    const { data: upload, error: uploadError } = await supabaseClient.storage
      .from('images')
      .upload(`${$metadata.requestId ?? ''}.png`, decode(image), {
        contentType: 'image/png',
        cacheControl: '3600',
        upsert: false,
      })
    if (!upload) {
      return Response.json(uploadError)
    }
    const { data } = supabaseClient.storage.from('images').getPublicUrl(upload.path!)
    return Response.json(data)
  }

  return Response.json(response)
})
```


## Run the function locally

1.  Run `supabase start` (see: https://supabase.com/docs/reference/cli/supabase-start)
2.  Start with env: `supabase functions serve --env-file supabase/.env`
3.  Make an HTTP request:

```bash
  curl -i --location --request POST 'http://127.0.0.1:54321/functions/v1/amazon-bedrock' \
    --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZS1kZW1vIiwicm9sZSI6ImFub24iLCJleHAiOjE5ODM4MTI5OTZ9.CRXP1A7WOeoJeXxjNni43kdQwgnWNReilDMblYTn_I0' \
    --header 'Content-Type: application/json' \
    --data '{"prompt":"A beautiful picture of a bird"}'
```

4.  Navigate back to your storage bucket. You might have to hit the refresh button to see the uploaded image.


## Deploy to your hosted project

```bash
supabase link
supabase functions deploy amazon-bedrock
supabase secrets set --env-file supabase/.env
```

You've now deployed a serverless function that uses AI to generate and upload images to your Supabase storage bucket.


# Custom Auth Emails with React Email and Resend



Use the [send email hook](/docs/guides/auth/auth-hooks/send-email-hook?queryGroups=language\&language=http) to send custom auth emails with [React Email](https://react.email/) and [Resend](https://resend.com/) in Supabase Edge Functions.


### Prerequisites

To get the most out of this guide, you’ll need to:

*   [Create a Resend API key](https://resend.com/api-keys)
*   [Verify your domain](https://resend.com/domains)

Make sure you have the latest version of the [Supabase CLI](https://supabase.com/docs/guides/cli#installation) installed.


### 1. Create Supabase function

Create a new function locally:

```bash
supabase functions new send-email
```


### 2. Edit the handler function

Paste the following code into the `index.ts` file:

```tsx supabase/functions/send-email/index.ts
import React from 'npm:react@18.3.1'
import { Webhook } from 'https://esm.sh/standardwebhooks@1.0.0'
import { Resend } from 'npm:resend@4.0.0'
import { renderAsync } from 'npm:@react-email/components@0.0.22'
import { MagicLinkEmail } from './_templates/magic-link.tsx'

const resend = new Resend(Deno.env.get('RESEND_API_KEY') as string)
const hookSecret = Deno.env.get('SEND_EMAIL_HOOK_SECRET') as string

Deno.serve(async (req) => {
  if (req.method !== 'POST') {
    return new Response('not allowed', { status: 400 })
  }

  const payload = await req.text()
  const headers = Object.fromEntries(req.headers)
  const wh = new Webhook(hookSecret)
  try {
    const {
      user,
      email_data: { token, token_hash, redirect_to, email_action_type },
    } = wh.verify(payload, headers) as {
      user: {
        email: string
      }
      email_data: {
        token: string
        token_hash: string
        redirect_to: string
        email_action_type: string
        site_url: string
        token_new: string
        token_hash_new: string
      }
    }

    const html = await renderAsync(
      React.createElement(MagicLinkEmail, {
        supabase_url: Deno.env.get('SUPABASE_URL') ?? '',
        token,
        token_hash,
        redirect_to,
        email_action_type,
      })
    )

    const { error } = await resend.emails.send({
      from: 'welcome <onboarding@resend.dev>',
      to: [user.email],
      subject: 'Supa Custom MagicLink!',
      html,
    })
    if (error) {
      throw error
    }
  } catch (error) {
    console.log(error)
    return new Response(
      JSON.stringify({
        error: {
          http_code: error.code,
          message: error.message,
        },
      }),
      {
        status: 401,
        headers: { 'Content-Type': 'application/json' },
      }
    )
  }

  const responseHeaders = new Headers()
  responseHeaders.set('Content-Type', 'application/json')
  return new Response(JSON.stringify({}), {
    status: 200,
    headers: responseHeaders,
  })
})
```


### 3. Create React Email templates

Create a new folder `_templates` and create a new file `magic-link.tsx` with the following code:

```tsx supabase/functions/send-email/_templates/magic-link.tsx
import {
  Body,
  Container,
  Head,
  Heading,
  Html,
  Link,
  Preview,
  Text,
} from 'npm:@react-email/components@0.0.22'
import * as React from 'npm:react@18.3.1'

interface MagicLinkEmailProps {
  supabase_url: string
  email_action_type: string
  redirect_to: string
  token_hash: string
  token: string
}

export const MagicLinkEmail = ({
  token,
  supabase_url,
  email_action_type,
  redirect_to,
  token_hash,
}: MagicLinkEmailProps) => (
  <Html>
    <Head />
    <Preview>Log in with this magic link</Preview>
    <Body style={main}>
      <Container style={container}>
        <Heading style={h1}>Login</Heading>
        <Link
          href={`${supabase_url}/auth/v1/verify?token=${token_hash}&type=${email_action_type}&redirect_to=${redirect_to}`}
          target="_blank"
          style={{
            ...link,
            display: 'block',
            marginBottom: '16px',
          }}
        >
          Click here to log in with this magic link
        </Link>
        <Text style={{ ...text, marginBottom: '14px' }}>
          Or, copy and paste this temporary login code:
        </Text>
        <code style={code}>{token}</code>
        <Text
          style={{
            ...text,
            color: '#ababab',
            marginTop: '14px',
            marginBottom: '16px',
          }}
        >
          If you didn&apos;t try to login, you can safely ignore this email.
        </Text>
        <Text style={footer}>
          <Link
            href="https://demo.vercel.store/"
            target="_blank"
            style={{ ...link, color: '#898989' }}
          >
            ACME Corp
          </Link>
          , the famouse demo corp.
        </Text>
      </Container>
    </Body>
  </Html>
)

export default MagicLinkEmail

const main = {
  backgroundColor: '#ffffff',
}

const container = {
  paddingLeft: '12px',
  paddingRight: '12px',
  margin: '0 auto',
}

const h1 = {
  color: '#333',
  fontFamily:
    "-apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif",
  fontSize: '24px',
  fontWeight: 'bold',
  margin: '40px 0',
  padding: '0',
}

const link = {
  color: '#2754C5',
  fontFamily:
    "-apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif",
  fontSize: '14px',
  textDecoration: 'underline',
}

const text = {
  color: '#333',
  fontFamily:
    "-apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif",
  fontSize: '14px',
  margin: '24px 0',
}

const footer = {
  color: '#898989',
  fontFamily:
    "-apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif",
  fontSize: '12px',
  lineHeight: '22px',
  marginTop: '12px',
  marginBottom: '24px',
}

const code = {
  display: 'inline-block',
  padding: '16px 4.5%',
  width: '90.5%',
  backgroundColor: '#f4f4f4',
  borderRadius: '5px',
  border: '1px solid #eee',
  color: '#333',
}
```


### 4. Deploy the Function

Deploy function to Supabase:

```bash
supabase functions deploy send-email --no-verify-jwt
```

Note down the function URL, you will need it in the next step!


### 5. Configure the Send Email Hook

*   Go to the [Auth Hooks](/dashboard/project/_/auth/hooks) section of the Supabase dashboard and create a new "Send Email hook".
*   Select HTTPS as the hook type.
*   Paste the function URL in the "URL" field.
*   Click "Generate Secret" to generate your webhook secret and note it down.
*   Click "Create" to save the hook configuration.

Store these secrets in your `.env` file.

```bash supabase/functions/.env
RESEND_API_KEY=your_resend_api_key
SEND_EMAIL_HOOK_SECRET=<base64_secret>
```

Set the secrets from the `.env` file:

```bash
supabase secrets set --env-file supabase/functions/.env
```

Now your Supabase Edge Function will be triggered anytime an Auth Email needs to be send to the user!


## More resources

*   [Send Email Hooks](/docs/guides/auth/auth-hooks/send-email-hook)
*   [Auth Hooks](/docs/guides/auth/auth-hooks)


# CAPTCHA support with Cloudflare Turnstile



[Cloudflare Turnstile](https://www.cloudflare.com/products/turnstile/) is a friendly, free CAPTCHA replacement, and it works seamlessly with Supabase Edge Functions to protect your forms. [View on GitHub](https://github.com/supabase/supabase/tree/master/examples/edge-functions/supabase/functions/cloudflare-turnstile).


## Setup

*   Follow these steps to set up a new site: https://developers.cloudflare.com/turnstile/get-started/
*   Add the Cloudflare Turnstile widget to your site: https://developers.cloudflare.com/turnstile/get-started/client-side-rendering/


## Code

Create a new function in your project:

```bash
supabase functions new cloudflare-turnstile
```

And add the code to the `index.ts` file:

```ts index.ts
import { corsHeaders } from '../_shared/cors.ts'

console.log('Hello from Cloudflare Trunstile!')

function ips(req: Request) {
  return req.headers.get('x-forwarded-for')?.split(/\s*,\s*/)
}

Deno.serve(async (req) => {
  // This is needed if you're planning to invoke your function from a browser.
  if (req.method === 'OPTIONS') {
    return new Response('ok', { headers: corsHeaders })
  }

  const { token } = await req.json()
  const clientIps = ips(req) || ['']
  const ip = clientIps[0]

  // Validate the token by calling the
  // "/siteverify" API endpoint.
  let formData = new FormData()
  formData.append('secret', Deno.env.get('CLOUDFLARE_SECRET_KEY') ?? '')
  formData.append('response', token)
  formData.append('remoteip', ip)

  const url = 'https://challenges.cloudflare.com/turnstile/v0/siteverify'
  const result = await fetch(url, {
    body: formData,
    method: 'POST',
  })

  const outcome = await result.json()
  console.log(outcome)
  if (outcome.success) {
    return new Response('success', { headers: corsHeaders })
  }
  return new Response('failure', { headers: corsHeaders })
})
```


## Deploy the server-side validation Edge Functions

*   https://developers.cloudflare.com/turnstile/get-started/server-side-validation/

```bash
supabase functions deploy cloudflare-turnstile
supabase secrets set CLOUDFLARE_SECRET_KEY=your_secret_key
```


## Invoke the function from your site

```js
const { data, error } = await supabase.functions.invoke('cloudflare-turnstile', {
  body: { token },
})
```


# Building a Discord Bot



## Create an application on Discord Developer portal

1.  Go to <https://discord.com/developers/applications> (login using your discord account if required).
2.  Click on **New Application** button available at left side of your profile picture.
3.  Name your application and click on **Create**.
4.  Go to **Bot** section, click on **Add Bot**, and finally on **Yes, do it!** to confirm.

A new application is created which will hold our Slash Command. Don't close the tab as we need information from this application page throughout our development.

Before we can write some code, we need to curl a discord endpoint to register a Slash Command in our app.

Fill `DISCORD_BOT_TOKEN` with the token available in the **Bot** section and `CLIENT_ID` with the ID available on the **General Information** section of the page and run the command on your terminal.

```bash
BOT_TOKEN='replace_me_with_bot_token'
CLIENT_ID='replace_me_with_client_id'
curl -X POST \
-H 'Content-Type: application/json' \
-H "Authorization: Bot $BOT_TOKEN" \
-d '{"name":"hello","description":"Greet a person","options":[{"name":"name","description":"The name of the person","type":3,"required":true}]}' \
"https://discord.com/api/v8/applications/$CLIENT_ID/commands"
```

This will register a Slash Command named `hello` that accepts a parameter named `name` of type string.


## Code

```ts index.ts
// Sift is a small routing library that abstracts away details like starting a
// listener on a port, and provides a simple function (serve) that has an API
// to invoke a function for a specific path.
import { json, serve, validateRequest } from 'https://deno.land/x/sift@0.6.0/mod.ts'
// TweetNaCl is a cryptography library that we use to verify requests
// from Discord.
import nacl from 'https://cdn.skypack.dev/tweetnacl@v1.0.3?dts'

enum DiscordCommandType {
  Ping = 1,
  ApplicationCommand = 2,
}

// For all requests to "/" endpoint, we want to invoke home() handler.
serve({
  '/discord-bot': home,
})

// The main logic of the Discord Slash Command is defined in this function.
async function home(request: Request) {
  // validateRequest() ensures that a request is of POST method and
  // has the following headers.
  const { error } = await validateRequest(request, {
    POST: {
      headers: ['X-Signature-Ed25519', 'X-Signature-Timestamp'],
    },
  })
  if (error) {
    return json({ error: error.message }, { status: error.status })
  }

  // verifySignature() verifies if the request is coming from Discord.
  // When the request's signature is not valid, we return a 401 and this is
  // important as Discord sends invalid requests to test our verification.
  const { valid, body } = await verifySignature(request)
  if (!valid) {
    return json(
      { error: 'Invalid request' },
      {
        status: 401,
      }
    )
  }

  const { type = 0, data = { options: [] } } = JSON.parse(body)
  // Discord performs Ping interactions to test our application.
  // Type 1 in a request implies a Ping interaction.
  if (type === DiscordCommandType.Ping) {
    return json({
      type: 1, // Type 1 in a response is a Pong interaction response type.
    })
  }

  // Type 2 in a request is an ApplicationCommand interaction.
  // It implies that a user has issued a command.
  if (type === DiscordCommandType.ApplicationCommand) {
    const { value } = data.options.find(
      (option: { name: string; value: string }) => option.name === 'name'
    )
    return json({
      // Type 4 responds with the below message retaining the user's
      // input at the top.
      type: 4,
      data: {
        content: `Hello, ${value}!`,
      },
    })
  }

  // We will return a bad request error as a valid Discord request
  // shouldn't reach here.
  return json({ error: 'bad request' }, { status: 400 })
}

/** Verify whether the request is coming from Discord. */
async function verifySignature(request: Request): Promise<{ valid: boolean; body: string }> {
  const PUBLIC_KEY = Deno.env.get('DISCORD_PUBLIC_KEY')!
  // Discord sends these headers with every request.
  const signature = request.headers.get('X-Signature-Ed25519')!
  const timestamp = request.headers.get('X-Signature-Timestamp')!
  const body = await request.text()
  const valid = nacl.sign.detached.verify(
    new TextEncoder().encode(timestamp + body),
    hexToUint8Array(signature),
    hexToUint8Array(PUBLIC_KEY)
  )

  return { valid, body }
}

/** Converts a hexadecimal string to Uint8Array. */
function hexToUint8Array(hex: string) {
  return new Uint8Array(hex.match(/.{1,2}/g)!.map((val) => parseInt(val, 16)))
}
```


## Deploy the slash command handler

```bash
supabase functions deploy discord-bot --no-verify-jwt
supabase secrets set DISCORD_PUBLIC_KEY=your_public_key
```

Navigate to your Function details in the Supabase Dashboard to get your Endpoint URL.


### Configure Discord application to use our URL as interactions endpoint URL

1.  Go back to your application (Greeter) page on Discord Developer Portal
2.  Fill **INTERACTIONS ENDPOINT URL** field with the URL and click on **Save Changes**.

The application is now ready. Let's proceed to the next section to install it.


## Install the slash command on your Discord server

So to use the `hello` Slash Command, we need to install our Greeter application on our Discord server. Here are the steps:

1.  Go to **OAuth2** section of the Discord application page on Discord Developer Portal
2.  Select `applications.commands` scope and click on the **Copy** button below.
3.  Now paste and visit the URL on your browser. Select your server and click on **Authorize**.

Open Discord, type `/Promise` and press **Enter**.


## Run locally

```bash
supabase functions serve discord-bot --no-verify-jwt --env-file ./supabase/.env.local
ngrok http 54321
```


# Streaming Speech with ElevenLabs

Generate and stream speech through Supabase Edge Functions. Store speech in Supabase Storage and cache responses via built-in CDN.

## Introduction

In this tutorial you will learn how to build an edge API to generate, stream, store, and cache speech using Supabase Edge Functions, Supabase Storage, and [ElevenLabs text to speech API](https://elevenlabs.io/text-to-speech).


## Requirements

*   An ElevenLabs account with an [API key](/app/settings/api-keys).
*   A [Supabase](https://supabase.com) account (you can sign up for a free account via [database.new](https://database.new)).
*   The [Supabase CLI](https://supabase.com/docs/guides/local-development) installed on your machine.
*   The [Deno runtime](https://docs.deno.com/runtime/getting_started/installation/) installed on your machine and optionally [setup in your favourite IDE](https://docs.deno.com/runtime/getting_started/setup_your_environment).


## Setup


### Create a Supabase project locally

After installing the [Supabase CLI](https://supabase.com/docs/guides/local-development), run the following command to create a new Supabase project locally:

```bash
supabase init
```


### Configure the storage bucket

You can configure the Supabase CLI to automatically generate a storage bucket by adding this configuration in the `config.toml` file:

```toml ./supabase/config.toml
[storage.buckets.audio]
public = false
file_size_limit = "50MiB"
allowed_mime_types = ["audio/mp3"]
objects_path = "./audio"
```


### Configure background tasks for Supabase Edge Functions

To use background tasks in Supabase Edge Functions when developing locally, you need to add the following configuration in the `config.toml` file:

```toml ./supabase/config.toml
[edge_runtime]
policy = "per_worker"
```


### Create a Supabase Edge Function for speech generation

Create a new Edge Function by running the following command:

```bash
supabase functions new text-to-speech
```

If you're using VS Code or Cursor, select `y` when the CLI prompts "Generate VS Code settings for Deno? \[y/N]"!


### Set up the environment variables

Within the `supabase/functions` directory, create a new `.env` file and add the following variables:

```env supabase/functions/.env
# Find / create an API key at https://elevenlabs.io/app/settings/api-keys
ELEVENLABS_API_KEY=your_api_key
```


### Dependencies

The project uses a couple of dependencies:

*   The [@supabase/supabase-js](https://supabase.com/docs/reference/javascript) library to interact with the Supabase database.
*   The ElevenLabs [JavaScript SDK](/docs/quickstart) to interact with the text-to-speech API.
*   The open-source [object-hash](https://www.npmjs.com/package/object-hash) to generate a hash from the request parameters.

Since Supabase Edge Function uses the [Deno runtime](https://deno.land/), you don't need to install the dependencies, rather you can [import](https://docs.deno.com/examples/npm/) them via the `npm:` prefix.


## Code the Supabase Edge Function

In your newly created `supabase/functions/text-to-speech/index.ts` file, add the following code:

```ts supabase/functions/text-to-speech/index.ts
// Setup type definitions for built-in Supabase Runtime APIs
import 'jsr:@supabase/functions-js/edge-runtime.d.ts'
import { createClient } from 'jsr:@supabase/supabase-js@2'
import { ElevenLabsClient } from 'npm:elevenlabs@1.52.0'
import * as hash from 'npm:object-hash'

const supabase = createClient(
  Deno.env.get('SUPABASE_URL')!,
  Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!
)

const client = new ElevenLabsClient({
  apiKey: Deno.env.get('ELEVENLABS_API_KEY'),
})

// Upload audio to Supabase Storage in a background task
async function uploadAudioToStorage(stream: ReadableStream, requestHash: string) {
  const { data, error } = await supabase.storage
    .from('audio')
    .upload(`${requestHash}.mp3`, stream, {
      contentType: 'audio/mp3',
    })

  console.log('Storage upload result', { data, error })
}

Deno.serve(async (req) => {
  // To secure your function for production, you can for example validate the request origin,
  // or append a user access token and validate it with Supabase Auth.
  console.log('Request origin', req.headers.get('host'))
  const url = new URL(req.url)
  const params = new URLSearchParams(url.search)
  const text = params.get('text')
  const voiceId = params.get('voiceId') ?? 'JBFqnCBsd6RMkjVDRZzb'

  const requestHash = hash.MD5({ text, voiceId })
  console.log('Request hash', requestHash)

  // Check storage for existing audio file
  const { data } = await supabase.storage.from('audio').createSignedUrl(`${requestHash}.mp3`, 60)

  if (data) {
    console.log('Audio file found in storage', data)
    const storageRes = await fetch(data.signedUrl)
    if (storageRes.ok) return storageRes
  }

  if (!text) {
    return new Response(JSON.stringify({ error: 'Text parameter is required' }), {
      status: 400,
      headers: { 'Content-Type': 'application/json' },
    })
  }

  try {
    console.log('ElevenLabs API call')
    const response = await client.textToSpeech.convertAsStream(voiceId, {
      output_format: 'mp3_44100_128',
      model_id: 'eleven_multilingual_v2',
      text,
    })

    const stream = new ReadableStream({
      async start(controller) {
        for await (const chunk of response) {
          controller.enqueue(chunk)
        }
        controller.close()
      },
    })

    // Branch stream to Supabase Storage
    const [browserStream, storageStream] = stream.tee()

    // Upload to Supabase Storage in the background
    EdgeRuntime.waitUntil(uploadAudioToStorage(storageStream, requestHash))

    // Return the streaming response immediately
    return new Response(browserStream, {
      headers: {
        'Content-Type': 'audio/mpeg',
      },
    })
  } catch (error) {
    console.log('error', { error })
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { 'Content-Type': 'application/json' },
    })
  }
})
```


## Run locally

To run the function locally, run the following commands:

```bash
supabase start
```

Once the local Supabase stack is up and running, run the following command to start the function and observe the logs:

```bash
supabase functions serve
```


### Try it out

Navigate to `http://127.0.0.1:54321/functions/v1/text-to-speech?text=hello%20world` to hear the function in action.

Afterwards, navigate to `http://127.0.0.1:54323/project/default/storage/buckets/audio` to see the audio file in your local Supabase Storage bucket.


## Deploy to Supabase

If you haven't already, create a new Supabase account at [database.new](https://database.new) and link the local project to your Supabase account:

```bash
supabase link
```

Once done, run the following command to deploy the function:

```bash
supabase functions deploy
```


### Set the function secrets

Now that you have all your secrets set locally, you can run the following command to set the secrets in your Supabase project:

```bash
supabase secrets set --env-file supabase/functions/.env
```


## Test the function

The function is designed in a way that it can be used directly as a source for an `<audio>` element.

```html
<audio
  src="https://${SUPABASE_PROJECT_REF}.supabase.co/functions/v1/text-to-speech?text=Hello%2C%20world!&voiceId=JBFqnCBsd6RMkjVDRZzb"
  controls
/>
```

You can find an example frontend implementation in the complete code example on [GitHub](https://github.com/elevenlabs/elevenlabs-examples/tree/main/examples/text-to-speech/supabase/stream-and-cache-storage/src/pages/Index.tsx).


# Transcription Telegram Bot

Build a Telegram bot that transcribes audio and video messages in 99 languages using TypeScript with Deno in Supabase Edge Functions.

## Introduction

In this tutorial you will learn how to build a Telegram bot that transcribes audio and video messages in 99 languages using TypeScript and the ElevenLabs Scribe model via the [speech to text API](https://elevenlabs.io/speech-to-text).

To check out what the end result will look like, you can test out the [t.me/ElevenLabsScribeBot](https://t.me/ElevenLabsScribeBot)


## Requirements

*   An ElevenLabs account with an [API key](/app/settings/api-keys).
*   A [Supabase](https://supabase.com) account (you can sign up for a free account via [database.new](https://database.new)).
*   The [Supabase CLI](https://supabase.com/docs/guides/local-development) installed on your machine.
*   The [Deno runtime](https://docs.deno.com/runtime/getting_started/installation/) installed on your machine and optionally [setup in your favourite IDE](https://docs.deno.com/runtime/getting_started/setup_your_environment).
*   A [Telegram](https://telegram.org) account.


## Setup


### Register a Telegram bot

Use the [BotFather](https://t.me/BotFather) to create a new Telegram bot. Run the `/newbot` command and follow the instructions to create a new bot. At the end, you will receive your secret bot token. Note it down securely for the next step.

![BotFather](/docs/img/guides/functions/elevenlabs/bot-father.png)


### Create a Supabase project locally

After installing the [Supabase CLI](https://supabase.com/docs/guides/local-development), run the following command to create a new Supabase project locally:

```bash
supabase init
```


### Create a database table to log the transcription results

Next, create a new database table to log the transcription results:

```bash
supabase migrations new init
```

This will create a new migration file in the `supabase/migrations` directory. Open the file and add the following SQL:

```sql supabase/migrations/init.sql
CREATE TABLE IF NOT EXISTS transcription_logs (
  id BIGSERIAL PRIMARY KEY,
  file_type VARCHAR NOT NULL,
  duration INTEGER NOT NULL,
  chat_id BIGINT NOT NULL,
  message_id BIGINT NOT NULL,
  username VARCHAR,
  transcript TEXT,
  language_code VARCHAR,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
  error TEXT
);

ALTER TABLE transcription_logs ENABLE ROW LEVEL SECURITY;
```


### Create a Supabase Edge Function to handle Telegram webhook requests

Next, create a new Edge Function to handle Telegram webhook requests:

```bash
supabase functions new scribe-bot
```

If you're using VS Code or Cursor, select `y` when the CLI prompts "Generate VS Code settings for Deno? \[y/N]"!


### Set up the environment variables

Within the `supabase/functions` directory, create a new `.env` file and add the following variables:

```env supabase/functions/.env
# Find / create an API key at https://elevenlabs.io/app/settings/api-keys
ELEVENLABS_API_KEY=your_api_key

# The bot token you received from the BotFather.
TELEGRAM_BOT_TOKEN=your_bot_token

# A random secret chosen by you to secure the function.
FUNCTION_SECRET=random_secret
```


### Dependencies

The project uses a couple of dependencies:

*   The open-source [grammY Framework](https://grammy.dev/) to handle the Telegram webhook requests.
*   The [@supabase/supabase-js](https://supabase.com/docs/reference/javascript) library to interact with the Supabase database.
*   The ElevenLabs [JavaScript SDK](/docs/quickstart) to interact with the speech-to-text API.

Since Supabase Edge Function uses the [Deno runtime](https://deno.land/), you don't need to install the dependencies, rather you can [import](https://docs.deno.com/examples/npm/) them via the `npm:` prefix.


## Code the Telegram bot

In your newly created `scribe-bot/index.ts` file, add the following code:

```ts supabase/functions/scribe-bot/index.ts
import { Bot, webhookCallback } from 'https://deno.land/x/grammy@v1.34.0/mod.ts'
import 'jsr:@supabase/functions-js/edge-runtime.d.ts'
import { createClient } from 'jsr:@supabase/supabase-js@2'
import { ElevenLabsClient } from 'npm:elevenlabs@1.50.5'

console.log(`Function "elevenlabs-scribe-bot" up and running!`)

const elevenLabsClient = new ElevenLabsClient({
  apiKey: Deno.env.get('ELEVENLABS_API_KEY') || '',
})

const supabase = createClient(
  Deno.env.get('SUPABASE_URL') || '',
  Deno.env.get('SUPABASE_SERVICE_ROLE_KEY') || ''
)

async function scribe({
  fileURL,
  fileType,
  duration,
  chatId,
  messageId,
  username,
}: {
  fileURL: string
  fileType: string
  duration: number
  chatId: number
  messageId: number
  username: string
}) {
  let transcript: string | null = null
  let languageCode: string | null = null
  let errorMsg: string | null = null
  try {
    const sourceFileArrayBuffer = await fetch(fileURL).then((res) => res.arrayBuffer())
    const sourceBlob = new Blob([sourceFileArrayBuffer], {
      type: fileType,
    })

    const scribeResult = await elevenLabsClient.speechToText.convert({
      file: sourceBlob,
      model_id: 'scribe_v1',
      tag_audio_events: false,
    })

    transcript = scribeResult.text
    languageCode = scribeResult.language_code

    // Reply to the user with the transcript
    await bot.api.sendMessage(chatId, transcript, {
      reply_parameters: { message_id: messageId },
    })
  } catch (error) {
    errorMsg = error.message
    console.log(errorMsg)
    await bot.api.sendMessage(chatId, 'Sorry, there was an error. Please try again.', {
      reply_parameters: { message_id: messageId },
    })
  }
  // Write log to Supabase.
  const logLine = {
    file_type: fileType,
    duration,
    chat_id: chatId,
    message_id: messageId,
    username,
    language_code: languageCode,
    error: errorMsg,
  }
  console.log({ logLine })
  await supabase.from('transcription_logs').insert({ ...logLine, transcript })
}

const telegramBotToken = Deno.env.get('TELEGRAM_BOT_TOKEN')
const bot = new Bot(telegramBotToken || '')
const startMessage = `Welcome to the ElevenLabs Scribe Bot\\! I can transcribe speech in 99 languages with super high accuracy\\!
    \nTry it out by sending or forwarding me a voice message, video, or audio file\\!
    \n[Learn more about Scribe](https://elevenlabs.io/speech-to-text) or [build your own bot](https://elevenlabs.io/docs/cookbooks/speech-to-text/telegram-bot)\\!
  `
bot.command('start', (ctx) => ctx.reply(startMessage.trim(), { parse_mode: 'MarkdownV2' }))

bot.on([':voice', ':audio', ':video'], async (ctx) => {
  try {
    const file = await ctx.getFile()
    const fileURL = `https://api.telegram.org/file/bot${telegramBotToken}/${file.file_path}`
    const fileMeta = ctx.message?.video ?? ctx.message?.voice ?? ctx.message?.audio

    if (!fileMeta) {
      return ctx.reply('No video|audio|voice metadata found. Please try again.')
    }

    // Run the transcription in the background.
    EdgeRuntime.waitUntil(
      scribe({
        fileURL,
        fileType: fileMeta.mime_type!,
        duration: fileMeta.duration,
        chatId: ctx.chat.id,
        messageId: ctx.message?.message_id!,
        username: ctx.from?.username || '',
      })
    )

    // Reply to the user immediately to let them know we received their file.
    return ctx.reply('Received. Scribing...')
  } catch (error) {
    console.error(error)
    return ctx.reply(
      'Sorry, there was an error getting the file. Please try again with a smaller file!'
    )
  }
})

const handleUpdate = webhookCallback(bot, 'std/http')

Deno.serve(async (req) => {
  try {
    const url = new URL(req.url)
    if (url.searchParams.get('secret') !== Deno.env.get('FUNCTION_SECRET')) {
      return new Response('not allowed', { status: 405 })
    }

    return await handleUpdate(req)
  } catch (err) {
    console.error(err)
  }
})
```


## Deploy to Supabase

If you haven't already, create a new Supabase account at [database.new](https://database.new) and link the local project to your Supabase account:

```bash
supabase link
```


### Apply the database migrations

Run the following command to apply the database migrations from the `supabase/migrations` directory:

```bash
supabase db push
```

Navigate to the [table editor](https://supabase.com/dashboard/project/_/editor) in your Supabase dashboard and you should see and empty `transcription_logs` table.

![Empty table](/docs/img/guides/functions/elevenlabs/supa-empty-table.png)

Lastly, run the following command to deploy the Edge Function:

```bash
supabase functions deploy --no-verify-jwt scribe-bot
```

Navigate to the [Edge Functions view](https://supabase.com/dashboard/project/_/functions) in your Supabase dashboard and you should see the `scribe-bot` function deployed. Make a note of the function URL as you'll need it later, it should look something like `https://<project-ref>.functions.supabase.co/scribe-bot`.

![Edge Function deployed](/docs/img/guides/functions/elevenlabs/supa-edge-function-deployed.png)


### Set up the webhook

Set your bot's webhook URL to `https://<PROJECT_REFERENCE>.functions.supabase.co/telegram-bot` (Replacing `<...>` with respective values). In order to do that, run a GET request to the following URL (in your browser, for example):

    https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/setWebhook?url=https://<PROJECT_REFERENCE>.supabase.co/functions/v1/scribe-bot?secret=<FUNCTION_SECRET>

Note that the `FUNCTION_SECRET` is the secret you set in your `.env` file.

![Set webhook](/docs/img/guides/functions/elevenlabs/set-webhook.png)


### Set the function secrets

Now that you have all your secrets set locally, you can run the following command to set the secrets in your Supabase project:

```bash
supabase secrets set --env-file supabase/functions/.env
```


## Test the bot

Finally you can test the bot by sending it a voice message, audio or video file.

![Test the bot](/docs/img/guides/functions/elevenlabs/test-bot.png)

After you see the transcript as a reply, navigate back to your table editor in the Supabase dashboard and you should see a new row in your `transcription_logs` table.

![New row in table](/docs/img/guides/functions/elevenlabs/supa-new-row.png)


# GitHub Actions



Use the Supabase CLI together with GitHub Actions to automatically deploy our Supabase Edge Functions. [View on GitHub](https://github.com/supabase/supabase/tree/master/examples/edge-functions/supabase/functions/github-action-deploy).

```yaml deploy.yaml
name: Deploy Function

on:
  push:
    branches:
      - main
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest

    env:
      SUPABASE_ACCESS_TOKEN: YOUR_SUPABASE_ACCESS_TOKEN
      PROJECT_ID: YOUR_SUPABASE_PROJECT_ID

    steps:
      - uses: actions/checkout@v4

      - uses: supabase/setup-cli@v1
        with:
          version: latest

      - run: supabase functions deploy --project-ref $PROJECT_ID
```

Since Supabase CLI [v1.62.0](https://github.com/supabase/cli/releases/tag/v1.62.0) you can deploy all functions with a single command.

Individual function configuration like [JWT verification](/docs/guides/cli/config#functions.function_name.verify_jwt) and [import map location](/docs/guides/cli/config#functions.function_name.import_map) can be set via the `config.toml` file.

```toml
[functions.hello-world]
verify_jwt = false
```


# Image Manipulation



Supabase Storage has [out-of-the-box support](https://supabase.com/docs/guides/storage/serving/image-transformations?queryGroups=language\&language=js) for the most common image transformations and optimizations you need.
If you need to do anything custom beyond what Supabase Storage provides, you can use Edge Functions to write custom image manipulation scripts.

In this example, we will use [`magick-wasm`](https://github.com/dlemstra/magick-wasm) to perform image manipulations. `magick-wasm` is the WebAssembly port of the popular ImageMagick library and supports processing over 100 file formats.


### Prerequisites

Make sure you have the latest version of the [Supabase CLI](https://supabase.com/docs/guides/cli#installation) installed.


### Create the Edge Function

Create a new function locally:

```bash
supabase functions new image-blur

```


### Write the function

In this example, we are implementing a function allowing users to upload an image and get a blurred thumbnail.

Here's the implementation in `index.ts` file:


### Test it locally

You can test the function locally by running:

```bash
supabase start
supabase functions serve --no-verify-jwt

```

Then, make a request using `curl` or your favorite API testing tool.

```bash
curl --location '<http://localhost:54321/functions/v1/image-blur>' \\
--form 'file=@"/path/to/image.png"'
--output '/path/to/output.png'

```

If you open the `output.png` file you will find a transformed version of your original image.


### Deploy to your hosted project

Now, let's deploy the function to your Supabase project.

```bash
supabase link
supabase functions deploy image-blur

```


# Generating OG Images



Generate Open Graph images with Deno and Supabase Edge Functions. [View on GitHub](https://github.com/supabase/supabase/tree/master/examples/edge-functions/supabase/functions/opengraph).


## Code

Create a `handler.tsx` file to construct the OG image in React:

```tsx handler.tsx
import React from 'https://esm.sh/react@18.2.0'
import { ImageResponse } from 'https://deno.land/x/og_edge@0.0.4/mod.ts'

export default function handler(req: Request) {
  return new ImageResponse(
    (
      <div
        style={{
          width: '100%',
          height: '100%',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
          fontSize: 128,
          background: 'lavender',
        }}
      >
        Hello OG Image!
      </div>
    )
  )
}
```

Create an `index.ts` file to execute the handler on incoming requests:

```ts index.ts
import handler from './handler.tsx'

console.log('Hello from og-image Function!')

Deno.serve(handler)
```


# Sending Push Notifications



Push notifications are an important part of any mobile app. They allow you to send notifications to your users even when they are not using your app. This guide will show you how to send push notifications to different mobile app frameworks from your Supabase edge functions.


# Rate Limiting Edge Functions



[Redis](https://redis.io/docs/about/) is an open source (BSD licensed), in-memory data structure store used as a database, cache, message broker, and streaming engine. It is optimized for atomic operations like incrementing a value, for example for a view counter or rate limiting. We can even rate limit based on the user ID from Supabase Auth!

[Upstash](https://upstash.com/) provides an HTTP/REST based Redis client which is ideal for serverless use-cases and therefore works well with Supabase Edge Functions.

Find the code on [GitHub](https://github.com/supabase/supabase/tree/master/examples/edge-functions/supabase/functions/upstash-redis-ratelimit).


# Taking Screenshots with Puppeteer



[Puppeteer](https://pptr.dev/) is a handy tool to programmatically take screenshots and generate PDFs. However, trying to do so in Edge Functions can be challenging due to the size restrictions. Luckily there is a [serverless browser offering available](https://www.browserless.io/) that we can connect to via WebSockets.

Find the code on [GitHub](https://github.com/supabase/supabase/tree/master/examples/edge-functions/supabase/functions/puppeteer).


# Semantic Search

Semantic Search with pgvector and Supabase Edge Functions

[Semantic search](/docs/guides/ai/semantic-search) interprets the meaning behind user queries rather than exact [keywords](/docs/guides/ai/keyword-search). It uses machine learning to capture the intent and context behind the query, handling language nuances like synonyms, phrasing variations, and word relationships.

Since Supabase Edge Runtime [v1.36.0](https://github.com/supabase/edge-runtime/releases/tag/v1.36.0) you can run the [`gte-small` model](https://huggingface.co/Supabase/gte-small) natively within Supabase Edge Functions without any external dependencies! This allows you to generate text embeddings without calling any external APIs!

In this tutorial you're implementing three parts:

1.  A [`generate-embedding`](https://github.com/supabase/supabase/tree/master/examples/ai/edge-functions/supabase/functions/generate-embedding/index.ts) database webhook edge function which generates embeddings when a content row is added (or updated) in the [`public.embeddings`](https://github.com/supabase/supabase/tree/master/examples/ai/edge-functions/supabase/migrations/20240408072601_embeddings.sql) table.
2.  A [`query_embeddings` Postgres function](https://github.com/supabase/supabase/tree/master/examples/ai/edge-functions/supabase/migrations/20240410031515_vector-search.sql) which allows us to perform similarity search from an Edge Function via [Remote Procedure Call (RPC)](https://supabase.com/docs/guides/database/functions?language=js).
3.  A [`search` edge function](https://github.com/supabase/supabase/tree/master/examples/ai/edge-functions/supabase/functions/search/index.ts) which generates the embedding for the search term, performs the similarity search via RPC function call, and returns the result.

You can find the complete example code on [GitHub](https://github.com/supabase/supabase/tree/master/examples/ai/edge-functions)


### Create the database table and webhook

Given the [following table definition](https://github.com/supabase/supabase/blob/master/examples/ai/edge-functions/supabase/migrations/20240408072601_embeddings.sql):

```sql
create extension if not exists vector with schema extensions;

create table embeddings (
  id bigint primary key generated always as identity,
  content text not null,
  embedding vector (384)
);
alter table embeddings enable row level security;

create index on embeddings using hnsw (embedding vector_ip_ops);
```

You can deploy the [following edge function](https://github.com/supabase/supabase/blob/master/examples/ai/edge-functions/supabase/functions/generate-embedding/index.ts) as a [database webhook](/docs/guides/database/webhooks) to generate the embeddings for any text content inserted into the table:

```tsx
const model = new Supabase.ai.Session('gte-small')

Deno.serve(async (req) => {
  const payload: WebhookPayload = await req.json()
  const { content, id } = payload.record

  // Generate embedding.
  const embedding = await model.run(content, {
    mean_pool: true,
    normalize: true,
  })

  // Store in database.
  const { error } = await supabase
    .from('embeddings')
    .update({ embedding: JSON.stringify(embedding) })
    .eq('id', id)
  if (error) console.warn(error.message)

  return new Response('ok')
})
```


## Create a Database Function and RPC

With the embeddings now stored in your Postgres database table, you can query them from Supabase Edge Functions by utilizing [Remote Procedure Calls (RPC)](/docs/guides/database/functions?language=js).

Given the [following Postgres Function](https://github.com/supabase/supabase/blob/master/examples/ai/edge-functions/supabase/migrations/20240410031515_vector-search.sql):

```sql
-- Matches document sections using vector similarity search on embeddings
--
-- Returns a setof embeddings so that we can use PostgREST resource embeddings (joins with other tables)
-- Additional filtering like limits can be chained to this function call
create or replace function query_embeddings(embedding vector(384), match_threshold float)
returns setof embeddings
language plpgsql
as $$
begin
  return query
  select *
  from embeddings

  -- The inner product is negative, so we negate match_threshold
  where embeddings.embedding <#> embedding < -match_threshold

  -- Our embeddings are normalized to length 1, so cosine similarity
  -- and inner product will produce the same query results.
  -- Using inner product which can be computed faster.
  --
  -- For the different distance functions, see https://github.com/pgvector/pgvector
  order by embeddings.embedding <#> embedding;
end;
$$;
```


## Query vectors in Supabase Edge Functions

You can use `supabase-js` to first generate the embedding for the search term and then invoke the Postgres function to find the relevant results from your stored embeddings, right from your [Supabase Edge Function](https://github.com/supabase/supabase/blob/master/examples/ai/edge-functions/supabase/functions/search/index.ts):

```tsx
const model = new Supabase.ai.Session('gte-small')

Deno.serve(async (req) => {
  const { search } = await req.json()
  if (!search) return new Response('Please provide a search param!')
  // Generate embedding for search term.
  const embedding = await model.run(search, {
    mean_pool: true,
    normalize: true,
  })

  // Query embeddings.
  const { data: result, error } = await supabase
    .rpc('query_embeddings', {
      embedding,
      match_threshold: 0.8,
    })
    .select('content')
    .limit(3)
  if (error) {
    return Response.json(error)
  }

  return Response.json({ search, result })
})
```

You now have AI powered semantic search set up without any external dependencies! Just you, pgvector, and Supabase Edge Functions!


# Sending Emails



Sending emails from Edge Functions using the [Resend API](https://resend.com/).


### Prerequisites

To get the most out of this guide, you’ll need to:

*   [Create an API key](https://resend.com/api-keys)
*   [Verify your domain](https://resend.com/domains)

Make sure you have the latest version of the [Supabase CLI](https://supabase.com/docs/guides/cli#installation) installed.


### 1. Create Supabase function

Create a new function locally:

```bash
supabase functions new resend
```

Store the `RESEND_API_KEY` in your `.env` file.


### 2. Edit the handler function

Paste the following code into the `index.ts` file:

```tsx
const RESEND_API_KEY = Deno.env.get('RESEND_API_KEY')

const handler = async (_request: Request): Promise<Response> => {
  const res = await fetch('https://api.resend.com/emails', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${RESEND_API_KEY}`,
    },
    body: JSON.stringify({
      from: 'onboarding@resend.dev',
      to: 'delivered@resend.dev',
      subject: 'hello world',
      html: '<strong>it works!</strong>',
    }),
  })

  const data = await res.json()

  return new Response(JSON.stringify(data), {
    status: 200,
    headers: {
      'Content-Type': 'application/json',
    },
  })
}

Deno.serve(handler)
```


### 3. Deploy and send email

Run function locally:

```bash
supabase start
supabase functions serve --no-verify-jwt --env-file .env
```

Test it: http://localhost:54321/functions/v1/resend

Deploy function to Supabase:

```bash
supabase functions deploy resend --no-verify-jwt
```

Open the endpoint URL to send an email:


### 4. Try it yourself

Find the complete example on [GitHub](https://github.com/resendlabs/resend-supabase-edge-functions-example).


# Monitoring with Sentry



Add the [Sentry Deno SDK](https://docs.sentry.io/platforms/javascript/guides/deno/) to your Supabase Edge Functions to track exceptions and get notified of errors or performance issues.


### Prerequisites

*   [Create a Sentry account](https://sentry.io/signup/).
*   Make sure you have the latest version of the [Supabase CLI](https://supabase.com/docs/guides/cli#installation) installed.


### 1. Create Supabase function

Create a new function locally:

```bash
supabase functions new sentryfied
```


### 2. Add the Sentry Deno SDK

Handle exceptions within your function and send them to Sentry.

```tsx
import * as Sentry from 'https://deno.land/x/sentry/index.mjs'

Sentry.init({
  // https://docs.sentry.io/product/sentry-basics/concepts/dsn-explainer/#where-to-find-your-dsn
  dsn: SENTRY_DSN,
  defaultIntegrations: false,
  // Performance Monitoring
  tracesSampleRate: 1.0,
  // Set sampling rate for profiling - this is relative to tracesSampleRate
  profilesSampleRate: 1.0,
})

// Set region and execution_id as custom tags
Sentry.setTag('region', Deno.env.get('SB_REGION'))
Sentry.setTag('execution_id', Deno.env.get('SB_EXECUTION_ID'))

Deno.serve(async (req) => {
  try {
    const { name } = await req.json()
    // This will throw, as `name` in our example call will be `undefined`
    const data = {
      message: `Hello ${name}!`,
    }

    return new Response(JSON.stringify(data), { headers: { 'Content-Type': 'application/json' } })
  } catch (e) {
    Sentry.captureException(e)
    return new Response(JSON.stringify({ msg: 'error' }), {
      status: 500,
      headers: { 'Content-Type': 'application/json' },
    })
  }
})
```


### 3. Deploy and test

Run function locally:

```bash
supabase start
supabase functions serve --no-verify-jwt
```

Test it: http://localhost:54321/functions/v1/sentryfied

Deploy function to Supabase:

```bash
supabase functions deploy sentryfied --no-verify-jwt
```


### 4. Try it yourself

Find the complete example on [GitHub](https://github.com/supabase/supabase/tree/master/examples/edge-functions/supabase/functions/sentryfied/index.ts).


## Working with scopes

Sentry Deno SDK currently do not support `Deno.serve` instrumentation, which means that there is no scope separation between requests.
Because of that, when the Edge Functions runtime is reused between multiple requests, all globally captured breadcrumbs and contextual data
will be shared, which is not the desired behavior. To work around this, all default integrations in the example code above are disabled,
and you should be relying on [`withScope`](https://docs.sentry.io/platforms/javascript/enriching-events/scopes/#using-withscope) to encapsulate
all Sentry SDK API calls, or [pass context directly](https://docs.sentry.io/platforms/javascript/enriching-events/context/#passing-context-directly)
to the `captureException` or `captureMessage` calls.


# Slack Bot Mention Edge Function



The Slack Bot Mention Edge Function allows you to process mentions in Slack and respond accordingly.


## Configuring Slack apps

For your bot to seamlessly interact with Slack, you'll need to configure Slack Apps:

1.  Navigate to the Slack Apps page.
2.  Under "Event Subscriptions," add the URL of the `slack-bot-mention` function and click to verify the URL.
3.  The Edge function will respond, confirming that everything is set up correctly.
4.  Add `app-mention` in the events the bot will subscribe to.


## Creating the Edge Function

Deploy the following code as an Edge function using the CLI:

```bash
supabase --project-ref nacho_slacker secrets \
set SLACK_TOKEN=<xoxb-0000000000-0000000000-01010101010nacho101010>
```

Here's the code of the Edge Function, you can change the response to handle the text received:

```ts index.ts
import { WebClient } from 'https://deno.land/x/slack_web_api@6.7.2/mod.js'

const slackBotToken = Deno.env.get('SLACK_TOKEN') ?? ''
const botClient = new WebClient(slackBotToken)

console.log(`Slack URL verification function up and running!`)
Deno.serve(async (req) => {
  try {
    const reqBody = await req.json()
    console.log(JSON.stringify(reqBody, null, 2))
    const { token, challenge, type, event } = reqBody

    if (type == 'url_verification') {
      return new Response(JSON.stringify({ challenge }), {
        headers: { 'Content-Type': 'application/json' },
        status: 200,
      })
    } else if (event.type == 'app_mention') {
      const { user, text, channel, ts } = event
      // Here you should process the text received and return a response:
      const response = await botClient.chat.postMessage({
        channel: channel,
        text: `Hello <@${user}>!`,
        thread_ts: ts,
      })
      return new Response('ok', { status: 200 })
    }
  } catch (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      headers: { 'Content-Type': 'application/json' },
      status: 500,
    })
  }
})
```


# Handling Stripe Webhooks



Handling signed Stripe Webhooks with Edge Functions. [View on GitHub](https://github.com/supabase/supabase/blob/master/examples/edge-functions/supabase/functions/stripe-webhooks/index.ts).


# Building a Telegram Bot



Handle Telegram Bot Webhooks with the [grammY framework](https://grammy.dev/). grammY is an open source Telegram Bot Framework which makes it easy to handle and respond to incoming messages. [View on GitHub](https://github.com/supabase/supabase/tree/master/examples/edge-functions/supabase/functions/telegram-bot).


# Upstash Redis



A Redis counter example that stores a [hash](https://redis.io/commands/hincrby/) of function invocation count per region. Find the code on [GitHub](https://github.com/supabase/supabase/tree/master/examples/edge-functions/supabase/functions/upstash-redis-counter).


## Redis database setup

Create a Redis database using the [Upstash Console](https://console.upstash.com/) or [Upstash CLI](https://github.com/upstash/cli).

Select the `Global` type to minimize the latency from all edge locations. Copy the `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` to your .env file.

You'll find them under **Details > REST API > .env**.

```bash
cp supabase/functions/upstash-redis-counter/.env.example supabase/functions/upstash-redis-counter/.env
```


## Code

Make sure you have the latest version of the [Supabase CLI installed](/docs/guides/cli#installation).

Create a new function in your project:

```bash
supabase functions new upstash-redis-counter
```

And add the code to the `index.ts` file:

```ts index.ts
import { Redis } from 'https://deno.land/x/upstash_redis@v1.19.3/mod.ts'

console.log(`Function "upstash-redis-counter" up and running!`)

Deno.serve(async (_req) => {
  try {
    const redis = new Redis({
      url: Deno.env.get('UPSTASH_REDIS_REST_URL')!,
      token: Deno.env.get('UPSTASH_REDIS_REST_TOKEN')!,
    })

    const deno_region = Deno.env.get('DENO_REGION')
    if (deno_region) {
      // Increment region counter
      await redis.hincrby('supa-edge-counter', deno_region, 1)
    } else {
      // Increment localhost counter
      await redis.hincrby('supa-edge-counter', 'localhost', 1)
    }

    // Get all values
    const counterHash: Record<string, number> | null = await redis.hgetall('supa-edge-counter')
    const counters = Object.entries(counterHash!)
      .sort(([, a], [, b]) => b - a) // sort desc
      .reduce((r, [k, v]) => ({ total: r.total + v, regions: { ...r.regions, [k]: v } }), {
        total: 0,
        regions: {},
      })

    return new Response(JSON.stringify({ counters }), { status: 200 })
  } catch (error) {
    return new Response(JSON.stringify({ error: error.message }), { status: 200 })
  }
})
```


## Run locally

```bash
supabase start
supabase functions serve --no-verify-jwt --env-file supabase/functions/upstash-redis-counter/.env
```

Navigate to http://localhost:54321/functions/v1/upstash-redis-counter.


## Deploy

```bash
supabase functions deploy upstash-redis-counter --no-verify-jwt
supabase secrets set --env-file supabase/functions/upstash-redis-counter/.env
```


# Type-Safe SQL with Kysely



Supabase Edge Functions can [connect directly to your Postgres database](/docs/guides/functions/connect-to-postgres) to execute SQL queries. [Kysely](https://github.com/kysely-org/kysely#kysely) is a type-safe and autocompletion-friendly typescript SQL query builder.

Combining Kysely with Deno Postgres gives you a convenient developer experience for interacting directly with your Postgres database.


## Code

Find the example on [GitHub](https://github.com/supabase/supabase/tree/master/examples/edge-functions/supabase/functions/kysely-postgres)

Get your database connection credentials from your [Supabase Dashboard](https://supabase.com/dashboard/project/_/settings/database) and store them in an `.env` file:

```bash .env
DB_HOSTNAME=
DB_PASSWORD=
DB_SSL_CERT="-----BEGIN CERTIFICATE-----
GET YOUR CERT FROM YOUR PROJECT DASHBOARD
-----END CERTIFICATE-----"
```

Create a `DenoPostgresDriver.ts` file to manage the connection to Postgres via [deno-postgres](https://deno-postgres.com/):

```ts DenoPostgresDriver.ts
import {
  CompiledQuery,
  DatabaseConnection,
  Driver,
  PostgresCursorConstructor,
  QueryResult,
  TransactionSettings,
} from 'https://esm.sh/kysely@0.23.4'
import { freeze, isFunction } from 'https://esm.sh/kysely@0.23.4/dist/esm/util/object-utils.js'
import { extendStackTrace } from 'https://esm.sh/kysely@0.23.4/dist/esm/util/stack-trace-utils.js'
import { Pool, PoolClient } from 'https://deno.land/x/postgres@v0.17.0/mod.ts'

export interface PostgresDialectConfig {
  pool: Pool | (() => Promise<Pool>)
  cursor?: PostgresCursorConstructor
  onCreateConnection?: (connection: DatabaseConnection) => Promise<void>
}

const PRIVATE_RELEASE_METHOD = Symbol()

export class PostgresDriver implements Driver {
  readonly #config: PostgresDialectConfig
  readonly #connections = new WeakMap<PoolClient, DatabaseConnection>()
  #pool?: Pool

  constructor(config: PostgresDialectConfig) {
    this.#config = freeze({ ...config })
  }

  async init(): Promise<void> {
    this.#pool = isFunction(this.#config.pool) ? await this.#config.pool() : this.#config.pool
  }

  async acquireConnection(): Promise<DatabaseConnection> {
    const client = await this.#pool!.connect()
    let connection = this.#connections.get(client)

    if (!connection) {
      connection = new PostgresConnection(client, {
        cursor: this.#config.cursor ?? null,
      })
      this.#connections.set(client, connection)

      // The driver must take care of calling `onCreateConnection` when a new
      // connection is created. The `pg` module doesn't provide an async hook
      // for the connection creation. We need to call the method explicitly.
      if (this.#config?.onCreateConnection) {
        await this.#config.onCreateConnection(connection)
      }
    }

    return connection
  }

  async beginTransaction(
    connection: DatabaseConnection,
    settings: TransactionSettings
  ): Promise<void> {
    if (settings.isolationLevel) {
      await connection.executeQuery(
        CompiledQuery.raw(`start transaction isolation level ${settings.isolationLevel}`)
      )
    } else {
      await connection.executeQuery(CompiledQuery.raw('begin'))
    }
  }

  async commitTransaction(connection: DatabaseConnection): Promise<void> {
    await connection.executeQuery(CompiledQuery.raw('commit'))
  }

  async rollbackTransaction(connection: DatabaseConnection): Promise<void> {
    await connection.executeQuery(CompiledQuery.raw('rollback'))
  }

  async releaseConnection(connection: PostgresConnection): Promise<void> {
    connection[PRIVATE_RELEASE_METHOD]()
  }

  async destroy(): Promise<void> {
    if (this.#pool) {
      const pool = this.#pool
      this.#pool = undefined
      await pool.end()
    }
  }
}

interface PostgresConnectionOptions {
  cursor: PostgresCursorConstructor | null
}

class PostgresConnection implements DatabaseConnection {
  #client: PoolClient
  #options: PostgresConnectionOptions

  constructor(client: PoolClient, options: PostgresConnectionOptions) {
    this.#client = client
    this.#options = options
  }

  async executeQuery<O>(compiledQuery: CompiledQuery): Promise<QueryResult<O>> {
    try {
      const result = await this.#client.queryObject<O>(compiledQuery.sql, [
        ...compiledQuery.parameters,
      ])

      if (
        result.command === 'INSERT' ||
        result.command === 'UPDATE' ||
        result.command === 'DELETE'
      ) {
        const numAffectedRows = BigInt(result.rowCount || 0)

        return {
          numUpdatedOrDeletedRows: numAffectedRows,
          numAffectedRows,
          rows: result.rows ?? [],
        } as any
      }

      return {
        rows: result.rows ?? [],
      }
    } catch (err) {
      throw extendStackTrace(err, new Error())
    }
  }

  async *streamQuery<O>(
    _compiledQuery: CompiledQuery,
    chunkSize: number
  ): AsyncIterableIterator<QueryResult<O>> {
    if (!this.#options.cursor) {
      throw new Error(
        "'cursor' is not present in your postgres dialect config. It's required to make streaming work in postgres."
      )
    }

    if (!Number.isInteger(chunkSize) || chunkSize <= 0) {
      throw new Error('chunkSize must be a positive integer')
    }

    // stream not available
    return null
  }

  [PRIVATE_RELEASE_METHOD](): void {
    this.#client.release()
  }
}
```

Create an `index.ts` file to execute a query on incoming requests:

```ts index.ts
import { serve } from 'https://deno.land/std@0.175.0/http/server.ts'
import { Pool } from 'https://deno.land/x/postgres@v0.17.0/mod.ts'
import {
  Kysely,
  Generated,
  PostgresAdapter,
  PostgresIntrospector,
  PostgresQueryCompiler,
} from 'https://esm.sh/kysely@0.23.4'
import { PostgresDriver } from './DenoPostgresDriver.ts'

console.log(`Function "kysely-postgres" up and running!`)

interface AnimalTable {
  id: Generated<bigint>
  animal: string
  created_at: Date
}

// Keys of this interface are table names.
interface Database {
  animals: AnimalTable
}

// Create a database pool with one connection.
const pool = new Pool(
  {
    tls: { caCertificates: [Deno.env.get('DB_SSL_CERT')!] },
    database: 'postgres',
    hostname: Deno.env.get('DB_HOSTNAME'),
    user: 'postgres',
    port: 5432,
    password: Deno.env.get('DB_PASSWORD'),
  },
  1
)

// You'd create one of these when you start your app.
const db = new Kysely<Database>({
  dialect: {
    createAdapter() {
      return new PostgresAdapter()
    },
    createDriver() {
      return new PostgresDriver({ pool })
    },
    createIntrospector(db: Kysely<unknown>) {
      return new PostgresIntrospector(db)
    },
    createQueryCompiler() {
      return new PostgresQueryCompiler()
    },
  },
})

serve(async (_req) => {
  try {
    // Run a query
    const animals = await db.selectFrom('animals').select(['id', 'animal', 'created_at']).execute()

    // Neat, it's properly typed \o/
    console.log(animals[0].created_at.getFullYear())

    // Encode the result as pretty printed JSON
    const body = JSON.stringify(
      animals,
      (key, value) => (typeof value === 'bigint' ? value.toString() : value),
      2
    )

    // Return the response with the correct content type header
    return new Response(body, {
      status: 200,
      headers: {
        'Content-Type': 'application/json; charset=utf-8',
      },
    })
  } catch (err) {
    console.error(err)
    return new Response(String(err?.message ?? err), { status: 500 })
  }
})
```


# Limits

Limits applied Edge Functions in Supabase's hosted platform.

## Runtime limits

*   Maximum Memory: 256MB
*   Maximum Duration (Wall clock limit):
    This is the duration an Edge Function worker will stay active. During this period, a worker can serve multiple requests or process background tasks.
    *   Free plan: 150s
    *   Paid plans: 400s
*   Maximum CPU Time: 2s (Amount of actual time spent on the CPU per request - does not include async I/O.)
*   Request idle timeout: 150s (If an Edge Function doesn't send a response before the timeout, 504 Gateway Timeout will be returned)


## Platform limits

*   Maximum Function Size: 20MB (After bundling using CLI)
*   Maximum no. of Functions per project:
    *   Free: 100
    *   Pro: 500
    *   Team: 1000
    *   Enterprise: Unlimited
*   Maximum log message length: 10,000 characters
*   Log event threshold: 100 events per 10 seconds


## Other limits & restrictions

*   Outgoing connections to ports `25` and `587` are not allowed.
*   Serving of HTML content is only supported with [custom domains](/docs/reference/cli/supabase-domains) (Otherwise `GET` requests that return `text/html` will be rewritten to `text/plain`).
*   Web Worker API (or Node `vm` API) are not available.
*   Node Libraries that require multithreading are not supported. Examples: [`libvips`](https://github.com/libvips/libvips), [sharp](https://github.com/lovell/sharp).


# Local development

Setup local development environment for Edge Functions.

We recommend installing the Deno CLI and related tools for local development.


## Deno support

You can follow the [Deno guide](https://deno.com/manual@v1.32.5/getting_started/setup_your_environment) for setting up your development environment with your favorite editor/IDE.


## Deno with Visual Studio Code

When using VSCode, you should install both the Deno CLI and the the Deno language server [via this link](vscode:extension/denoland.vscode-deno) or by browsing the extensions in VSCode and choosing to install the *Deno* extension.


## Deno support in subfolders

You can enable the Deno language server for specific sub-paths in a workspace, while using VSCode's built-in JavaScript/TypeScript language server for all other files.

For example if you have a project like this:

    project
    ├── app
    └── supabase
      └── functions

To enable the Deno language server only for the `supabase/functions` folder, add `./supabase/functions` to the list of *Deno: Enable Paths* in the configuration. In your `.vscode/settings.json` file add:

```json
{
  "deno.enablePaths": ["./supabase/functions"],
  "deno.importMap": "./supabase/functions/import_map.json"
}
```


## Multi-root workspaces in VSCode

We recommend using `deno.enablePaths` mentioned above as it's easier to manage, however if you like [multi-root workspaces](https://code.visualstudio.com/docs/editor/workspaces#_multiroot-workspaces) you can use these as an alternative.

For example, see this `edge-functions.code-workspace` configuration for a CRA (create react app) client with Supabase Edge Functions. You can find the complete example on [GitHub](https://github.com/supabase/supabase/tree/master/examples/edge-functions).

```json
{
  "folders": [
    {
      "name": "project-root",
      "path": "./"
    },
    {
      "name": "client",
      "path": "app"
    },
    {
      "name": "supabase-functions",
      "path": "supabase/functions"
    }
  ],
  "settings": {
    "files.exclude": {
      "node_modules/": true,
      "app/": true,
      "supabase/functions/": true
    },
    "deno.importMap": "./supabase/functions/import_map.json"
  }
}
```


# Developing Edge Functions locally

Get started with Edge Functions on your local machine.

Let's create a basic Edge Function on your local machine and then invoke it using the Supabase CLI.


## Initialize a project

Create a new Supabase project in a folder on your local machine:

```bash
supabase init
```


## Create an Edge Function

Let's create a new Edge Function called `hello-world` inside your project:

```bash
supabase functions new hello-world
```

This creates a function stub in your `supabase` folder:

```bash
└── supabase
    ├── functions
    │   └── hello-world
    │   │   └── index.ts ## Your function code
    └── config.toml
```


## How to write the code

The generated function uses native [Deno.serve](https://docs.deno.com/runtime/manual/runtime/http_server_apis) to handle requests. It gives you access to `Request` and `Response` objects.

Here's the generated Hello World Edge Function, that accepts a name in the `Request` and responds with a greeting:

```tsx
Deno.serve(async (req) => {
  const { name } = await req.json()
  const data = {
    message: `Hello ${name}!`,
  }

  return new Response(JSON.stringify(data), { headers: { 'Content-Type': 'application/json' } })
})
```


## Running Edge Functions locally

You can run your Edge Function locally using [`supabase functions serve`](/docs/reference/cli/usage#supabase-functions-serve):

```bash
supabase start # start the supabase stack
supabase functions serve # start the Functions watcher
```

The `functions serve` command has hot-reloading capabilities. It will watch for any changes to your files and restart the Deno server.


## Invoking Edge Functions locally

While serving your local Edge Function, you can invoke it using curl or one of the client libraries.
To call the function from a browser you need to handle CORS requests. See [CORS](/docs/guides/functions/cors).

You should see the response `{ "message":"Hello Functions!" }`.

If you execute the function with a different payload, the response will change.

Modify the `--data '{"name":"Functions"}'` line to `--data '{"name":"World"}'` and try invoking the command again.


## Next steps

Check out the [Deploy to Production](/docs/guides/functions/deploy) guide to make your Edge Function available to the world.

See the [development tips](/docs/guides/functions/development-tips) for best practices.


# Logging

How to access logs for your Edge Functions.

Logs are provided for each function invocation, locally and in hosted environments.


## How to access logs


### Hosted

You can access both tools from the [Functions section](https://supabase.com/dashboard/project/_/functions) of the Dashboard. Select your function from the list, and click `Invocations` or `Logs`:

*   **Invocations**: shows the Request and Response for each execution. You can see the headers, body, status code, and duration of each invocation. You can also filter the invocations by date, time, or status code.
*   **Logs**: shows any platform events, uncaught exceptions, and custom log events. You can see the timestamp, level, and message of each log event. You can also filter the log events by date, time, or level.

![Function invocations.](/docs/img/guides/functions/function-logs.png)


### Local

When [developing locally](/docs/guides/functions/local-development) you will see error messages and console log statements printed to your local terminal window.


## Events that get logged

*   **Uncaught exceptions**: Uncaught exceptions thrown by a function during execution are automatically logged. You can see the error message and stack trace in the Logs tool.
*   **Custom log events**: You can use `console.log`, `console.error`, and `console.warn` in your code to emit custom log events. These events also appear in the Logs tool.
*   **Boot and Shutdown Logs**: The Logs tool extends its coverage to include logs for the boot and shutdown of functions.

Here is an example of how to use custom logs events in your function:

```typescript
Deno.serve(async (req) => {
  try {
    const { name } = await req.json()

    if (!name) {
      console.warn('Empty name provided')
    }

    const data = {
      message: `Hello ${name || 'Guest'}!`, // Provide a default value if name is empty
    }

    console.log(`Name: ${name}`)

    return new Response(JSON.stringify(data), { headers: { 'Content-Type': 'application/json' } })
  } catch (error) {
    console.error(`Error processing request: ${error}`)
    return new Response(JSON.stringify({ error: 'Internal Server Error' }), {
      status: 500,
      headers: { 'Content-Type': 'application/json' },
    })
  }
})
```


## Logging tips


### Logging request headers

When debugging Edge Functions, a common mistake is to try to log headers to the developer console via code like this:

```ts index.ts
Deno.serve(async (req) => {
  const headers = JSON.stringify(req.headers)
  console.log(`Request headers: ${headers}`)
  // OR
  console.log(`Request headers: ${JSON.stringify(req.headers)}`)
  return new Response('ok', {
    headers: {
      'Content-Type': 'application/json',
    },
    status: 200,
  })
})
```

Both attempts will give as output the string `"{}"`, even though retrieving the value using `request.headers.get("Your-Header-Name")` will indeed give you the correct value. This behavior mirrors that of browsers.

The reason behind this behavior is that [Headers](https://developer.mozilla.org/en-US/docs/Web/API/Headers) objects don't store headers in JavaScript properties that can be enumerated. As a result, neither the developer console nor the JSON stringifier can properly interpret the names and values of the headers. Essentially, it's not an empty object, but rather an opaque one.

However, `Headers` objects are iterable. You can utilize this feature to craft a couple of succinct one-liners for debugging and printing headers.


### Convert headers into an object with `Object.fromEntries`:

You can use `Object.fromEntries` which is a call to convert the headers into an object:

```ts index.ts
Deno.serve(async (req) => {
  let headersObject = Object.fromEntries(req.headers)
  let requestHeaders = JSON.stringify(headersObject, null, 2)
  console.log(`Request headers: ${requestHeaders}`)
  return new Response('ok', {
    headers: {
      'Content-Type': 'application/json',
    },
    status: 200,
  })
})
```

This results in something like:

    Request headers: {
        "accept": "*/*",
        "accept-encoding": "gzip",
        "authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6InN1cGFuYWNobyIsInJvbGUiOiJhbm9uIiwieW91IjoidmVyeSBzbmVha3ksIGh1aD8iLCJpYXQiOjE2NTQ1NDA5MTYsImV4cCI6MTk3MDExNjkxNn0.cwBbk2tq-fUcKF1S0jVKkOAG2FIQSID7Jjvff5Do99Y",
        "cdn-loop": "cloudflare; subreqs=1",
        "cf-ew-via": "15",
        "cf-ray": "8597a2fcc558a5d7-GRU",
        "cf-visitor": "{\"scheme\":\"https\"}",
        "cf-worker": "supabase.co",
        "content-length": "20",
        "content-type": "application/x-www-form-urlencoded",
        "host": "edge-runtime.supabase.com",
        "my-custom-header": "abcd",
        "user-agent": "curl/8.4.0",
        "x-deno-subhost": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsImtpZCI6InN1cGFiYXNlIn0.eyJkZXBsb3ltZW50X2lkIjoic3VwYW5hY2hvX2M1ZGQxMWFiLTFjYmUtNDA3NS1iNDAxLTY3ZTRlZGYxMjVjNV8wMDciLCJycGNfcm9vdCI6Imh0dHBzOi8vc3VwYWJhc2Utb3JpZ2luLmRlbm8uZGV2L3YwLyIsImV4cCI6MTcwODYxMDA4MiwiaWF0IjoxNzA4NjA5MTgyfQ.-fPid2kEeEM42QHxWeMxxv2lJHZRSkPL-EhSH0r_iV4",
        "x-forwarded-host": "edge-runtime.supabase.com",
        "x-forwarded-port": "443",
        "x-forwarded-proto": "https"
    }


# Pricing



For a detailed explanation of how charges are calculated, refer to [Manage Edge Function Invocations usage](/docs/guides/platform/manage-your-usage/edge-function-invocations).


# Developing Edge Functions with Supabase

Get started with Edge Functions on the Supabase dashboard.

In this guide we'll cover how to create a basic Edge Function on the Supabase dashboard, and access it using the Supabase CLI.


## Deploy from Dashboard

Go to your project > Edge Functions > Deploy a new function > Via Editor

This will scaffold a new function for you. You can choose from Templates some of the pre-defined functions for common use cases.

Modify the function as needed, name it, and click `Deploy function`.

Your function is now active. Navigate to the function's details page, and click on the test button.

You can test your function by providing the expected HTTP method, headers, query parameters, and request body. You can also change the authorization token passed (e.g., anon key or a user key).


## Access deployed functions via Supabase CLI

Now that your function is deployed, you can access it from your local development environment.
Here's how:

1.  **Link your project** to your local environment.

    You can find your project reference ID in the URL of your Supabase dashboard or in the project settings.

    ```bash
    supabase link --project-ref your-project-ref
    ```

2.  **List all Functions** in the linked Supabase project.

    ```bash
    supabase functions list
    ```

3.  **Access the specific function** you want to work on.

    ```bash
    supabase functions download function-name
    ```

4.  **Make local edits** to the function code as needed.

5.  **Run your function locally** before redeploying.

    ```bash
    supabase functions serve function-name
    ```

6.  **Redeploy** when you're ready with your changes.

    ```bash
    supabase functions deploy function-name
    ```


## Deploy via Assistant

You can also leverage the Supabase Assistant to help you write and deploy edge functions.

Go to your project > Edge Functions > Click on the Assistant icon to Create with Supabase Assistant

This brings up an assistant window with a pre-filled prompt for generating edge functions.
Write up your Edge Function requirement, and let Supabase Assistant do the rest.

Click Deploy and the Assistant will automatically deploy your function.

This function requires an OpenAI API key. You can add the key in your Edge Functions secrets page, or ask Assistant for help.

1.  Navigate to your Edge Functions > Secrets page.
2.  Look for the option to add environment variables.
3.  Add a new environment variable with the key `OPENAI_API_KEY` and set its value to your actual OpenAI API key.

Once you've set this environment variable, your edge functions will be able to access the OPENAI\_API\_KEY securely without hardcoding it into the function code. This is a best practice for keeping sensitive information safe.

With your variable set, you can test by sending a request via the dashboard. Navigate to the function's details page, and click on the test button. Then provide a Request Body your function expects.


## Editing functions from the Dashboard

1.  From the functions page, click on the function you want to edit. From the function page, click on the Code tab.

2.  This opens up a code editor in the dashboard where you can see your deployed function's code.

3.  Modify the code as needed, then click Deploy updates. This will overwrite the existing deployment with the newly edited function code.


## Next steps

Check out the [Local development](/docs/guides/functions/local-quickstart) guide for more details on working with Edge Functions.

Read on for some [common development tips](/docs/guides/functions/development-tips).


# Regional Invocations

How to execute an Edge Function in a particular region.

Edge Functions are executed in the region closest to the user making the request. This helps to reduce network latency and provide faster responses to the user.

However, if your Function performs lots of database or storage operations, invoking the Function in the same region as your database may provide better performance. Some situations where this might be helpful include:

*   Bulk adding and editing records in your database
*   Uploading files

Supabase provides an option to specify the region when invoking the Function.


## Using the `x-region` header

Use the `x-region` HTTP header when calling an Edge Function to determine where the Function should be executed:

You can verify the execution region by looking at the `x-sb-edge-region` HTTP header in the response. You can also find it as metadata in [Edge Function Logs](/docs/guides/functions/logging).


## Available regions

These are the currently supported region values you can provide for `x-region` header.

*   `ap-northeast-1`
*   `ap-northeast-2`
*   `ap-south-1`
*   `ap-southeast-1`
*   `ap-southeast-2`
*   `ca-central-1`
*   `eu-central-1`
*   `eu-west-1`
*   `eu-west-2`
*   `eu-west-3`
*   `sa-east-1`
*   `us-east-1`
*   `us-west-1`
*   `us-west-2`


## Using the client library

You can also specify the region when invoking a Function using the Supabase client library:

```js
import { createClient, FunctionRegion } from '@supabase/supabase-js'
const supabase = createClient('SUPABASE_URL', 'SUPABASE_ANON_KEY')

const { data: ret, error } = await supabase.functions.invoke('my-function-name', {
  headers: { 'Content-Type': 'application/json' },
  method: 'GET',
  body: {},
  region: FunctionRegion.UsEast1,
})
```


## Handling regional outages

If you explicitly specify the region via `x-region` header, requests **will NOT** be automatically re-routed to another region and you should consider temporarily changing regions during the outage.


# Handling Routing in Functions

How to handle custom routing within Edge Functions.

Usually, an Edge Function is written to perform a single action (e.g. write a record to the database). However, if your app's logic is split into multiple Edge Functions requests to each action may seem slower.
This is because each Edge Function needs to be booted before serving a request (known as cold starts). If an action is performed less frequently (e.g. deleting a record), there is a high-chance of that function experiencing a cold-start.

One way to reduce the cold starts and increase performance of your app is to combine multiple actions into a single Edge Function. This way only one instance of the Edge Function needs to be booted and it can handle multiple requests to different actions.
For example, we can use a single Edge Function to create a typical CRUD API (create, read, update, delete records).

To combine multiple endpoints into a single Edge Function, you can use web application frameworks such as [Express](https://expressjs.com/), [Oak](https://oakserver.github.io/oak/), or [Hono](https://hono.dev).

Let's dive into some examples.


## Routing with frameworks

Here's a simple hello world example using some popular web frameworks.

Create a new function called `hello-world` using Supabase CLI:

```bash
supabase functions new hello-world
```

Copy and paste the following code:

You will notice in the above example, we created two routes - `GET` and `POST`. The path for both routes are defined as `/hello-world`.
If you run a server outside of Edge Functions, you'd usually set the root path as `/` .
However, within Edge Functions, paths should always be prefixed with the function name (in this case `hello-world`).

You can deploy the function to Supabase via:

```bash
supabase functions deploy hello-world
```

Once the function is deployed, you can try to call the two endpoints using cURL (or Postman).

```bash
# https://supabase.com/docs/guides/functions/deploy#invoking-remote-functions
curl --request GET 'https://<project_ref>.supabase.co/functions/v1/hello-world' \
  --header 'Authorization: Bearer ANON_KEY' \
```

This should print the response as `Hello World!`, meaning it was handled by the `GET` route.

Similarly, we can make a request to the `POST` route.

```bash cURL
# https://supabase.com/docs/guides/functions/deploy#invoking-remote-functions
curl --request POST 'https://<project_ref>.supabase.co/functions/v1/hello-world' \
  --header 'Authorization: Bearer ANON_KEY' \
  --header 'Content-Type: application/json' \
  --data '{ "name":"Foo" }'
```

We should see a response printing `Hello Foo!`.


## Using route parameters

We can use route parameters to capture values at specific URL segments (e.g. `/tasks/:taskId/notes/:noteId`).

Here's an example Edge Function implemented using the Framework for managing tasks using route parameters.
Keep in mind paths must be prefixed by function name (i.e. `tasks` in this example). Route parameters can only be used after the function name prefix.


## URL patterns API

If you prefer not to use a web framework, you can directly use [URL Pattern API](https://developer.mozilla.org/en-US/docs/Web/API/URL_Pattern_API) within your Edge Functions to implement routing.
This is ideal for small apps with only couple of routes and you want to have a custom matching algorithm.

Here is an example Edge Function using URL Patterns API: https://github.com/supabase/supabase/blob/master/examples/edge-functions/supabase/functions/restful-tasks/index.ts


# Scheduling Edge Functions



The hosted Supabase Platform supports the [`pg_cron` extension](/docs/guides/database/extensions/pgcron), a recurring job scheduler in Postgres.

In combination with the [`pg_net` extension](/docs/guides/database/extensions/pgnet), this allows us to invoke Edge Functions periodically on a set schedule.


## Examples


### Invoke an Edge Function every minute

Store `project_url` and `anon_key` in Supabase Vault:

```sql
select vault.create_secret('https://project-ref.supabase.co', 'project_url');
select vault.create_secret('YOUR_SUPABASE_ANON_KEY', 'anon_key');
```

Make a POST request to a Supabase Edge Function every minute:

```sql
select
  cron.schedule(
    'invoke-function-every-minute',
    '* * * * *', -- every minute
    $$
    select
      net.http_post(
          url:= (select decrypted_secret from vault.decrypted_secrets where name = 'project_url') || '/functions/v1/function-name',
          headers:=jsonb_build_object(
            'Content-type', 'application/json',
            'Authorization', 'Bearer ' || (select decrypted_secret from vault.decrypted_secrets where name = 'anon_key')
          ),
          body:=concat('{"time": "', now(), '"}')::jsonb
      ) as request_id;
    $$
  );
```


## Resources

*   [`pg_net` extension](/docs/guides/database/extensions/pgnet)
*   [`pg_cron` extension](/docs/guides/database/extensions/pgcron)


# Managing Secrets (Environment Variables)

Managing secrets and environment variables.

It's common that you will need to use environment variables or other sensitive information Edge Functions. You can manage secrets using the CLI or the Dashboard.

You can access these using Deno's built-in handler

```js
Deno.env.get('MY_SECRET_NAME')
```


## Default secrets

Edge Functions have access to these secrets by default:

*   `SUPABASE_URL`: The API gateway for your Supabase project.
*   `SUPABASE_ANON_KEY`: The `anon` key for your Supabase API. This is safe to use in a browser when you have [Row Level Security](/docs/guides/database/postgres/row-level-security) enabled.
*   `SUPABASE_SERVICE_ROLE_KEY`: The `service_role` key for your Supabase API. This is safe to use in Edge Functions, but it should NEVER be used in a browser. This key will bypass [Row Level Security](/docs/guides/database/postgres/row-level-security).
*   `SUPABASE_DB_URL`: The URL for your [Postgres database](/docs/guides/database). You can use this to connect directly to your database.


## Local secrets

You can load environment variables in two ways:

1.  Through an `.env` file placed at `supabase/functions/.env`, which is automatically loaded on `supabase start`
2.  Through the `--env-file` option for `supabase functions serve`, for example: `supabase functions serve --env-file ./path/to/.env-file`

Let's create a local file for storing our secrets, and inside it we can store a secret `MY_NAME`:

```bash
echo "MY_NAME=Yoda" >> ./supabase/.env.local
```

This creates a new file `./supabase/.env.local` for storing your local development secrets.

Now let's access this environment variable `MY_NAME` inside our Function. Anywhere in your function, add this line:

```jsx
console.log(Deno.env.get('MY_NAME'))
```

Now we can invoke our function locally, by serving it with our new `.env.local` file:

```bash
supabase functions serve --env-file ./supabase/.env.local
```

When the function starts you should see the name “Yoda” output to the terminal.


## Production secrets

You will also need to set secrets for your production Edge Functions. You can do this via the Dashboard or using the CLI.


### Using the Dashboard

1.  Visit [Edge Function Secrets Management](https://supabase.com/dashboard/project/_/settings/functions) page in your Dashboard.
2.  Add the Key and Value for your secret and press Save.
3.  Note that you can paste multiple secrets at a time.


### Using the CLI

Let's create a `.env` to help us deploy our secrets to production. In this case we'll just use the same as our local secrets:

```bash
cp ./supabase/.env.local ./supabase/.env
```

This creates a new file `./supabase/.env` for storing your production secrets.

Let's push all the secrets from the `.env` file to our remote project using [`supabase secrets set`](/docs/reference/cli/usage#supabase-secrets-set):

```bash
supabase secrets set --env-file ./supabase/.env

# You can also set secrets individually using:
supabase secrets set MY_NAME=Chewbacca
```

You don't need to re-deploy after setting your secrets.

To see all the secrets which you have set remotely, use [`supabase secrets list`](/docs/reference/cli/usage#supabase-secrets-list):

```bash
supabase secrets list
```


# Status codes

Edge Functions can return following status codes.

## 2XX Success

A successful Edge Function Response


## 3XX Redirect

The Edge Function has responded with a `Response.redirect` [API docs](https://developer.mozilla.org/en-US/docs/Web/API/Response/redirect_static)


## 4XX Client Errors


### 401 Unauthorized

If the Edge Function has `Verify JWT` option enabled, but the request was made with an invalid JWT.


### 404 Not Found

Requested Edge Function was not found.


### 405 Method Not Allowed

Edge Functions only support these HTTP methods: 'POST', 'GET', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'


## 5XX Server Errors


### 500 Internal Server Error

Edge Function threw an uncaught exception (`WORKER_ERROR`). Check Edge Function logs to find the cause.


### 503 Service Unavailable

Edge Function failed to start (`BOOT_ERROR`). Check Edge Function logs to find the cause.


### 504 Gateway Timeout

Edge Function didn't respond before the [request idle timeout](/docs/guides/functions/limits).


### 546 Resource Limit (Custom Error Code)

Edge Function execution was stopped due to a resource limit (`WORKER_LIMIT`). Edge Function logs should provide which [resource limit](/docs/guides/functions/limits) was exceeded.


# Integrating with Supabase Storage



Integrate Edge Functions with Supabase Storage to cache images on the Edge (CDN). [View on GitHub](https://github.com/supabase/supabase/tree/master/examples/edge-functions/supabase/functions/og-image-with-storage-cdn).


# Troubleshooting Common Issues

How to solve common problems and issues related to Edge Functions.

If you encounter any problems or issues with your Edge Functions, here are some tips and steps to help you resolve them.


### Unable to deploy Edge Function

*   Make sure you're on the latest version of the [Supabase CLI](/docs/guides/cli#updates).
*   If the output from the commands above does not help you to resolve the issue, open a support ticket via the Supabase Dashboard (by clicking the "Help" button at the top right) and include all output from the commands mentioned above.


### Unable to call Edge Function

If you’re unable to call your Edge Function or are experiencing any CORS issues:

*   Make sure you followed the [CORS guide](/docs/guides/functions/cors). This guide explains how to enable and configure CORS for your Edge Functions, and how to avoid common pitfalls and errors.
*   Check your function logs. Navigate to the [Functions section](https://supabase.com/dashboard/project/_/functions) in your dashboard, select your function from the list, and click `Logs`. Check for any errors or warnings that may indicate the cause of the problem.

There are two debugging tools available: Invocations and Logs. Invocations shows the Request and Response for each execution, while Logs shows any platform events, including deployments and errors.


### Edge Function takes too long to respond

If your Edge Function takes too long to respond or times out:

*   Navigate to the [Functions section](https://supabase.com/dashboard/project/_/functions) in your dashboard, select your function from the list, and click `Logs`.
*   In the logs, look for the `booted` event and check if they have consistent boot times.
    *   If the boot times are similar, it’s likely an issue with your function’s code, such as a large dependency, a slow API call, or a complex computation. You can try to optimize your code, reduce the size of your dependencies, or use caching techniques to improve the performance of your function.
    *   If only some of the `booted` events are slow, find the affected `region` in the metadata and submit a support request via the "Help" button at the top.


### Receiving 546 Error Response

The 546 error response might occur because:

*   **Memory or CPU Limits**: The function might have exhausted its memory or encountered CPU limits enforced during execution.
*   **Event Loop Completion**: If you observe "Event loop completed" in your error logs, it's likely your function is not implemented correctly. You should check your function code for any syntax errors, infinite loops, or unresolved promises that might cause this error. Or you can try running the function locally (using Supabase CLI **`functions serve`**) to see if you can debug the error. The local console should give a full stack trace on the error with line numbers of the source code. You can also refer to [Edge Functions examples](https://github.com/supabase/supabase/tree/master/examples/edge-functions) for guidance.


### Issues serving Edge Functions locally with the Supabase CLI

*   Make sure you're on the latest version of the [Supabase CLI](/docs/guides/cli#updates).
*   Run the serve command with the `-debug` flag.
*   Support engineers can then try to run the provided sample code locally and see if they can reproduce the issue.
*   Search the [Edge Runtime](https://github.com/supabase/edge-runtime) and [CLI](https://github.com/supabase/cli) repos for the error message, to see if it has been reported before.
*   If the output from the commands above does not help you to resolve the issue, open a support ticket via the Supabase Dashboard (by clicking the "Help" button at the top right) and include all output and details about your commands.


## Advanced techniques


### Monitoring Edge Function resource usage

To determine how much memory and CPU your Edge Function consumes, follow these steps:

*   Navigate to the Supabase Dashboard.
*   Go to **Edge Functions**.
*   Select the specific function by clicking on its name.
*   View the resource usage **Metrics** on the charts provided.


### Understanding CPU soft and hard limits

An isolate is like a worker that can handle multiple requests for a function. It works until a time limit of 400 seconds is reached. Now, there are two types of limits for the CPU.

1.  **Soft Limit**: When the isolate hits the soft limit, it retires. This means it won't take on any new requests, but it will finish processing the ones it's already working on. It keeps going until it either hits the hard limit for CPU time or reaches the 400-second time limit, whichever comes first.
2.  **Hard Limit**: If there are new requests after the soft limit is reached, a new isolate is created to handle them. The original isolate continues until it hits the hard limit or the time limit. This ensures that existing requests are completed, and new ones will be managed by a newly created isolate.


### Checking function boot time

Check the logs for the function. In the logs, look for a "Booted" event and note the reported boot time. If available, click on the event to access more details, including the regions from where the function was served. Investigate if the boot time is excessively high (longer than 1 second) and note any patterns or regions where it occurs. You can refer to this guide for troubleshooting [regional invocations](/docs/guides/functions/regional-invocation).


### Finding bundle size

To find the bundle size of a function, run the following command locally:

`deno info /path/to/function/index.ts`

Look for the "size" field in the output which represents the approximate bundle size of the function. You can find the accurate bundle size when you deploy your function via Supabase CLI. If the function is part of a larger application, consider examining the bundle size of the specific function independently.

The source code of a function is subject to 10MB site limit.


### Analyze dependencies

When analyzing dependencies for your Supabase Edge Functions, it's essential to review both Deno and NPM dependencies to ensure optimal performance and resource utilization.
By selectively importing only the required submodules, you can effectively reduce the size of your function's dependencies and optimize its performance.
Before finalizing your imports, ensure to review both Deno and NPM dependencies, checking for any unnecessary or redundant dependencies that can be removed. Additionally, check for outdated dependencies and update to the latest versions if possible.


#### Deno dependencies

Run `deno info`, providing the path to your input map if you use one.
Review the dependencies listed in the output. Pay attention to any significantly large dependencies, as they can contribute to increased bundle size and potential boot time issues.
Examine if there are any unnecessary or redundant dependencies that can be removed. Check for outdated dependencies and update to the latest versions if possible.

```bash
deno info --import-map=/path/to/import_map.json /path/to/function/index.ts
```


#### NPM dependencies

Additionally, if you utilize NPM modules in your Edge Functions, it's crucial to be mindful of their size and impact on the overall bundle size. While importing NPM modules, consider using the notation `import { submodule } from 'npm:package/submodule'` to selectively import specific submodules rather than importing the entire package. This approach can help minimize unnecessary overhead and streamline the execution of your function.

For example, if you only need the `Sheets` submodule from the `googleapis` package, you can import it like this:

```typescript
import { Sheets } from 'npm:@googleapis/sheets'
```


# Testing your Edge Functions

Writing Unit Tests for Edge Functions using Deno Test

Testing is an essential step in the development process to ensure the correctness and performance of your Edge Functions.


## Testing in Deno

Deno has a built-in test runner that you can use for testing JavaScript or TypeScript code. You can read the [official documentation](https://docs.deno.com/runtime/manual/basics/testing/) for more information and details about the available testing functions.


## Folder structure

We recommend creating your testing in a `supabase/functions/tests` directory, using the same name as the Function followed by `-test.ts`:

```bash
└── supabase
    ├── functions
    │   ├── function-one
    │   │   └── index.ts
    │   └── function-two
    │   │   └── index.ts
    │   └── tests
    │       └── function-one-test.ts  # Tests for function-one
    │       └── function-two-test.ts  # Tests for function-two
    └── config.toml
```


## Example script

The following script is a good example to get started with testing your Edge Functions:

```typescript function-one-test.ts
// Import required libraries and modules
import { assert, assertEquals } from 'jsr:@std/assert@1'
import { createClient, SupabaseClient } from 'jsr:@supabase/supabase-js@2'

// Will load the .env file to Deno.env
import 'jsr:@std/dotenv/load'

// Set up the configuration for the Supabase client
const supabaseUrl = Deno.env.get('SUPABASE_URL') ?? ''
const supabaseKey = Deno.env.get('SUPABASE_ANON_KEY') ?? ''
const options = {
  auth: {
    autoRefreshToken: false,
    persistSession: false,
    detectSessionInUrl: false,
  },
}

// Test the creation and functionality of the Supabase client
const testClientCreation = async () => {
  var client: SupabaseClient = createClient(supabaseUrl, supabaseKey, options)

  // Verify if the Supabase URL and key are provided
  if (!supabaseUrl) throw new Error('supabaseUrl is required.')
  if (!supabaseKey) throw new Error('supabaseKey is required.')

  // Test a simple query to the database
  const { data: table_data, error: table_error } = await client
    .from('my_table')
    .select('*')
    .limit(1)
  if (table_error) {
    throw new Error('Invalid Supabase client: ' + table_error.message)
  }
  assert(table_data, 'Data should be returned from the query.')
}

// Test the 'hello-world' function
const testHelloWorld = async () => {
  var client: SupabaseClient = createClient(supabaseUrl, supabaseKey, options)

  // Invoke the 'hello-world' function with a parameter
  const { data: func_data, error: func_error } = await client.functions.invoke('hello-world', {
    body: { name: 'bar' },
  })

  // Check for errors from the function invocation
  if (func_error) {
    throw new Error('Invalid response: ' + func_error.message)
  }

  // Log the response from the function
  console.log(JSON.stringify(func_data, null, 2))

  // Assert that the function returned the expected result
  assertEquals(func_data.message, 'Hello bar!')
}

// Register and run the tests
Deno.test('Client Creation Test', testClientCreation)
Deno.test('Hello-world Function Test', testHelloWorld)
```

This test case consists of two parts. The first part tests the client library and verifies that the database can be connected to and returns values from a table (`my_table`). The second part tests the edge function and checks if the received value matches the expected value. Here's a brief overview of the code:

*   We import various testing functions from the Deno standard library, including `assert`, `assertExists`, and `assertEquals`.
*   We import the `createClient` and `SupabaseClient` classes from the `@supabase/supabase-js` library to interact with the Supabase client.
*   We define the necessary configuration for the Supabase client, including the Supabase URL, API key, and authentication options.
*   The `testClientCreation` function tests the creation of a Supabase client instance and queries the database for data from a table. It verifies that data is returned from the query.
*   The `testHelloWorld` function tests the "Hello-world" Edge Function by invoking it using the Supabase client's `functions.invoke` method. It checks if the response message matches the expected greeting.
*   We run the tests using the `Deno.test` function, providing a descriptive name for each test case and the corresponding test function.


## Running Edge Functions locally

To locally test and debug Edge Functions, you can utilize the Supabase CLI. Let's explore how to run Edge Functions locally using the Supabase CLI:

1.  Ensure that the Supabase server is running by executing the following command:

    ```bash
    supabase start
    ```

2.  In your terminal, use the following command to serve the Edge Functions locally:

    ```bash
    supabase functions serve
    ```

    This command starts a local server that runs your Edge Functions, enabling you to test and debug them in a development environment.

3.  Create the environment variables file:

    ```bash
    # creates the file
    touch .env
    # adds the SUPABASE_URL secret
    echo "SUPABASE_URL=http://localhost:54321" >> .env
    # adds the SUPABASE_ANON_KEY secret
    echo "SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZS1kZW1vIiwicm9sZSI6ImFub24iLCJleHAiOjE5ODM4MTI5OTZ9.CRXP1A7WOeoJeXxjNni43kdQwgnWNReilDMblYTn_I0" >> .env
    # Alternatively, you can open it in your editor:
    open .env
    ```

4.  To run the tests, use the following command in your terminal:

    ```bash
    deno test --allow-all supabase/functions/tests/function-one-test.ts
    ```


## Resources

*   Full guide on Testing Supabase Edge Functions on [Mansueli's tips](https://blog.mansueli.com/testing-supabase-edge-functions-with-deno-test)


# Using Wasm modules

How to use WebAssembly in Edge Functions.

Edge Functions supports running [WebAssembly (Wasm)](https://developer.mozilla.org/en-US/docs/WebAssembly) modules. WebAssembly is useful if you want to optimize code that's slower to run in JavaScript or require low-level manipulation.

It also gives you the option to port existing libraries written in other languages to be used with JavaScript. For example, [magick-wasm](https://supabase.com/docs/guides/functions/examples/image-manipulation), which does image manipulation and transforms, is a port of an existing C library to WebAssembly.


### Writing a Wasm module

You can use different languages and SDKs to write Wasm modules. For this tutorial, we will write a simple Wasm module in Rust that adds two numbers.

Follow this [guide on writing Wasm modules in Rust](https://developer.mozilla.org/en-US/docs/WebAssembly/Rust_to_Wasm) to setup your dev environment.

Create a new Edge Function called `wasm-add`.

```bash
supabase functions new wasm-add
```

Create a new Cargo project for the Wasm module inside the function's directory:

```bash
cd supabase/functions/wasm-add
cargo new --lib add-wasm
```

Add the following code to `add-wasm/src/lib.rs`.

Update the `add-wasm/Cargo.toml` to include the `wasm-bindgen` dependency.

After that we can build the package, by running:

```bash
wasm-pack build --target deno
```

This will produce a Wasm binary file inside `add-wasm/pkg` directory.


### Calling the Wasm module from the Edge Function

Now let's update the Edge Function to call `add` from the Wasm module.


### Bundle and deploy the Edge Function

Before deploying the Edge Function, we need to ensure it bundles the Wasm module with it. We can do this by defining it in the `static_files` for the function in `superbase/config.toml`.

```toml
[functions.wasm-add]
static_files = [ "./functions/wasm-add/add-wasm/pkg/*"]
```

Deploy the function by running:

```bash
supabase functions deploy wasm-add
```


# Handling WebSockets

How to handle WebSocket connections in Edge Functions

Edge Functions supports hosting WebSocket servers that can facilitate bi-directional communications with browser clients.

You can also establish outgoing WebSocket client connections to another server from Edge Functions (e.g., [OpenAI Realtime API](https://platform.openai.com/docs/guides/realtime/overview)). You can find an example OpenAI Realtime Relay Server implementation on the [supabase-community GitHub account](https://github.com/supabase-community/openai-realtime-console?tab=readme-ov-file#using-supabase-edge-functions-as-a-relay-server).


### Writing a WebSocket server

Here are some basic examples of setting up WebSocket servers using Deno and Node.js APIs.


### Outbound WebSockets

You can also establish an outbound WebSocket connection to another server from an Edge Function.

Combining it with incoming WebSocket servers, it's possible to use Edge Functions as a WebSocket proxy, for example as a [relay server](https://github.com/supabase-community/openai-realtime-console?tab=readme-ov-file#using-supabase-edge-functions-as-a-relay-server) for the [OpenAI Realtime API](https://platform.openai.com/docs/guides/realtime/overview).


### Authentication

WebSocket browser clients don't have the option to send custom headers. Because of this, Edge Functions won't be able to perform the usual authorization header check to verify the JWT.

You can skip the default authorization header checks by explicitly providing `--no-verify-jwt` when serving and deploying functions.

To authenticate the user making WebSocket requests, you can pass the JWT in URL query params or via a custom protocol.


### Limits

The maximum duration is capped based on the wall-clock, CPU, and memory limits. The Function will shutdown when it reaches one of these [limits](/docs/guides/functions/limits).


### Testing WebSockets locally

When testing Edge Functions locally with Supabase CLI, the instances are terminated automatically after a request is completed. This will prevent keeping WebSocket connections open.

To prevent that, you can update the `supabase/config.toml` with the following settings:

```toml
[edge_runtime]
policy = "per_worker"
```

When running with `per_worker` policy, Function won't auto-reload on edits. You will need to manually restart it by running `supabase functions serve`.

```
```


# Getting Started



### Use cases


### Framework quickstarts


### Web app demos


### Mobile tutorials


# AI Prompts

Prompts for working with Supabase using AI-powered IDE tools

We've curated a selection of prompts to help you work with Supabase using your favorite AI-powered IDE tools, such as Cursor or GitHub Copilot.


## How to use

Copy the prompt to a file in your repo.

Use the "include file" feature from your AI tool to include the prompt when chatting with your AI assistant. For example, in Cursor, add them as [project rules](https://docs.cursor.com/context/rules-for-ai#project-rules-recommended), with GitHub Copilot, use `#<filename>`, and in Zed, use `/file`.


## Prompts


# Architecture



Supabase is open source. We choose open source tools which are scalable and make them simple to use.

Supabase is not a 1-to-1 mapping of Firebase. While we are building many of the features that Firebase offers, we are not going about it the same way:
our technological choices are quite different; everything we use is open source; and wherever possible, we use and support existing tools rather than developing from scratch.

Most notably, we use Postgres rather than a NoSQL store. This choice was deliberate. We believe that no other database offers the functionality required to compete with Firebase, while maintaining the scalability required to go beyond it.


## Choose your comfort level

Our goal at Supabase is to make *all* of Postgres easy to use. That doesn’t mean you have to use all of it. If you’re a Postgres veteran, you’ll probably love the tools that we offer. If you’ve never used Postgres before, then start smaller and grow into it. If you just want to treat Postgres like a simple table-store, that’s perfectly fine.


## Architecture

Each Supabase project consists of several tools:


### Postgres (database)

Postgres is the core of Supabase. We do not abstract the Postgres database—you can access it and use it with full privileges. We provide tools which makes Postgres as easy to use as Firebase.

*   Official Docs: [postgresql.org/docs](https://www.postgresql.org/docs/current/index.html)
*   Source code: [github.com/postgres/postgres](https://github.com/postgres/postgres) (mirror)
*   License: [PostgreSQL License](https://www.postgresql.org/about/licence/)- Language: C


### Studio (dashboard)

An open source Dashboard for managing your database and services.

*   Official Docs: [Supabase docs](/docs)
*   Source code: [github.com/supabase/supabase](https://github.com/supabase/supabase/tree/master/apps/studio)
*   License: [Apache 2](https://github.com/supabase/supabase/blob/master/LICENSE)
*   Language: TypeScript


### GoTrue (Auth)

A JWT-based API for managing users and issuing access tokens. This integrates with PostgreSQL's Row Level Security and the API servers.

*   Official Docs: [Supabase Auth reference docs](/docs/reference/auth)
*   Source code: [github.com/supabase/gotrue](https://github.com/supabase/gotrue)
*   License: [MIT](https://github.com/supabase/gotrue/blob/master/LICENSE)
*   Language: Go


### PostgREST (API)

A standalone web server that turns your Postgres database directly into a RESTful API.
We use this with our [`pg_graphql`](https://github.com/supabase/pg_graphql) extension to provide a GraphQL API.

*   Official Docs: [postgrest.org](https://postgrest.org/)
*   Source code: [github.com/PostgREST/postgrest](https://github.com/PostgREST/postgrest)
*   License: [MIT](https://github.com/PostgREST/postgrest/blob/main/LICENSE)
*   Language: Haskell


### Realtime (API & multiplayer)

A scalable WebSocket engine for managing user Presence, broadcasting messages, and streaming database changes.

*   Official Docs: [Supabase Realtime docs](/docs/guides/realtime)
*   Source code: [github.com/supabase/realtime](https://github.com/supabase/realtime)
*   License: [Apache 2](https://github.com/supabase/realtime/blob/main/LICENSE)
*   Language: Elixir


### Storage API (large file storage)

An S3-compatible object storage service that stores metadata in Postgres.

*   Official Docs: [Supabase Storage reference docs](/docs/reference/storage)
*   Source code: [github.com/supabase/storage-api](https://github.com/supabase/storage-api)
*   License: [Apache 2.0](https://github.com/supabase/storage-api/blob/master/LICENSE)
*   Language: Node.js / TypeScript


### Deno (Edge Functions)

A modern runtime for JavaScript and TypeScript.

*   Official Docs: [Deno documentation](https://deno.land/)
*   Source code: [Deno source code](https://github.com/denoland/deno)
*   License: [MIT](https://github.com/denoland/deno/blob/main/LICENSE.md)
*   Language: TypeScript / Rust


### `postgres-meta` (database management)

A RESTful API for managing your Postgres. Fetch tables, add roles, and run queries.

*   Official Docs: [supabase.github.io/postgres-meta](https://supabase.github.io/postgres-meta/)
*   Source code: [github.com/supabase/postgres-meta](https://github.com/supabase/postgres-meta)
*   License: [Apache 2.0](https://github.com/supabase/postgres-meta/blob/master/LICENSE)
*   Language: Node.js / TypeScript


### Supavisor

A cloud-native, multi-tenant Postgres connection pooler.

*   Official Docs: [Supavisor GitHub Pages](https://supabase.github.io/supavisor/)
*   Source code: [`supabase/supavisor`](https://github.com/supabase/supavisor)
*   License: [Apache 2.0](https://github.com/supabase/supavisor/blob/main/LICENSE)
*   Language: Elixir


### Kong (API gateway)

A cloud-native API gateway, built on top of NGINX.

*   Official Docs: [docs.konghq.com](https://docs.konghq.com/)
*   Source code: [github.com/kong/kong](https://github.com/kong/kong)
*   License: [Apache 2.0](https://github.com/Kong/kong/blob/master/LICENSE)
*   Language: Lua


## Product principles

It is our goal to provide an architecture that any large-scale company would design for themselves,
and then provide tooling around that architecture that is easy-to-use for indie-developers and small teams.

We use a series of principles to ensure that scalability and usability are never mutually exclusive:


### Everything works in isolation

Each system must work as a standalone tool with as few moving parts as possible.
The litmus test for this is: "Can a user run this product with nothing but a Postgres database?"


### Everything is integrated

Supabase is composable. Even though every product works in isolation, each product on the platform needs to 10x the other products.
For integration, each tool should expose an API and Webhooks.


### Everything is extensible

We're deliberate about adding a new tool, and prefer instead to extend an existing one.
This is the opposite of many cloud providers whose product offering expands into niche use-cases. We provide *primitives* for developers, which allow them to achieve any goal.
Less, but better.


### Everything is portable

To avoid lock-in, we make it easy to migrate in and out. Our cloud offering is compatible with our self-hosted product.
We use existing standards to increase portability (like `pg_dump` and CSV files). If a new standard emerges which competes with a "Supabase" approach, we will deprecate the approach in favor of the standard.
This forces us to compete on user experience. We aim to be the best Postgres hosting service.


### Play the long game

We sacrifice short-term wins for long-term gains. For example, it is tempting to run a fork of Postgres with additional functionality which only our customers need.
Instead, we prefer to support efforts to upstream missing functionality so that the entire community benefits. This has the additional benefit of ensuring portability and longevity.


### Build for developers

"Developers" are a specific profile of user: they are *builders*.
When assessing impact as a function of effort, developers have a large efficiency due to the type of products and systems they can build.
As the profile of a developer changes over time, Supabase will continue to evolve the product to fit this evolving profile.


### Support existing tools

Supabase supports existing tools and communities wherever possible. Supabase is more like a "community of communities" - each tool typically has its own community which we work with.
Open source is something we approach [collaboratively](https://supabase.com/blog/supabase-series-b#giving-back): we employ maintainers, sponsor projects, invest in businesses, and develop our own open source tools.


# Features



This is a non-exhaustive list of features that Supabase provides for every project.


## Database


### Postgres database

Every project is a full Postgres database. [Docs](/docs/guides/database).


### Vector database

Store vector embeddings right next to the rest of your data. [Docs](/docs/guides/ai).


### Auto-generated REST API via PostgREST

RESTful APIs are auto-generated from your database, without a single line of code. [Docs](/docs/guides/api#rest-api-overview).


### Auto-generated GraphQL API via pg\_graphql

Fast GraphQL APIs using our custom Postgres GraphQL extension. [Docs](/docs/guides/graphql/api).


### Database webhooks

Send database changes to any external service using Webhooks. [Docs](/docs/guides/database/webhooks).


### Secrets and encryption

Encrypt sensitive data and store secrets using our Postgres extension, Supabase Vault. [Docs](/docs/guides/database/vault).


## Platform


### Database backups

Projects are backed up daily with the option to upgrade to Point in Time recovery. [Docs](/docs/guides/platform/backups).


### Custom domains

White-label the Supabase APIs to create a branded experience for your users. [Docs](/docs/guides/platform/custom-domains).


### Network restrictions

Restrict IP ranges that can connect to your database. [Docs](/docs/guides/platform/network-restrictions).


### SSL enforcement

Enforce Postgres clients to connect via SSL. [Docs](/docs/guides/platform/ssl-enforcement).


### Branching

Use Supabase Branches to test and preview changes. [Docs](/docs/guides/platform/branching).


### Terraform provider

Manage Supabase infrastructure via Terraform, an Infrastructure as Code tool. [Docs](/docs/guides/platform/terraform).


### Read replicas

Deploy read-only databases across multiple regions, for lower latency and better resource management. [Docs](/docs/guides/platform/read-replicas).


### Log drains

Export Supabase logs at to 3rd party providers and external tooling. [Docs](/docs/guides/platform/log-drains).


## Studio


### Studio Single Sign-On

Login to the Supabase dashboard via SSO. [Docs](/docs/guides/platform/sso).


## Realtime


### Postgres changes

Receive your database changes through WebSockets. [Docs](/docs/guides/realtime/postgres-changes).


### Broadcast

Send messages between connected users through WebSockets. [Docs](/docs/guides/realtime/broadcast).


### Presence

Synchronize shared state across your users, including online status and typing indicators. [Docs](/docs/guides/realtime/presence).


## Auth


### Email login

Build email logins for your application or website. [Docs](/docs/guides/auth/auth-email).


### Social login

Provide social logins - everything from Apple, to GitHub, to Slack. [Docs](/docs/guides/auth/social-login).


### Phone logins

Provide phone logins using a third-party SMS provider. [Docs](/docs/guides/auth/phone-login).


### Passwordless login

Build passwordless logins via magic links for your application or website. [Docs](/docs/guides/auth/auth-magic-link).


### Authorization via Row Level Security

Control the data each user can access with Postgres Policies. [Docs](/docs/guides/database/postgres/row-level-security).


### CAPTCHA protection

Add CAPTCHA to your sign-in, sign-up, and password reset forms. [Docs](/docs/guides/auth/auth-captcha).


### Server-Side Auth

Helpers for implementing user authentication in popular server-side languages and frameworks like Next.js, SvelteKit and Remix. [Docs](/docs/guides/auth/server-side).


## Storage


### File storage

Supabase Storage makes it simple to store and serve files. [Docs](/docs/guides/storage).


### Content Delivery Network

Cache large files using the Supabase CDN. [Docs](/docs/guides/storage/cdn/fundamentals).


### Smart Content Delivery Network

Automatically revalidate assets at the edge via the Smart CDN. [Docs](/docs/guides/storage/cdn/smart-cdn).


### Image transformations

Transform images on the fly. [Docs](/docs/guides/storage/serving/image-transformations).


### Resumable uploads

Upload large files using resumable uploads. [Docs](/docs/guides/storage/uploads/resumable-uploads).


### S3 compatibility

Interact with Storage from tool which supports the S3 protocol. [Docs](/docs/guides/storage/s3/compatibility).


## Edge Functions


### Deno Edge Functions

Globally distributed TypeScript functions to execute custom business logic. [Docs](/docs/guides/functions).


### Regional invocations

Execute an Edge Function in a region close to your database. [Docs](/docs/guides/functions/regional-invocation).


### NPM compatibility

Edge functions natively support NPM modules and Node built-in APIs. [Link](https://supabase.com/blog/edge-functions-node-npm).


## Project management


### CLI

Use our CLI to develop your project locally and deploy to the Supabase Platform. [Docs](/docs/reference/cli).


### Management API

Manage your projects programmatically. [Docs](/docs/reference/api).


## Client libraries

Official client libraries for [JavaScript](/docs/reference/javascript/start), [Flutter](/docs/reference/dart/initializing) and [Swift](/docs/reference/swift/introduction).
Unofficial libraries are supported by the community.


## Feature status

Supabase Features are in 4 different states - Private Alpha, Public Alpha, Beta and Generally Available.


### Private alpha

Features are initially launched as a private alpha to gather feedback from the community. To join our early access program, send an email to product-ops@supabase.io.


### Public alpha

The alpha stage indicates that the API might change in the future, not that the service isn’t stable. Even though the [uptime Service Level Agreement](https://supabase.com/sla) does not cover products in Alpha, we do our best to have the service as stable as possible.


### Beta

Features in Beta are tested by an external penetration tester for security issues. The API is guaranteed to be stable and there is a strict communication process for breaking changes.


### Generally available

In addition to the Beta requirements, features in GA are covered by the [uptime SLA](https://supabase.com/sla).

| Product        | Feature                    | Stage           | Available on self-hosted                    |
| -------------- | -------------------------- | --------------- | ------------------------------------------- |
| Database       | Postgres                   | `GA`            | ✅                                          |
| Database       | Vector Database            | `GA`            | ✅                                          |
| Database       | Auto-generated Rest API    | `GA`            | ✅                                          |
| Database       | Auto-generated GraphQL API | `GA`            | ✅                                          |
| Database       | Webhooks                   | `beta`          | ✅                                          |
| Database       | Vault                      | `public alpha`  | ✅                                          |
| Platform       |                            | `GA`            | ✅                                          |
| Platform       | Point-in-Time Recovery     | `GA`            | 🚧 [wal-g](https://github.com/wal-g/wal-g)  |
| Platform       | Custom Domains             | `GA`            | N/A                                         |
| Platform       | Network Restrictions       | `beta`          | N/A                                         |
| Platform       | SSL enforcement            | `GA`            | N/A                                         |
| Platform       | Branching                  | `public alpha`  | N/A                                         |
| Platform       | Terraform Provider         | `public alpha`  | N/A                                         |
| Platform       | Read Replicas              | `private alpha` | N/A                                         |
| Platform       | Log Drains                 | `public alpha`  | ✅                                          |
| Studio         |                            | `GA`            | ✅                                          |
| Studio         | SSO                        | `GA`            | ✅                                          |
| Realtime       | Postgres Changes           | `GA`            | ✅                                          |
| Realtime       | Broadcast                  | `GA`            | ✅                                          |
| Realtime       | Presence                   | `GA`            | ✅                                          |
| Realtime       | Broadcast Authorization    | `public beta`   | ✅                                          |
| Realtime       | Presence Authorization     | `public beta`   | ✅                                          |
| Storage        |                            | `GA`            | ✅                                          |
| Storage        | CDN                        | `GA`            | 🚧 [Cloudflare](https://www.cloudflare.com) |
| Storage        | Smart CDN                  | `GA`            | 🚧 [Cloudflare](https://www.cloudflare.com) |
| Storage        | Image Transformations      | `GA`            | ✅                                          |
| Storage        | Resumable Uploads          | `GA`            | ✅                                          |
| Storage        | S3 compatibility           | `public alpha`  | ✅                                          |
| Edge Functions |                            | `beta`          | ✅                                          |
| Edge Functions | Regional Invocations       | `beta`          | ✅                                          |
| Edge Functions | NPM compatibility          | `beta`          | ✅                                          |
| Auth           |                            | `GA`            | ✅                                          |
| Auth           | Email login                | `GA`            | ✅                                          |
| Auth           | Social login               | `GA`            | ✅                                          |
| Auth           | Phone login                | `GA`            | ✅                                          |
| Auth           | Passwordless login         | `GA`            | ✅                                          |
| Auth           | SSO with SAML              | `GA`            | ✅                                          |
| Auth           | Authorization via RLS      | `GA`            | ✅                                          |
| Auth           | CAPTCHA protection         | `GA`            | ✅                                          |
| Auth           | Server-side Auth           | `beta`          | ✅                                          |
| CLI            |                            | `GA`            | ✅ Works with self-hosted                   |
| Management API |                            | `GA`            | N/A                                         |
| Client Library | JavaScript                 | `GA`            | N/A                                         |
| Client Library | Flutter                    | `beta`          | N/A                                         |
| Client Library | Swift                      | `beta`          | N/A                                         |

*   ✅ = Fully Available
*   🚧 = Available, but requires external tools or configuration


# Model context protocol (MCP)

Connect your AI tools to Supabase using MCP

The [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) is a standard for connecting Large Language Models (LLMs) to platforms like Supabase. This guide covers how to connect Supabase to the following AI tools using MCP:

*   [Cursor](#cursor)
*   [Windsurf](#windsurf) (Codium)
*   [Visual Studio Code](#visual-studio-code-copilot) (Copilot)
*   [Cline](#cline) (VS Code extension)
*   [Claude desktop](#claude-desktop)
*   [Claude code](#claude-code)

Once connected, your AI assistants can interact with and query your Supabase projects on your behalf.


## Step 1: Create a personal access token (PAT)

First, go to your [Supabase settings](https://supabase.com/dashboard/account/tokens) and create a personal access token. Give it a name that describes its purpose, like "Cursor MCP Server". This will be used to authenticate the MCP server with your Supabase account.


## Step 2: Configure in your AI tool

MCP compatible tools can connect to Supabase using the [Supabase MCP server](https://github.com/supabase-community/supabase-mcp). Below are instructions for connecting to this server using popular AI tools:


### Cursor

1.  Open [Cursor](https://www.cursor.com/) and create a `.cursor` directory in your project root if it doesn't exist.

2.  Create a `.cursor/mcp.json` file if it doesn't exist and open it.

3.  Add the following configuration:

4.  Save the configuration file.

5.  Open Cursor and navigate to **Settings/MCP**. You should see a green active status after the server is successfully connected.


### Windsurf

1.  Open [Windsurf](https://docs.codeium.com/windsurf) and navigate to the Cascade assistant.

2.  Tap on the hammer (MCP) icon, then **Configure** to open the configuration file.

3.  Add the following configuration:

4.  Save the configuration file and reload by tapping **Refresh** in the Cascade assistant.

5.  You should see a green active status after the server is successfully connected.


### Visual Studio Code (Copilot)

1.  Open [VS Code](https://code.visualstudio.com/) and create a `.vscode` directory in your project root if it doesn't exist.

2.  Create a `.vscode/mcp.json` file if it doesn't exist and open it.

3.  Add the following configuration:

4.  Save the configuration file.

5.  Open Copilot chat and switch to "Agent" mode. You should see a tool icon that you can tap to confirm the MCP tools are available. Once you begin using the server, you will be prompted to enter your personal access token. Enter the token that you created earlier.

For more info on using MCP in VS Code, see the [Copilot documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers).


### Cline

1.  Open the [Cline](https://github.com/cline/cline) extension in VS Code and tap the **MCP Servers** icon.

2.  Tap **Configure MCP Servers** to open the configuration file.

3.  Add the following configuration:

4.  Save the configuration file. Cline should automatically reload the configuration.

5.  You should see a green active status after the server is successfully connected.


### Claude desktop

1.  Open [Claude desktop](https://claude.ai/download) and navigate to **Settings**.

2.  Under the **Developer** tab, tap **Edit Config** to open the configuration file.

3.  Add the following configuration:

4.  Save the configuration file and restart Claude desktop.

5.  From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available.


### Claude code

1.  Create a `.mcp.json` file in your project root if it doesn't exist.

2.  Add the following configuration:

3.  Save the configuration file.

4.  Restart [Claude code](https://claude.ai/code) to apply the new configuration.


### Next steps

Your AI tool is now connected to Supabase using MCP. Try asking your AI assistant to create a new project, create a table, or fetch project config.

For a full list of tools available, see the [GitHub README](https://github.com/supabase-community/supabase-mcp#tools). If you experience any issues, [submit an bug report](https://github.com/supabase-community/supabase-mcp/issues/new?template=1.Bug_report.md).


## MCP for local Supabase instances

The Supabase MCP server connects directly to the cloud platform to access your database. If you are running a local instance of Supabase, you can instead use the [Postgres MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/postgres) to connect to your local database. This MCP server runs all queries as read-only transactions.


### Step 1: Find your database connection string

To connect to your local Supabase instance, you need to get the connection string for your local database. You can find your connection string by running:

```shell
supabase status
```

or if you are using `npx`:

```shell
npx supabase status
```

This will output a list of details about your local Supabase instance. Copy the `DB URL` field in the output.


### Step 2: Configure the MCP server

Configure your client with the following:


### Next steps

Your AI tool is now connected to your local Supabase instance using MCP. Try asking the AI tool to query your database using natural language commands.


# Use Supabase with Flutter

Learn how to create a Supabase project, add some sample data to your database, and query the data from a Flutter app.

## Setup deep links

Many sign in methods require deep links to redirect the user back to your app after authentication. Read more about setting deep links up for all platforms (including web) in the [Flutter Mobile Guide](/docs/guides/getting-started/tutorials/with-flutter#setup-deep-links).


## Going to production


### Android

In production, your Android app needs explicit permission to use the internet connection on the user's device which is required to communicate with Supabase APIs.
To do this, add the following line to the `android/app/src/main/AndroidManifest.xml` file.

```xml
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
  <!-- Required to fetch data from the internet. -->
  <uses-permission android:name="android.permission.INTERNET" />
  <!-- ... -->
</manifest>
```


# Use Supabase with Hono

Learn how to create a Supabase project, add some sample data to your database, secure it with auth, and query the data from a Hono app.

## Next steps

*   Learn how [server side auth](/docs/guides/auth/server-side/creating-a-client?queryGroups=framework\&framework=hono) works with Hono.
*   [Insert more data](/docs/guides/database/import-data) into your database
*   Upload and serve static files using [Storage](/docs/guides/storage)


# Use Supabase with iOS and SwiftUI

Learn how to create a Supabase project, add some sample data to your database, and query the data from an iOS app.



# Use Supabase with Android Kotlin

Learn how to create a Supabase project, add some sample data to your database, and query the data from an Android Kotlin app.



# Use Supabase with Laravel

Learn how to create a PHP Laravel project, connect it to your Supabase Postgres database, and configure user authentication.



# Use Supabase with Next.js

Learn how to create a Supabase project, add some sample data, and query from a Next.js app.

## Next steps

*   Set up [Auth](/docs/guides/auth) for your app
*   [Insert more data](/docs/guides/database/import-data) into your database
*   Upload and serve static files using [Storage](/docs/guides/storage)


# Use Supabase with Nuxt

Learn how to create a Supabase project, add some sample data to your database, and query the data from a Nuxt app.



# Use Supabase with React

Learn how to create a Supabase project, add some sample data to your database, and query the data from a React app.

## Next steps

*   Set up [Auth](/docs/guides/auth) for your app
*   [Insert more data](/docs/guides/database/import-data) into your database
*   Upload and serve static files using [Storage](/docs/guides/storage)


# Use Supabase with RedwoodJS

Learn how to create a Supabase project, add some sample data to your database using Prisma migration and seeds, and query the data from a RedwoodJS app.



# Use Supabase with refine

Learn how to create a Supabase project, add some sample data to your database, and query the data from a refine app.



# Use Supabase with Ruby on Rails

Learn how to create a Rails project and connect it to your Supabase Postgres database.



# Use Supabase with SolidJS

Learn how to create a Supabase project, add some sample data to your database, and query the data from a SolidJS app.



# Use Supabase with SvelteKit

Learn how to create a Supabase project, add some sample data to your database, and query the data from a SvelteKit app.

## Next steps

*   Set up [Auth](/docs/guides/auth) for your app
*   [Insert more data](/docs/guides/database/import-data) into your database
*   Upload and serve static files using [Storage](/docs/guides/storage)


# Use Supabase with Vue

Learn how to create a Supabase project, add some sample data to your database, and query the data from a Vue app.



# Build a User Management App with Angular



![Supabase User Management example](/docs/img/user-management-demo.png)


## Building the app

Let's start building the Angular app from scratch.


### Initialize an Angular app

We can use the [Angular CLI](https://angular.io/cli) to initialize
an app called `supabase-angular`:

```bash
npx ng new supabase-angular --routing false --style css --standalone false
cd supabase-angular
```

Then let's install the only additional dependency: [supabase-js](https://github.com/supabase/supabase-js)

```bash
npm install @supabase/supabase-js
```

And finally we want to save the environment variables in the `src/environments/environment.ts` file.
All we need are the API URL and the `anon` key that you copied [earlier](#get-the-api-keys).
These variables will be exposed on the browser, and that's completely fine since we have [Row Level Security](/docs/guides/auth#row-level-security) enabled on our Database.

Now that we have the API credentials in place, let's create a `SupabaseService` with `ng g s supabase` to initialize the Supabase client and implement functions to communicate with the Supabase API.

Optionally, update [src/styles.css](https://raw.githubusercontent.com/supabase/supabase/master/examples/user-management/angular-user-management/src/styles.css) to style the app.


### Set up a login component

Let's set up an Angular component to manage logins and sign ups. We'll use Magic Links, so users can sign in with their email without using passwords.
Create an `AuthComponent` with `ng g c auth` Angular CLI command.


### Account page

Users also need a way to edit their profile details and manage their accounts after signing in.
Create an `AccountComponent` with the `ng g c account` Angular CLI command.


### Launch!

Now that we have all the components in place, let's update `AppComponent`:

`app.module.ts` also needs to be modified to include the `ReactiveFormsModule` from the `@angular/forms` package.

Once that's done, run this in a terminal window:

```bash
npm run start
```

And then open the browser to [localhost:4200](http://localhost:4200) and you should see the completed app.

![Supabase Angular](/docs/img/supabase-angular-demo.png)


## Bonus: Profile photos

Every Supabase project is configured with [Storage](/docs/guides/storage) for managing large files like photos and videos.


### Create an upload widget

Let's create an avatar for the user so that they can upload a profile photo.
Create an `AvatarComponent` with `ng g c avatar` Angular CLI command.


### Add the new widget

And then we can add the widget on top of the `AccountComponent` HTML template:

And add an `updateAvatar` function along with an `avatarUrl` getter to the `AccountComponent` typescript file:

At this stage you have a fully functional application!


# Build a User Management App with Expo React Native



![Supabase User Management example](/docs/img/supabase-flutter-demo.png)


## Building the app

Let's start building the React Native app from scratch.


### Initialize a React Native app

We can use [`expo`](https://docs.expo.dev/get-started/create-a-new-app/) to initialize
an app called `expo-user-management`:

```bash
npx create-expo-app -t expo-template-blank-typescript expo-user-management

cd expo-user-management
```

Then let's install the additional dependencies: [supabase-js](https://github.com/supabase/supabase-js)

```bash
npx expo install @supabase/supabase-js @react-native-async-storage/async-storage @rneui/themed
```

Now let's create a helper file to initialize the Supabase client.
We need the API URL and the `anon` key that you copied [earlier](#get-the-api-keys).
These variables are safe to expose in your Expo app since Supabase has
[Row Level Security](/docs/guides/database/postgres/row-level-security) enabled on your Database.


### Set up a login component

Let's set up a React Native component to manage logins and sign ups.
Users would be able to sign in with their email and password.


### Account page

After a user is signed in we can allow them to edit their profile details and manage their account.

Let's create a new component for that called `Account.tsx`.


### Launch!

Now that we have all the components in place, let's update `App.tsx`:

Once that's done, run this in a terminal window:

```bash
npm start
```

And then press the appropriate key for the environment you want to test the app in and you should see the completed app.


## Bonus: Profile photos

Every Supabase project is configured with [Storage](/docs/guides/storage) for managing large files like
photos and videos.


### Additional dependency installation

You will need an image picker that works on the environment you will build the project for, we will use `expo-image-picker` in this example.

```bash
npx expo install expo-image-picker
```


### Create an upload widget

Let's create an avatar for the user so that they can upload a profile photo.
We can start by creating a new component:


### Add the new widget

And then we can add the widget to the Account page:

Now you will need to run the prebuild command to get the application working on your chosen platform.

```bash
npx expo prebuild
```

At this stage you have a fully functional application!


# Build a User Management App with Flutter



![Supabase User Management example](/docs/img/supabase-flutter-demo.png)


## Building the app

Let's start building the Flutter app from scratch.


### Initialize a Flutter app

We can use [`flutter create`](https://flutter.dev/docs/get-started/test-drive) to initialize
an app called `supabase_quickstart`:

```bash
flutter create supabase_quickstart
```

Then let's install the only additional dependency: [`supabase_flutter`](https://pub.dev/packages/supabase_flutter)

Copy and paste the following line in your pubspec.yaml to install the package:

```yaml
supabase_flutter: ^2.0.0
```

Run `flutter pub get` to install the dependencies.


### Setup deep links

Now that we have the dependencies installed let's setup deep links.
Setting up deep links is required to bring back the user to the app when they click on the magic link to sign in.
We can setup deep links with just a minor tweak on our Flutter application.

We have to use `io.supabase.flutterquickstart` as the scheme. In this example, we will use `login-callback` as the host for our deep link, but you can change it to whatever you would like.

First, add `io.supabase.flutterquickstart://login-callback/` as a new [redirect URL](https://supabase.com/dashboard/project/_/auth/url-configuration) in the Dashboard.

![Supabase console deep link setting](/docs/img/deeplink-setting.png)

That is it on Supabase's end and the rest are platform specific settings:


### Main function

Now that we have deep links ready let's initialize the Supabase client inside our `main` function with the API credentials that you copied [earlier](#get-the-api-keys). These variables will be exposed on the app, and that's completely fine since we have [Row Level Security](/docs/guides/auth#row-level-security) enabled on our Database.

Notice that we have a `showSnackBar` extension method that we will use to show snack bars in the app. You could define this method in a separate file and import it where needed, but for simplicity, we will define it here.


### Set up a login page

Let's create a Flutter widget to manage logins and sign ups. We will use Magic Links, so users can sign in with their email without using passwords.

Notice that this page sets up a listener on the user's auth state using `onAuthStateChange`. A new event will fire when the user comes back to the app by clicking their magic link, which this page can catch and redirect the user accordingly.


### Set up account page

After a user is signed in we can allow them to edit their profile details and manage their account.
Let's create a new widget called `account_page.dart` for that.


### Launch!

Now that we have all the components in place, let's update `lib/main.dart`.
The `home` of the `MaterialApp`, meaning the initial page shown to the user, will be the `LoginPage` if the user is not authenticated, and the `AccountPage` if the user is authenticated.
We also included some theming to make the app look a bit nicer.

Once that's done, run this in a terminal window to launch on Android or iOS:

```bash
flutter run
```

Or for web, run the following command to launch it on `localhost:3000`

```bash
flutter run -d web-server --web-hostname localhost --web-port 3000
```

And then open the browser to [localhost:3000](http://localhost:3000) and you should see the completed app.

![Supabase User Management example](/docs/img/supabase-flutter-account-page.png)


## Bonus: Profile photos

Every Supabase project is configured with [Storage](/docs/guides/storage) for managing large files like
photos and videos.


### Making sure we have a public bucket

We will be storing the image as a publicly sharable image.
Make sure your `avatars` bucket is set to public, and if it is not, change the publicity by clicking the dot menu that appears when you hover over the bucket name.
You should see an orange `Public` badge next to your bucket name if your bucket is set to public.


### Adding image uploading feature to account page

We will use [`image_picker`](https://pub.dev/packages/image_picker) plugin to select an image from the device.

Add the following line in your pubspec.yaml file to install `image_picker`:

```yaml
image_picker: ^1.0.5
```

Using [`image_picker`](https://pub.dev/packages/image_picker) requires some additional preparation depending on the platform.
Follow the instruction on README.md of [`image_picker`](https://pub.dev/packages/image_picker) on how to set it up for the platform you are using.

Once you are done with all of the above, it is time to dive into coding.


### Create an upload widget

Let's create an avatar for the user so that they can upload a profile photo.
We can start by creating a new component:


### Add the new widget

And then we can add the widget to the Account page as well as some logic to update the `avatar_url` whenever the user uploads a new avatar.

Congratulations, you've built a fully functional user management app using Flutter and Supabase!


## See also

*   [Flutter Tutorial: building a Flutter chat app](https://supabase.com/blog/flutter-tutorial-building-a-chat-app)
*   [Flutter Tutorial - Part 2: Authentication and Authorization with RLS](https://supabase.com/blog/flutter-authentication-and-authorization-with-rls)


# Build a User Management App with Ionic Angular



![Supabase User Management example](/docs/img/ionic-demos/ionic-angular-account.png)


## Building the app

Let's start building the Angular app from scratch.


### Initialize an Ionic Angular app

We can use the [Ionic CLI](https://ionicframework.com/docs/cli) to initialize
an app called `supabase-ionic-angular`:

```bash
npm install -g @ionic/cli
ionic start supabase-ionic-angular blank --type angular
cd supabase-ionic-angular
```

Then let's install the only additional dependency: [supabase-js](https://github.com/supabase/supabase-js)

```bash
npm install @supabase/supabase-js
```

And finally, we want to save the environment variables in the `src/environments/environment.ts` file.
All we need are the API URL and the `anon` key that you copied [earlier](#get-the-api-keys).
These variables will be exposed on the browser, and that's completely fine since we have [Row Level Security](/docs/guides/auth#row-level-security) enabled on our Database.

Now that we have the API credentials in place, let's create a `SupabaseService` with `ionic g s supabase` to initialize the Supabase client and implement functions to communicate with the Supabase API.


### Set up a login route

Let's set up a route to manage logins and signups. We'll use Magic Links so users can sign in with their email without using passwords.
Create a `LoginPage` with the `ionic g page login` Ionic CLI command.


### Account page

After a user is signed in, we can allow them to edit their profile details and manage their account.
Create an `AccountComponent` with `ionic g page account` Ionic CLI command.


### Launch!

Now that we have all the components in place, let's update `AppComponent`:

Then update the `AppRoutingModule`

Once that's done, run this in a terminal window:

```bash
ionic serve
```

And the browser will automatically open to show the app.

![Supabase Angular](/docs/img/ionic-demos/ionic-angular.png)


## Bonus: Profile photos

Every Supabase project is configured with [Storage](/docs/guides/storage) for managing large files like photos and videos.


### Create an upload widget

Let's create an avatar for the user so that they can upload a profile photo.

First, install two packages in order to interact with the user's camera.

```bash
npm install @ionic/pwa-elements @capacitor/camera
```

[Capacitor](https://capacitorjs.com) is a cross-platform native runtime from Ionic that enables web apps to be deployed through the app store and provides access to native device API.

Ionic PWA elements is a companion package that will polyfill certain browser APIs that provide no user interface with custom Ionic UI.

With those packages installed, we can update our `main.ts` to include an additional bootstrapping call for the Ionic PWA Elements.

Then create an `AvatarComponent` with this Ionic CLI command:

```bash
 ionic g component avatar --module=/src/app/account/account.module.ts --create-module
```


### Add the new widget

And then, we can add the widget on top of the `AccountComponent` HTML template:

At this stage, you have a fully functional application!


## See also

*   [Authentication in Ionic Angular with Supabase](https://supabase.com/blog/authentication-in-ionic-angular)


# Build a User Management App with Ionic React



![Supabase User Management example](/docs/img/ionic-demos/ionic-angular-account.png)


## Building the app

Let's start building the React app from scratch.


### Initialize an Ionic React app

We can use the [Ionic CLI](https://ionicframework.com/docs/cli) to initialize
an app called `supabase-ionic-react`:

```bash
npm install -g @ionic/cli
ionic start supabase-ionic-react blank --type react
cd supabase-ionic-react
```

Then let's install the only additional dependency: [supabase-js](https://github.com/supabase/supabase-js)

```bash
npm install @supabase/supabase-js
```

And finally we want to save the environment variables in a `.env`.
All we need are the API URL and the `anon` key that you copied [earlier](#get-the-api-keys).

Now that we have the API credentials in place, let's create a helper file to initialize the Supabase client. These variables will be exposed
on the browser, and that's completely fine since we have [Row Level Security](/docs/guides/auth#row-level-security) enabled on our Database.


### Set up a login route

Let's set up a React component to manage logins and sign ups. We'll use Magic Links, so users can sign in with their email without using passwords.


### Account page

After a user is signed in we can allow them to edit their profile details and manage their account.

Let's create a new component for that called `Account.tsx`.


### Launch!

Now that we have all the components in place, let's update `App.tsx`:

Once that's done, run this in a terminal window:

```bash
ionic serve
```

And then open the browser to [localhost:3000](http://localhost:3000) and you should see the completed app.

![Supabase Ionic React](/docs/img/ionic-demos/ionic-react.png)


## Bonus: Profile photos

Every Supabase project is configured with [Storage](/docs/guides/storage) for managing large files like photos and videos.


### Create an upload widget

First install two packages in order to interact with the user's camera.

```bash
npm install @ionic/pwa-elements @capacitor/camera
```

[Capacitor](https://capacitorjs.com) is a cross platform native runtime from Ionic that enables web apps to be deployed through the app store and provides access to native device API.

Ionic PWA elements is a companion package that will polyfill certain browser APIs that provide no user interface with custom Ionic UI.

With those packages installed we can update our `index.tsx` to include an additional bootstrapping call for the Ionic PWA Elements.

Then create an `AvatarComponent`.


### Add the new widget

And then we can add the widget to the Account page:

At this stage you have a fully functional application!


# Build a User Management App with Ionic Vue



![Supabase User Management example](/docs/img/ionic-demos/ionic-angular-account.png)


## Building the app

Let's start building the Vue app from scratch.


### Initialize an Ionic Vue app

We can use the [Ionic CLI](https://ionicframework.com/docs/cli) to initialize an app called `supabase-ionic-vue`:

```bash
npm install -g @ionic/cli
ionic start supabase-ionic-vue blank --type vue
cd supabase-ionic-vue
```

Then let's install the only additional dependency: [supabase-js](https://github.com/supabase/supabase-js)

```bash
npm install @supabase/supabase-js
```

And finally we want to save the environment variables in a `.env`.

All we need are the API URL and the `anon` key that you copied [earlier](#get-the-api-keys).

Now that we have the API credentials in place, let's create a helper file to initialize the Supabase client. These variables will be exposed on the browser, and that's completely fine since we have [Row Level Security](/docs/guides/auth#row-level-security) enabled on our Database.


### Set up a login route

Let's set up a Vue component to manage logins and sign ups. We'll use Magic Links, so users can sign in with their email without using passwords.


### Account page

After a user is signed in we can allow them to edit their profile details and manage their account.

Let's create a new component for that called `Account.vue`.


### Launch!

Now that we have all the components in place, let's update `App.vue` and our routes:

Once that's done, run this in a terminal window:

```bash
ionic serve
```

And then open the browser to [localhost:3000](http://localhost:3000) and you should see the completed app.

![Supabase Ionic Vue](/docs/img/ionic-demos/ionic-vue.png)


## Bonus: Profile photos

Every Supabase project is configured with [Storage](/docs/guides/storage) for managing large files like photos and videos.


### Create an upload widget

First install two packages in order to interact with the user's camera.

```bash
npm install @ionic/pwa-elements @capacitor/camera
```

[Capacitor](https://capacitorjs.com) is a cross-platform native runtime from Ionic that enables web apps to be deployed through the app store and provides access to native device API.

Ionic PWA elements is a companion package that will polyfill certain browser APIs that provide no user interface with custom Ionic UI.

With those packages installed we can update our `main.ts` to include an additional bootstrapping call for the Ionic PWA Elements.

Then create an `AvatarComponent`.


### Add the new widget

And then we can add the widget to the Account page:

At this stage you have a fully functional application!


# Build a Product Management Android App with Jetpack Compose



This tutorial demonstrates how to build a basic product management app. The app demonstrates management operations, photo upload, account creation and authentication using:

*   [Supabase Database](/docs/guides/database) - a Postgres database for storing your user data and [Row Level Security](/docs/guides/auth#row-level-security) so data is protected and users can only access their own information.
*   [Supabase Auth](/docs/guides/auth) - users log in through magic links sent to their email (without having to set up a password).
*   [Supabase Storage](/docs/guides/storage) - users can upload a profile photo.

![manage-product-cover](/docs/img/guides/kotlin/manage-product-cover.png)


## Building the app


### Create new Android project

Open Android Studio > New Project > Base Activity (Jetpack Compose).

![Android Studio new project](/docs/img/guides/kotlin/android-studio-new-project.png)


### Set up API key and secret securely


#### Create local environment secret

Create or edit the `local.properties` file at the root (same level as `build.gradle`) of your project.

> **Note**: Do not commit this file to your source control, for example, by adding it to your `.gitignore` file!

```kotlin
SUPABASE_ANON_KEY=YOUR_SUPABASE_ANON_KEY
SUPABASE_URL=YOUR_SUPABASE_URL
```


#### Read and set value to `BuildConfig`

In your `build.gradle` (app) file, create a `Properties` object and read the values from your `local.properties` file by calling the `buildConfigField` method:

```kotlin
defaultConfig {
   applicationId "com.example.manageproducts"
   minSdkVersion 22
   targetSdkVersion 33
   versionCode 5
   versionName "1.0"
   testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"

   // Set value part
   Properties properties = new Properties()
   properties.load(project.rootProject.file("local.properties").newDataInputStream())
   buildConfigField("String", "SUPABASE_ANON_KEY", "\"${properties.getProperty("SUPABASE_ANON_KEY")}\"")
   buildConfigField("String", "SECRET", "\"${properties.getProperty("SECRET")}\"")
   buildConfigField("String", "SUPABASE_URL", "\"${properties.getProperty("SUPABASE_URL")}\"")
}
```


#### Use value from `BuildConfig`

Read the value from `BuildConfig`:

```kotlin
val url = BuildConfig.SUPABASE_URL
val apiKey = BuildConfig.SUPABASE_ANON_KEY
```


### Set up Supabase dependencies

![Gradle dependencies](/docs/img/guides/kotlin/gradle-dependencies.png)

In the `build.gradle` (app) file, add these dependencies then press "Sync now." Replace the dependency version placeholders `$supabase_version` and `$ktor_version` with their respective latest versions.

```kotlin
implementation "io.github.jan-tennert.supabase:postgrest-kt:$supabase_version"
implementation "io.github.jan-tennert.supabase:storage-kt:$supabase_version"
implementation "io.github.jan-tennert.supabase:auth-kt:$supabase_version"
implementation "io.ktor:ktor-client-android:$ktor_version"
implementation "io.ktor:ktor-client-core:$ktor_version"
implementation "io.ktor:ktor-utils:$ktor_version"
```

Also in the `build.gradle` (app) file, add the plugin for serialization. The version of this plugin should be the same as your Kotlin version.

```kotlin
plugins {
    ...
    id 'org.jetbrains.kotlin.plugin.serialization' version '$kotlin_version'
    ...
}
```


### Set up Hilt for dependency injection

In the `build.gradle` (app) file, add the following:

```kotlin
implementation "com.google.dagger:hilt-android:$hilt_version"
annotationProcessor "com.google.dagger:hilt-compiler:$hilt_version"
implementation("androidx.hilt:hilt-navigation-compose:1.0.0")
```

Create a new `ManageProductApplication.kt` class extending Application with `@HiltAndroidApp` annotation:

```kotlin
// ManageProductApplication.kt
@HiltAndroidApp
class ManageProductApplication: Application()
```

Open the `AndroidManifest.xml` file, update name property of Application tag:

```xml
<application
...
    android:name=".ManageProductApplication"
...
</application>

```

Create the `MainActivity`:

```kotlin
@AndroidEntryPoint
class MainActivity : ComponentActivity() {
    //This will come later
}
```


### Provide Supabase instances with Hilt

To make the app easier to test, create a `SupabaseModule.kt` file as follows:

```kotlin
@InstallIn(SingletonComponent::class)
@Module
object SupabaseModule {

    @Provides
    @Singleton
    fun provideSupabaseClient(): SupabaseClient {
        return createSupabaseClient(
            supabaseUrl = BuildConfig.SUPABASE_URL,
            supabaseKey = BuildConfig.SUPABASE_ANON_KEY
        ) {
            install(Postgrest)
            install(Auth) {
                flowType = FlowType.PKCE
                scheme = "app"
                host = "supabase.com"
            }
            install(Storage)
        }
    }

    @Provides
    @Singleton
    fun provideSupabaseDatabase(client: SupabaseClient): Postgrest {
        return client.postgrest
    }

    @Provides
    @Singleton
    fun provideSupabaseAuth(client: SupabaseClient): Auth {
        return client.auth
    }


    @Provides
    @Singleton
    fun provideSupabaseStorage(client: SupabaseClient): Storage {
        return client.storage
    }

}
```


### Create a data transfer object

Create a `ProductDto.kt` class and use annotations to parse data from Supabase:

```kotlin
@Serializable
data class ProductDto(

    @SerialName("name")
    val name: String,

    @SerialName("price")
    val price: Double,

    @SerialName("image")
    val image: String?,

    @SerialName("id")
    val id: String,
)
```

Create a Domain object in `Product.kt` expose the data in your view:

```kotlin
data class Product(
    val id: String,
    val name: String,
    val price: Double,
    val image: String?
)
```


### Implement repositories

Create a `ProductRepository` interface and its implementation named `ProductRepositoryImpl`. This holds the logic to interact with data sources from Supabase. Do the same with the `AuthenticationRepository`.

Create the Product Repository:

```kotlin
interface ProductRepository {
    suspend fun createProduct(product: Product): Boolean
    suspend fun getProducts(): List<ProductDto>?
    suspend fun getProduct(id: String): ProductDto
    suspend fun deleteProduct(id: String)
    suspend fun updateProduct(
        id: String, name: String, price: Double, imageName: String, imageFile: ByteArray
    )
}
```

```kotlin
class ProductRepositoryImpl @Inject constructor(
    private val postgrest: Postgrest,
    private val storage: Storage,
) : ProductRepository {
    override suspend fun createProduct(product: Product): Boolean {
        return try {
            withContext(Dispatchers.IO) {
                val productDto = ProductDto(
                    name = product.name,
                    price = product.price,
                )
                postgrest.from("products").insert(productDto)
                true
            }
            true
        } catch (e: java.lang.Exception) {
            throw e
        }
    }

    override suspend fun getProducts(): List<ProductDto>? {
        return withContext(Dispatchers.IO) {
            val result = postgrest.from("products")
                .select().decodeList<ProductDto>()
            result
        }
    }


    override suspend fun getProduct(id: String): ProductDto {
        return withContext(Dispatchers.IO) {
            postgrest.from("products").select {
                filter {
                    eq("id", id)
                }
            }.decodeSingle<ProductDto>()
        }
    }

    override suspend fun deleteProduct(id: String) {
        return withContext(Dispatchers.IO) {
            postgrest.from("products").delete {
                filter {
                    eq("id", id)
                }
            }
        }
    }

    override suspend fun updateProduct(
        id: String,
        name: String,
        price: Double,
        imageName: String,
        imageFile: ByteArray
    ) {
        withContext(Dispatchers.IO) {
            if (imageFile.isNotEmpty()) {
                val imageUrl =
                    storage.from("Product%20Image").upload(
                        path = "$imageName.png",
                        data = imageFile,
                        upsert = true
                    )
                postgrest.from("products").update({
                    set("name", name)
                    set("price", price)
                    set("image", buildImageUrl(imageFileName = imageUrl))
                }) {
                    filter {
                        eq("id", id)
                    }
                }
            } else {
                postgrest.from("products").update({
                    set("name", name)
                    set("price", price)
                }) {
                    filter {
                        eq("id", id)
                    }
                }
            }
        }
    }

    // Because I named the bucket as "Product Image" so when it turns to an url, it is "%20"
    // For better approach, you should create your bucket name without space symbol
    private fun buildImageUrl(imageFileName: String) =
        "${BuildConfig.SUPABASE_URL}/storage/v1/object/public/${imageFileName}".replace(" ", "%20")
}
```

Create the Authentication Repository:

```kotlin
interface AuthenticationRepository {
    suspend fun signIn(email: String, password: String): Boolean
    suspend fun signUp(email: String, password: String): Boolean
    suspend fun signInWithGoogle(): Boolean
}
```

```kotlin
class AuthenticationRepositoryImpl @Inject constructor(
    private val auth: Auth
) : AuthenticationRepository {
    override suspend fun signIn(email: String, password: String): Boolean {
        return try {
            auth.signInWith(Email) {
                this.email = email
                this.password = password
            }
            true
        } catch (e: Exception) {
            false
        }
    }

    override suspend fun signUp(email: String, password: String): Boolean {
        return try {
            auth.signUpWith(Email) {
                this.email = email
                this.password = password
            }
            true
        } catch (e: Exception) {
            false
        }
    }

    override suspend fun signInWithGoogle(): Boolean {
        return try {
            auth.signInWith(Google)
            true
        } catch (e: Exception) {
            false
        }
    }
}
```


### Implement screens

To navigate screens, use the AndroidX navigation library. For routes, implement a `Destination` interface:

```kotlin

interface Destination {
    val route: String
    val title: String
}


object ProductListDestination : Destination {
    override val route = "product_list"
    override val title = "Product List"
}

object ProductDetailsDestination : Destination {
    override val route = "product_details"
    override val title = "Product Details"
    const val productId = "product_id"
    val arguments = listOf(navArgument(name = productId) {
        type = NavType.StringType
    })
    fun createRouteWithParam(productId: String) = "$route/${productId}"
}

object AddProductDestination : Destination {
    override val route = "add_product"
    override val title = "Add Product"
}

object AuthenticationDestination: Destination {
    override val route = "authentication"
    override val title = "Authentication"
}

object SignUpDestination: Destination {
    override val route = "signup"
    override val title = "Sign Up"
}
```

This will help later for navigating between screens.

Create a `ProductListViewModel`:

```kotlin
@HiltViewModel
class ProductListViewModel @Inject constructor(
private val productRepository: ProductRepository,
) : ViewModel() {

    private val _productList = MutableStateFlow<List<Product>?>(listOf())
    val productList: Flow<List<Product>?> = _productList


    private val _isLoading = MutableStateFlow(false)
    val isLoading: Flow<Boolean> = _isLoading

    init {
        getProducts()
    }

    fun getProducts() {
        viewModelScope.launch {
            val products = productRepository.getProducts()
            _productList.emit(products?.map { it -> it.asDomainModel() })
        }
    }

    fun removeItem(product: Product) {
        viewModelScope.launch {
            val newList = mutableListOf<Product>().apply { _productList.value?.let { addAll(it) } }
            newList.remove(product)
            _productList.emit(newList.toList())
            // Call api to remove
            productRepository.deleteProduct(id = product.id)
            // Then fetch again
            getProducts()
        }
    }

    private fun ProductDto.asDomainModel(): Product {
        return Product(
            id = this.id,
            name = this.name,
            price = this.price,
            image = this.image
        )
    }

}

```

Create the `ProductListScreen.kt`:

```kotlin
@OptIn(ExperimentalMaterial3Api::class, ExperimentalMaterialApi::class)
@Composable
fun ProductListScreen(
    modifier: Modifier = Modifier,
    navController: NavController,
    viewModel: ProductListViewModel = hiltViewModel(),
) {
    val isLoading by viewModel.isLoading.collectAsState(initial = false)
    val swipeRefreshState = rememberSwipeRefreshState(isRefreshing = isLoading)
    SwipeRefresh(state = swipeRefreshState, onRefresh = { viewModel.getProducts() }) {
        Scaffold(
            topBar = {
                TopAppBar(
                    backgroundColor = MaterialTheme.colorScheme.primary,
                    title = {
                        Text(
                            text = stringResource(R.string.product_list_text_screen_title),
                            color = MaterialTheme.colorScheme.onPrimary,
                        )
                    },
                )
            },
            floatingActionButton = {
                AddProductButton(onClick = { navController.navigate(AddProductDestination.route) })
            }
        ) { padding ->
            val productList = viewModel.productList.collectAsState(initial = listOf()).value
            if (!productList.isNullOrEmpty()) {
                LazyColumn(
                    modifier = modifier.padding(padding),
                    contentPadding = PaddingValues(5.dp)
                ) {
                    itemsIndexed(
                        items = productList,
                        key = { _, product -> product.name }) { _, item ->
                        val state = rememberDismissState(
                            confirmStateChange = {
                                if (it == DismissValue.DismissedToStart) {
                                    // Handle item removed
                                    viewModel.removeItem(item)
                                }
                                true
                            }
                        )
                        SwipeToDismiss(
                            state = state,
                            background = {
                                val color by animateColorAsState(
                                    targetValue = when (state.dismissDirection) {
                                        DismissDirection.StartToEnd -> MaterialTheme.colorScheme.primary
                                        DismissDirection.EndToStart -> MaterialTheme.colorScheme.primary.copy(
                                            alpha = 0.2f
                                        )
                                        null -> Color.Transparent
                                    }
                                )
                                Box(
                                    modifier = modifier
                                        .fillMaxSize()
                                        .background(color = color)
                                        .padding(16.dp),
                                ) {
                                    Icon(
                                        imageVector = Icons.Filled.Delete,
                                        contentDescription = null,
                                        tint = MaterialTheme.colorScheme.primary,
                                        modifier = modifier.align(Alignment.CenterEnd)
                                    )
                                }

                            },
                            dismissContent = {
                                ProductListItem(
                                    product = item,
                                    modifier = modifier,
                                    onClick = {
                                        navController.navigate(
                                            ProductDetailsDestination.createRouteWithParam(
                                                item.id
                                            )
                                        )
                                    },
                                )
                            },
                            directions = setOf(DismissDirection.EndToStart),
                        )
                    }
                }
            } else {
                Text("Product list is empty!")
            }

        }
    }
}

@Composable
private fun AddProductButton(
    modifier: Modifier = Modifier,
    onClick: () -> Unit,
) {
    FloatingActionButton(
        modifier = modifier,
        onClick = onClick,
        containerColor = MaterialTheme.colorScheme.primary,
        contentColor = MaterialTheme.colorScheme.onPrimary
    ) {
        Icon(
            imageVector = Icons.Filled.Add,
            contentDescription = null,
        )
    }
}
```

Create the `ProductDetailsViewModel.kt`:

```kotlin

@HiltViewModel
class ProductDetailsViewModel @Inject constructor(
    private val productRepository: ProductRepository,
    savedStateHandle: SavedStateHandle,
    ) : ViewModel() {

    private val _product = MutableStateFlow<Product?>(null)
    val product: Flow<Product?> = _product

    private val _name = MutableStateFlow("")
    val name: Flow<String> = _name

    private val _price = MutableStateFlow(0.0)
    val price: Flow<Double> = _price

    private val _imageUrl = MutableStateFlow("")
    val imageUrl: Flow<String> = _imageUrl

    init {
        val productId = savedStateHandle.get<String>(ProductDetailsDestination.productId)
        productId?.let {
            getProduct(productId = it)
        }
    }

    private fun getProduct(productId: String) {
        viewModelScope.launch {
           val result = productRepository.getProduct(productId).asDomainModel()
            _product.emit(result)
            _name.emit(result.name)
            _price.emit(result.price)
        }
    }

    fun onNameChange(name: String) {
        _name.value = name
    }

    fun onPriceChange(price: Double) {
        _price.value = price
    }

    fun onSaveProduct(image: ByteArray) {
        viewModelScope.launch {
            productRepository.updateProduct(
                id = _product.value?.id,
                price = _price.value,
                name = _name.value,
                imageFile = image,
                imageName = "image_${_product.value.id}",
            )
        }
    }

    fun onImageChange(url: String) {
        _imageUrl.value = url
    }

    private fun ProductDto.asDomainModel(): Product {
        return Product(
            id = this.id,
            name = this.name,
            price = this.price,
            image = this.image
        )
    }
}
```

Create the `ProductDetailsScreen.kt`:

```kotlin
@OptIn(ExperimentalCoilApi::class)
@SuppressLint("UnusedMaterialScaffoldPaddingParameter")
@Composable
fun ProductDetailsScreen(
    modifier: Modifier = Modifier,
    viewModel: ProductDetailsViewModel = hiltViewModel(),
    navController: NavController,
    productId: String?,
) {
    val snackBarHostState = remember { SnackbarHostState() }
    val coroutineScope = rememberCoroutineScope()

    Scaffold(
        snackbarHost = { SnackbarHost(snackBarHostState) },
        topBar = {
            TopAppBar(
                navigationIcon = {
                    IconButton(onClick = {
                        navController.navigateUp()
                    }) {
                        Icon(
                            imageVector = Icons.Filled.ArrowBack,
                            contentDescription = null,
                            tint = MaterialTheme.colorScheme.onPrimary
                        )
                    }
                },
                backgroundColor = MaterialTheme.colorScheme.primary,
                title = {
                    Text(
                        text = stringResource(R.string.product_details_text_screen_title),
                        color = MaterialTheme.colorScheme.onPrimary,
                    )
                },
            )
        }
    ) {
        val name = viewModel.name.collectAsState(initial = "")
        val price = viewModel.price.collectAsState(initial = 0.0)
        var imageUrl = Uri.parse(viewModel.imageUrl.collectAsState(initial = null).value)
        val contentResolver = LocalContext.current.contentResolver

        Column(
            modifier = modifier
                .padding(16.dp)
                .fillMaxSize()
        ) {
            val galleryLauncher =
                rememberLauncherForActivityResult(ActivityResultContracts.GetContent())
                { uri ->
                    uri?.let {
                        if (it.toString() != imageUrl.toString()) {
                            viewModel.onImageChange(it.toString())
                        }
                    }
                }

            Image(
                painter = rememberImagePainter(imageUrl),
                contentScale = ContentScale.Fit,
                contentDescription = null,
                modifier = Modifier
                    .padding(16.dp, 8.dp)
                    .size(100.dp)
                    .align(Alignment.CenterHorizontally)
            )
            IconButton(modifier = modifier.align(alignment = Alignment.CenterHorizontally),
                onClick = {
                    galleryLauncher.launch("image/*")
                }) {
                Icon(
                    imageVector = Icons.Filled.Edit,
                    contentDescription = null,
                    tint = MaterialTheme.colorScheme.primary
                )
            }
            OutlinedTextField(
                label = {
                    Text(
                        text = "Product name",
                        color = MaterialTheme.colorScheme.primary,
                        style = MaterialTheme.typography.titleMedium
                    )
                },
                maxLines = 2,
                shape = RoundedCornerShape(32),
                modifier = modifier.fillMaxWidth(),
                value = name.value,
                onValueChange = {
                    viewModel.onNameChange(it)
                },
            )
            Spacer(modifier = modifier.height(12.dp))
            OutlinedTextField(
                label = {
                    Text(
                        text = "Product price",
                        color = MaterialTheme.colorScheme.primary,
                        style = MaterialTheme.typography.titleMedium
                    )
                },
                maxLines = 2,
                shape = RoundedCornerShape(32),
                modifier = modifier.fillMaxWidth(),
                value = price.value.toString(),
                keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Number),
                onValueChange = {
                    viewModel.onPriceChange(it.toDouble())
                },
            )
            Spacer(modifier = modifier.weight(1f))
            Button(
                modifier = modifier.fillMaxWidth(),
                onClick = {
                    if (imageUrl.host?.contains("supabase") == true) {
                        viewModel.onSaveProduct(image = byteArrayOf())
                    } else {
                        val image = uriToByteArray(contentResolver, imageUrl)
                        viewModel.onSaveProduct(image = image)
                    }
                    coroutineScope.launch {
                        snackBarHostState.showSnackbar(
                            message = "Product updated successfully !",
                            duration = SnackbarDuration.Short
                        )
                    }
                }) {
                Text(text = "Save changes")
            }
            Spacer(modifier = modifier.height(12.dp))
            OutlinedButton(
                modifier = modifier
                    .fillMaxWidth(),
                onClick = {
                    navController.navigateUp()
                }) {
                Text(text = "Cancel")
            }

        }

    }
}


private fun getBytes(inputStream: InputStream): ByteArray {
    val byteBuffer = ByteArrayOutputStream()
    val bufferSize = 1024
    val buffer = ByteArray(bufferSize)
    var len = 0
    while (inputStream.read(buffer).also { len = it } != -1) {
        byteBuffer.write(buffer, 0, len)
    }
    return byteBuffer.toByteArray()
}


private fun uriToByteArray(contentResolver: ContentResolver, uri: Uri): ByteArray {
    if (uri == Uri.EMPTY) {
        return byteArrayOf()
    }
    val inputStream = contentResolver.openInputStream(uri)
    if (inputStream != null) {
        return getBytes(inputStream)
    }
    return byteArrayOf()
}
```

Create a `AddProductScreen`:

```kotlin
@SuppressLint("UnusedMaterial3ScaffoldPaddingParameter")
@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun AddProductScreen(
    modifier: Modifier = Modifier,
    navController: NavController,
    viewModel: AddProductViewModel = hiltViewModel(),
) {
    Scaffold(
        topBar = {
            TopAppBar(
                navigationIcon = {
                    IconButton(onClick = {
                        navController.navigateUp()
                    }) {
                        Icon(
                            imageVector = Icons.Filled.ArrowBack,
                            contentDescription = null,
                            tint = MaterialTheme.colorScheme.onPrimary
                        )
                    }
                },
                backgroundColor = MaterialTheme.colorScheme.primary,
                title = {
                    Text(
                        text = stringResource(R.string.add_product_text_screen_title),
                        color = MaterialTheme.colorScheme.onPrimary,
                    )
                },
            )
        }
    ) { padding ->
        val navigateAddProductSuccess =
            viewModel.navigateAddProductSuccess.collectAsState(initial = null).value
        val isLoading =
            viewModel.isLoading.collectAsState(initial = null).value
        if (isLoading == true) {
            LoadingScreen(message = "Adding Product",
                onCancelSelected = {
                    navController.navigateUp()
                })
        } else {
            SuccessScreen(
                message = "Product added",
                onMoreAction = {
                    viewModel.onAddMoreProductSelected()
                },
                onNavigateBack = {
                    navController.navigateUp()
                })
        }

    }
}
```

Create the `AddProductViewModel.kt`:

```kotlin
@HiltViewModel
class AddProductViewModel @Inject constructor(
    private val productRepository: ProductRepository,
) : ViewModel() {

    private val _isLoading = MutableStateFlow(false)
    val isLoading: Flow<Boolean> = _isLoading

    private val _showSuccessMessage = MutableStateFlow(false)
    val showSuccessMessage: Flow<Boolean> = _showSuccessMessage

    fun onCreateProduct(name: String, price: Double) {
        if (name.isEmpty() || price <= 0) return
        viewModelScope.launch {
            _isLoading.value = true
            val product = Product(
                id = UUID.randomUUID().toString(),
                name = name,
                price = price,
            )
            productRepository.createProduct(product = product)
            _isLoading.value = false
            _showSuccessMessage.emit(true)

        }
    }
}
```

Create a `SignUpViewModel`:

```kotlin
@HiltViewModel
class SignUpViewModel @Inject constructor(
    private val authenticationRepository: AuthenticationRepository
) : ViewModel() {

    private val _email = MutableStateFlow("")
    val email: Flow<String> = _email

    private val _password = MutableStateFlow("")
    val password = _password

    fun onEmailChange(email: String) {
        _email.value = email
    }

    fun onPasswordChange(password: String) {
        _password.value = password
    }

    fun onSignUp() {
        viewModelScope.launch {
            authenticationRepository.signUp(
                email = _email.value,
                password = _password.value
            )
        }
    }
}
```

Create the `SignUpScreen.kt`:

```kotlin
@Composable
fun SignUpScreen(
    modifier: Modifier = Modifier,
    navController: NavController,
    viewModel: SignUpViewModel = hiltViewModel()
) {
    val snackBarHostState = remember { SnackbarHostState() }
    val coroutineScope = rememberCoroutineScope()
    Scaffold(
        snackbarHost = { androidx.compose.material.SnackbarHost(snackBarHostState) },
        topBar = {
            TopAppBar(
                navigationIcon = {
                    IconButton(onClick = {
                        navController.navigateUp()
                    }) {
                        Icon(
                            imageVector = Icons.Filled.ArrowBack,
                            contentDescription = null,
                            tint = MaterialTheme.colorScheme.onPrimary
                        )
                    }
                },
                backgroundColor = MaterialTheme.colorScheme.primary,
                title = {
                    Text(
                        text = "Sign Up",
                        color = MaterialTheme.colorScheme.onPrimary,
                    )
                },
            )
        }
    ) { paddingValues ->
        Column(
            modifier = modifier
                .padding(paddingValues)
                .padding(20.dp)
        ) {
            val email = viewModel.email.collectAsState(initial = "")
            val password = viewModel.password.collectAsState()
            OutlinedTextField(
                label = {
                    Text(
                        text = "Email",
                        color = MaterialTheme.colorScheme.primary,
                        style = MaterialTheme.typography.titleMedium
                    )
                },
                maxLines = 1,
                shape = RoundedCornerShape(32),
                modifier = modifier.fillMaxWidth(),
                value = email.value,
                onValueChange = {
                    viewModel.onEmailChange(it)
                },
            )
            OutlinedTextField(
                label = {
                    Text(
                        text = "Password",
                        color = MaterialTheme.colorScheme.primary,
                        style = MaterialTheme.typography.titleMedium
                    )
                },
                maxLines = 1,
                shape = RoundedCornerShape(32),
                modifier = modifier
                    .fillMaxWidth()
                    .padding(top = 12.dp),
                value = password.value,
                onValueChange = {
                    viewModel.onPasswordChange(it)
                },
            )
            val localSoftwareKeyboardController = LocalSoftwareKeyboardController.current
            Button(modifier = modifier
                .fillMaxWidth()
                .padding(top = 12.dp),
                onClick = {
                    localSoftwareKeyboardController?.hide()
                    viewModel.onSignUp()
                    coroutineScope.launch {
                        snackBarHostState.showSnackbar(
                            message = "Create account successfully. Sign in now!",
                            duration = SnackbarDuration.Long
                        )
                    }
                }) {
                Text("Sign up")
            }
        }
    }
}
```

Create a `SignInViewModel`:

```kotlin
@HiltViewModel
class SignInViewModel @Inject constructor(
    private val authenticationRepository: AuthenticationRepository
) : ViewModel() {

    private val _email = MutableStateFlow("")
    val email: Flow<String> = _email

    private val _password = MutableStateFlow("")
    val password = _password

    fun onEmailChange(email: String) {
        _email.value = email
    }

    fun onPasswordChange(password: String) {
        _password.value = password
    }

    fun onSignIn() {
        viewModelScope.launch {
            authenticationRepository.signIn(
                email = _email.value,
                password = _password.value
            )
        }
    }

    fun onGoogleSignIn() {
        viewModelScope.launch {
            authenticationRepository.signInWithGoogle()
        }
    }

}
```

Create the `SignInScreen.kt`:

```kotlin
@OptIn(ExperimentalMaterial3Api::class, ExperimentalComposeUiApi::class)
@Composable
fun SignInScreen(
    modifier: Modifier = Modifier,
    navController: NavController,
    viewModel: SignInViewModel = hiltViewModel()
) {
    val snackBarHostState = remember { SnackbarHostState() }
    val coroutineScope = rememberCoroutineScope()
    Scaffold(
        snackbarHost = { androidx.compose.material.SnackbarHost(snackBarHostState) },
        topBar = {
            TopAppBar(
                navigationIcon = {
                    IconButton(onClick = {
                        navController.navigateUp()
                    }) {
                        Icon(
                            imageVector = Icons.Filled.ArrowBack,
                            contentDescription = null,
                            tint = MaterialTheme.colorScheme.onPrimary
                        )
                    }
                },
                backgroundColor = MaterialTheme.colorScheme.primary,
                title = {
                    Text(
                        text = "Login",
                        color = MaterialTheme.colorScheme.onPrimary,
                    )
                },
            )
        }
    ) { paddingValues ->
        Column(
            modifier = modifier
                .padding(paddingValues)
                .padding(20.dp)
        ) {
            val email = viewModel.email.collectAsState(initial = "")
            val password = viewModel.password.collectAsState()
            androidx.compose.material.OutlinedTextField(
                label = {
                    Text(
                        text = "Email",
                        color = MaterialTheme.colorScheme.primary,
                        style = MaterialTheme.typography.titleMedium
                    )
                },
                maxLines = 1,
                shape = RoundedCornerShape(32),
                modifier = modifier.fillMaxWidth(),
                value = email.value,
                onValueChange = {
                    viewModel.onEmailChange(it)
                },
            )
            androidx.compose.material.OutlinedTextField(
                label = {
                    Text(
                        text = "Password",
                        color = MaterialTheme.colorScheme.primary,
                        style = MaterialTheme.typography.titleMedium
                    )
                },
                maxLines = 1,
                shape = RoundedCornerShape(32),
                modifier = modifier
                    .fillMaxWidth()
                    .padding(top = 12.dp),
                value = password.value,
                onValueChange = {
                    viewModel.onPasswordChange(it)
                },
            )
            val localSoftwareKeyboardController = LocalSoftwareKeyboardController.current
            Button(modifier = modifier
                .fillMaxWidth()
                .padding(top = 12.dp),
                onClick = {
                    localSoftwareKeyboardController?.hide()
                    viewModel.onGoogleSignIn()
                }) {
                Text("Sign in with Google")
            }
            Button(modifier = modifier
                .fillMaxWidth()
                .padding(top = 12.dp),
                onClick = {
                    localSoftwareKeyboardController?.hide()
                    viewModel.onSignIn()
                    coroutineScope.launch {
                        snackBarHostState.showSnackbar(
                            message = "Sign in successfully !",
                            duration = SnackbarDuration.Long
                        )
                    }
                }) {
                Text("Sign in")
            }
            OutlinedButton(modifier = modifier
                .fillMaxWidth()
                .padding(top = 12.dp), onClick = {
                navController.navigate(SignUpDestination.route)
            }) {
                Text("Sign up")
            }
        }
    }
}
```


### Implement the `MainActivity`

In the `MainActivity` you created earlier, show your newly created screens:

```kotlin
@AndroidEntryPoint
class MainActivity : ComponentActivity() {
    @Inject
    lateinit var supabaseClient: SupabaseClient

    @OptIn(ExperimentalMaterial3Api::class)
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContent {
            ManageProductsTheme {
                // A surface container using the 'background' color from the theme
                val navController = rememberNavController()
                val currentBackStack by navController.currentBackStackEntryAsState()
                val currentDestination = currentBackStack?.destination
                Scaffold { innerPadding ->
                    NavHost(
                        navController,
                        startDestination = ProductListDestination.route,
                        Modifier.padding(innerPadding)
                    ) {
                        composable(ProductListDestination.route) {
                            ProductListScreen(
                                navController = navController
                            )
                        }

                        composable(AuthenticationDestination.route) {
                            SignInScreen(
                                navController = navController
                            )
                        }

                        composable(SignUpDestination.route) {
                            SignUpScreen(
                                navController = navController
                            )
                        }

                        composable(AddProductDestination.route) {
                            AddProductScreen(
                                navController = navController
                            )
                        }

                        composable(
                            route = "${ProductDetailsDestination.route}/{${ProductDetailsDestination.productId}}",
                            arguments = ProductDetailsDestination.arguments
                        ) { navBackStackEntry ->
                            val productId =
                                navBackStackEntry.arguments?.getString(ProductDetailsDestination.productId)
                            ProductDetailsScreen(
                                productId = productId,
                                navController = navController,
                            )
                        }
                    }
                }
            }
        }
    }
}
```


### Create the success screen

To handle OAuth and OTP signins, create a new activity to handle the deep link you set in `AndroidManifest.xml`:

```xml
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">
    <uses-permission android:name="android.permission.INTERNET" />
    <application
        android:name=".ManageProductApplication"
        android:allowBackup="true"
        android:dataExtractionRules="@xml/data_extraction_rules"
        android:enableOnBackInvokedCallback="true"
        android:fullBackupContent="@xml/backup_rules"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:supportsRtl="true"
        android:theme="@style/Theme.ManageProducts"
        tools:targetApi="31">
        <activity
            android:name=".DeepLinkHandlerActivity"
            android:exported="true"
            android:theme="@style/Theme.ManageProducts" >
            <intent-filter android:autoVerify="true">
                <action android:name="android.intent.action.VIEW" />
                <category android:name="android.intent.category.DEFAULT" />
                <category android:name="android.intent.category.BROWSABLE" />
                <data
                    android:host="supabase.com"
                    android:scheme="app" />
            </intent-filter>
        </activity>
        <activity
            android:name=".MainActivity"
            android:exported="true"
            android:label="@string/app_name"
            android:theme="@style/Theme.ManageProducts">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>
</manifest>
```

Then create the `DeepLinkHandlerActivity`:

```kotlin
@AndroidEntryPoint
class DeepLinkHandlerActivity : ComponentActivity() {

    @Inject
    lateinit var supabaseClient: SupabaseClient

    private lateinit var callback: (String, String) -> Unit

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        supabaseClient.handleDeeplinks(intent = intent,
            onSessionSuccess = { userSession ->
                Log.d("LOGIN", "Log in successfully with user info: ${userSession.user}")
                userSession.user?.apply {
                    callback(email ?: "", createdAt.toString())
                }
            })
        setContent {
            val navController = rememberNavController()
            val emailState = remember { mutableStateOf("") }
            val createdAtState = remember { mutableStateOf("") }
            LaunchedEffect(Unit) {
                callback = { email, created ->
                    emailState.value = email
                    createdAtState.value = created
                }
            }
            ManageProductsTheme {
                Surface(
                    modifier = Modifier.fillMaxSize(),
                    color = MaterialTheme.colorScheme.background
                ) {
                    SignInSuccessScreen(
                        modifier = Modifier.padding(20.dp),
                        navController = navController,
                        email = emailState.value,
                        createdAt = createdAtState.value,
                        onClick = { navigateToMainApp() }
                    )
                }
            }
        }
    }

    private fun navigateToMainApp() {
        val intent = Intent(this, MainActivity::class.java).apply {
            flags = Intent.FLAG_ACTIVITY_CLEAR_TOP
        }
        startActivity(intent)
    }
}
```


# Build a User Management App with Next.js



![Supabase User Management example](/docs/img/user-management-demo.png)


## Building the app

Let's start building the Next.js app from scratch.


### Initialize a Next.js app

We can use [`create-next-app`](https://nextjs.org/docs/getting-started) to initialize an app called `supabase-nextjs`:

Then install the Supabase client library: [supabase-js](https://github.com/supabase/supabase-js)

```bash
npm install @supabase/supabase-js
```

And finally we want to save the environment variables in a `.env.local`.
Create a `.env.local` file at the root of the project, and paste the API URL and the `anon` key that you copied [earlier](#get-the-api-keys).

```bash .env.local
NEXT_PUBLIC_SUPABASE_URL=YOUR_SUPABASE_URL
NEXT_PUBLIC_SUPABASE_ANON_KEY=YOUR_SUPABASE_ANON_KEY
```


### App styling (optional)

An optional step is to update the CSS file `app/globals.css` to make the app look nice.
You can find the full contents of this file [here](https://raw.githubusercontent.com/supabase/supabase/master/examples/user-management/nextjs-user-management/app/globals.css).


### Supabase Server-Side Auth

Next.js is a highly versatile framework offering pre-rendering at build time (SSG), server-side rendering at request time (SSR), API routes, and middleware edge-functions.

To better integrate with the framework, we've created the `@supabase/ssr` package for Server-Side Auth. It has all the functionalities to quickly configure your Supabase project to use cookies for storing user sessions. See the [Next.js Server-Side Auth guide](/docs/guides/auth/server-side/nextjs) for more information.

Install the package for Next.js.

```bash
npm install @supabase/ssr
```


### Supabase utilities

There are two different types of clients in Supabase:

1.  **Client Component client** - To access Supabase from Client Components, which run in the browser.
2.  **Server Component client** - To access Supabase from Server Components, Server Actions, and Route Handlers, which run only on the server.

It is recommended to create the following essential utilities files for creating clients, and organize them within `utils/supabase` at the root of the project.


### Next.js middleware

Since Server Components can't write cookies, you need middleware to refresh expired Auth tokens and store them. This is accomplished by:

*   Refreshing the Auth token with the call to `supabase.auth.getUser`.
*   Passing the refreshed Auth token to Server Components through `request.cookies.set`, so they don't attempt to refresh the same token themselves.
*   Passing the refreshed Auth token to the browser, so it replaces the old token. This is done with `response.cookies.set`.

You could also add a matcher, so that the middleware only runs on route that access Supabase. For more information, check out this [documentation](https://nextjs.org/docs/app/building-your-application/routing/middleware#matching-paths).


## Set up a login page


### Login and signup form

Create a login/signup page for your application:

Navigate to `http://localhost:3000/login`. You should see your login form, but it's not yet hooked up to the actual login function. Next, you need to create the login/signup actions. They will:

*   Retrieve the user's information.
*   Send that information to Supabase as a signup request, which in turns will send a confirmation email.
*   Handle any error that arises.


### Email template

Change the email template to support a server-side authentication flow.

Before we proceed, let's change the email template to support sending a token hash:

*   Go to the [Auth templates](/dashboard/project/_/auth/templates) page in your dashboard.
*   Select `Confirm signup` template.
*   Change `{{ .ConfirmationURL }}` to `{{ .SiteURL }}/auth/confirm?token_hash={{ .TokenHash }}&type=email`.


### Confirmation endpoint

As we are working in a server-side rendering (SSR) environment, it is necessary to create a server endpoint responsible for exchanging the `token_hash` for a session.

In the following code snippet, we perform the following steps:

*   Retrieve the code sent back from the Supabase Auth server using the `token_hash` query parameter.
*   Exchange this code for a session, which we store in our chosen storage mechanism (in this case, cookies).
*   Finally, we redirect the user to the `account` page.


### Account page

After a user is signed in we can allow them to edit their profile details and manage their account.

Let's create a new component for that called `AccountForm` within the `app/account` folder.

Create an account page for the `AccountForm` component we just created


### Sign out

Let's create a route handler to handle the signout from the server side. Make sure to check if the user is logged in first!


### Launch!

Now that we have all the pages, route handlers and components in place, let's run this in a terminal window:

```bash
npm run dev
```

And then open the browser to [localhost:3000](http://localhost:3000) and you should see the completed app.


## Bonus: Profile photos

Every Supabase project is configured with [Storage](/docs/guides/storage) for managing large files like
photos and videos.


### Create an upload widget

Let's create an avatar widget for the user so that they can upload a profile photo. We can start by creating a new component:


### Add the new widget

And then we can add the widget to the `AccountForm` component:

At this stage you have a fully functional application!


## See also

*   See the complete [example on GitHub](https://github.com/supabase/supabase/tree/master/examples/user-management/nextjs-user-management) and deploy it to Vercel
*   [Build a Twitter Clone with the Next.js App Router and Supabase - free egghead course](https://egghead.io/courses/build-a-twitter-clone-with-the-next-js-app-router-and-supabase-19bebadb)
*   Explore the [pre-built Auth UI for React](/docs/guides/auth/auth-helpers/auth-ui)
*   Explore the [Auth Helpers for Next.js](/docs/guides/auth/auth-helpers/nextjs)
*   Explore the [Supabase Cache Helpers](https://github.com/psteinroe/supabase-cache-helpers)
*   See the [Next.js Subscription Payments Starter](https://github.com/vercel/nextjs-subscription-payments) template on GitHub


# Build a User Management App with Nuxt 3



![Supabase User Management example](/docs/img/user-management-demo.png)


## Building the app

Let's start building the Vue 3 app from scratch.


### Initialize a Nuxt 3 app

We can use [`nuxi init`](https://nuxt.com/docs/getting-started/installation) to create an app called `nuxt-user-management`:

```bash
npx nuxi init nuxt-user-management

cd nuxt-user-management
```

Then let's install the only additional dependency: [Nuxt Supabase](https://supabase.nuxtjs.org/). We only need to import Nuxt Supabase as a dev dependency.

```bash
npm install @nuxtjs/supabase --save-dev
```

And finally we want to save the environment variables in a `.env`.
All we need are the API URL and the `anon` key that you copied [earlier](#get-the-api-keys).

These variables will be exposed on the browser, and that's completely fine since we have [Row Level Security](/docs/guides/auth#row-level-security) enabled on our Database.
Amazing thing about [Nuxt Supabase](https://supabase.nuxtjs.org/) is that setting environment variables is all we need to do in order to start using Supabase.
No need to initialize Supabase. The library will take care of it automatically.


### App styling (optional)

An optional step is to update the CSS file `assets/main.css` to make the app look nice.
You can find the full contents of this file [here](https://github.com/supabase-community/nuxt3-quickstarter/blob/main/assets/main.css).


### Set up Auth component

Let's set up a Vue component to manage logins and sign ups. We'll use Magic Links, so users can sign in with their email without using passwords.


### User state

To access the user information, use the composable [`useSupabaseUser`](https://supabase.nuxtjs.org/usage/composables/usesupabaseuser) provided by the Supabase Nuxt module.


### Account component

After a user is signed in we can allow them to edit their profile details and manage their account.
Let's create a new component for that called `Account.vue`.


### Launch!

Now that we have all the components in place, let's update `app.vue`:

Once that's done, run this in a terminal window:

```bash
npm run dev
```

And then open the browser to [localhost:3000](http://localhost:3000) and you should see the completed app.

![Supabase Nuxt 3](/docs/img/supabase-vue-3-demo.png)


## Bonus: Profile photos

Every Supabase project is configured with [Storage](/docs/guides/storage) for managing large files like photos and videos.


### Create an upload widget

Let's create an avatar for the user so that they can upload a profile photo. We can start by creating a new component:


### Add the new widget

And then we can add the widget to the Account page:

That is it! You should now be able to upload a profile photo to Supabase Storage and you have a fully functional application.


# Build a User Management App with React



![Supabase User Management example](/docs/img/user-management-demo.png)


## Building the app

Let's start building the React app from scratch.


### Initialize a React app

We can use [Vite](https://vitejs.dev/guide/) to initialize
an app called `supabase-react`:

```bash
npm create vite@latest supabase-react -- --template react
cd supabase-react
```

Then let's install the only additional dependency: [supabase-js](https://github.com/supabase/supabase-js).

```bash
npm install @supabase/supabase-js
```

And finally we want to save the environment variables in a `.env.local` file.
All we need are the API URL and the `anon` key that you copied [earlier](#get-the-api-keys).

Now that we have the API credentials in place, let's create a helper file to initialize the Supabase client. These variables will be exposed
on the browser, and that's completely fine since we have [Row Level Security](/docs/guides/auth#row-level-security) enabled on our Database.

Create and edit `src/supabaseClient.js`:


### App styling (optional)

An optional step is to update the CSS file `src/index.css` to make the app look nice.
You can find the full contents of this file [here](https://raw.githubusercontent.com/supabase/supabase/master/examples/user-management/react-user-management/src/index.css).


### Set up a login component

Let's set up a React component to manage logins and sign ups. We'll use Magic Links, so users can sign in with their email without using passwords.

Create and edit `src/Auth.jsx`:


### Account page

After a user is signed in we can allow them to edit their profile details and manage their account.

Let's create a new component for that called `src/Account.jsx`.


### Launch!

Now that we have all the components in place, let's update `src/App.jsx`:

Once that's done, run this in a terminal window:

```bash
npm run dev
```

And then open the browser to [localhost:5173](http://localhost:5173) and you should see the completed app.

![Supabase React](/docs/img/supabase-react-demo.png)


## Bonus: Profile photos

Every Supabase project is configured with [Storage](/docs/guides/storage) for managing large files like photos and videos.


### Create an upload widget

Let's create an avatar for the user so that they can upload a profile photo. We can start by creating a new component:

Create and edit `src/Avatar.jsx`:


### Add the new widget

And then we can add the widget to the Account page at `src/Account.jsx`:

At this stage you have a fully functional application!


# Build a User Management App with RedwoodJS



![Supabase User Management example](/docs/img/user-management-demo.png)


## About RedwoodJS

A Redwood application is split into two parts: a frontend and a backend. This is represented as two node projects within a single monorepo.

The frontend project is called **`web`** and the backend project is called **`api`**. For clarity, we will refer to these in prose as **"sides,"** that is, the `web side` and the `api side`.
They are separate projects because code on the `web side` will end up running in the user's browser while code on the `api side` will run on a server somewhere.

The **`api side`** is an implementation of a GraphQL API. The business logic is organized into "services" that represent their own internal API and can be called both from external GraphQL requests and other internal services.

The **`web side`** is built with React. Redwood's router makes it simple to map URL paths to React "Page" components (and automatically code-split your app on each route).
Pages may contain a "Layout" component to wrap content. They also contain "Cells" and regular React components.
Cells allow you to declaratively manage the lifecycle of a component that fetches and displays data.

For the sake of consistency with the other framework tutorials, we'll build this app a little differently than normal.
We ***won't use*** Prisma to connect to the Supabase Postgres database or [Prisma migrations](https://redwoodjs.com/docs/cli-commands#prisma-migrate) as one typically might in a Redwood app.
Instead, we'll rely on the Supabase client to do some of the work on the **`web`** side and use the client again on the **`api`** side to do data fetching as well.

That means you will want to refrain from running any `yarn rw prisma migrate` commands and also double check your build commands on deployment to ensure Prisma won't reset your database. Prisma currently doesn't support cross-schema foreign keys, so introspecting the schema fails due
to how your Supabase `public` schema references the `auth.users`.


## Building the app

Let's start building the RedwoodJS app from scratch.

Make sure you have installed yarn since RedwoodJS relies on it to [manage its packages in workspaces](https://classic.yarnpkg.com/lang/en/docs/workspaces/) for its `web` and `api` "sides."


### Initialize a RedwoodJS app

We can use [Create Redwood App](https://redwoodjs.com/docs/quick-start) command to initialize
an app called `supabase-redwoodjs`:

```bash
yarn create redwood-app supabase-redwoodjs
cd supabase-redwoodjs
```

While the app is installing, you should see:

```bash
✔ Creating Redwood app
  ✔ Checking node and yarn compatibility
  ✔ Creating directory 'supabase-redwoodjs'
✔ Installing packages
  ✔ Running 'yarn install'... (This could take a while)
✔ Convert TypeScript files to JavaScript
✔ Generating types

Thanks for trying out Redwood!
```

Then let's install the only additional dependency [supabase-js](https://github.com/supabase/supabase-js) by running the `setup auth` command:

```bash
yarn redwood setup auth supabase
```

When prompted:

> Overwrite existing /api/src/lib/auth.\[jt]s?

Say, **yes** and it will setup the Supabase client in your app and also provide hooks used with Supabase authentication.

```bash
✔ Generating auth lib...
  ✔ Successfully wrote file `./api/src/lib/auth.js`
  ✔ Adding auth config to web...
  ✔ Adding auth config to GraphQL API...
  ✔ Adding required web packages...
  ✔ Installing packages...
  ✔ One more thing...

  You will need to add your Supabase URL (SUPABASE_URL), public API KEY,
  and JWT SECRET (SUPABASE_KEY, and SUPABASE_JWT_SECRET) to your .env file.
```

Next, we want to save the environment variables in a `.env`.
We need the `API URL` as well as the `anon` and `jwt_secret` keys that you copied [earlier](#get-the-api-keys).

And finally, you will also need to save **just** the `web side` environment variables to the `redwood.toml`.

These variables will be exposed on the browser, and that's completely fine.
They allow your web app to initialize the Supabase client with your public anon key
since we have [Row Level Security](/docs/guides/auth#row-level-security) enabled on our Database.

You'll see these being used to configure your Supabase client in `web/src/App.js`:


### App styling (optional)

An optional step is to update the CSS file `web/src/index.css` to make the app look nice.
You can find the full contents of this file [here](https://raw.githubusercontent.com/supabase/supabase/master/examples/user-management/react-user-management/src/index.css).


### Start RedwoodJS and your first page

Let's test our setup at the moment by starting up the app:

```bash
yarn rw dev
```

You should see a "Welcome to RedwoodJS" page and a message about not having any pages yet.

So, let's create a "home" page:

```bash
yarn rw generate page home /

✔ Generating page files...
  ✔ Successfully wrote file `./web/src/pages/HomePage/HomePage.stories.js`
  ✔ Successfully wrote file `./web/src/pages/HomePage/HomePage.test.js`
  ✔ Successfully wrote file `./web/src/pages/HomePage/HomePage.js`
✔ Updating routes file...
✔ Generating types ...
```

You can stop the `dev` server if you want; to see your changes, just be sure to run `yarn rw dev` again.

You should see the `Home` page route in `web/src/Routes.js`:


### Set up a login component

Let's set up a Redwood component to manage logins and sign ups. We'll use Magic Links, so users can sign in with their email without using passwords.

```bash
yarn rw g component auth

  ✔ Generating component files...
    ✔ Successfully wrote file `./web/src/components/Auth/Auth.test.js`
    ✔ Successfully wrote file `./web/src/components/Auth/Auth.stories.js`
    ✔ Successfully wrote file `./web/src/components/Auth/Auth.js`

```

Now, update the `Auth.js` component to contain:


### Set up an account component

After a user is signed in we can allow them to edit their profile details and manage their account.

Let's create a new component for that called `Account.js`.

```bash
yarn rw g component account

  ✔ Generating component files...
    ✔ Successfully wrote file `./web/src/components/Account/Account.test.js`
    ✔ Successfully wrote file `./web/src/components/Account/Account.stories.js`
    ✔ Successfully wrote file `./web/src/components/Account/Account.js`
```

And then update the file to contain:

You'll see the use of `useAuth()` several times. Redwood's `useAuth` hook provides convenient ways to access
`logIn`, `logOut`, `currentUser`, and access the `supabase` authenticate client. We'll use it to get an instance
of the Supabase client to interact with your API.


### Update home page

Now that we have all the components in place, let's update your `HomePage` page to use them:


### Launch!

Once that's done, run this in a terminal window to launch the `dev` server:

```bash
yarn rw dev
```

And then open the browser to [localhost:8910](http://localhost:8910) and you should see the completed app.

![Supabase RedwoodJS](/docs/img/supabase-redwoodjs-demo.png)


## Bonus: Profile photos

Every Supabase project is configured with [Storage](/docs/guides/storage) for managing large files like photos and videos.


### Create an upload widget

Let's create an avatar for the user so that they can upload a profile photo. We can start by creating a new component:

```bash
yarn rw g component avatar
  ✔ Generating component files...
    ✔ Successfully wrote file `./web/src/components/Avatar/Avatar.test.js`
    ✔ Successfully wrote file `./web/src/components/Avatar/Avatar.stories.js`
    ✔ Successfully wrote file `./web/src/components/Avatar/Avatar.js`
```

Now, update your Avatar component to contain the following widget:


### Add the new widget

And then we can add the widget to the Account component:

At this stage you have a fully functional application!


## See also

*   Learn more about [RedwoodJS](https://redwoodjs.com)
*   Visit the [RedwoodJS Discourse Community](https://community.redwoodjs.com)


# Build a User Management App with refine



![Supabase User Management example](/docs/img/user-management-demo.png)


## About refine

[refine](https://github.com/refinedev/refine) is a React-based framework used to rapidly build data-heavy applications like admin panels, dashboards, storefronts and any type of CRUD apps. It separates app concerns into individual layers, each backed by a React context and respective provider object. For example, the auth layer represents a context served by a specific set of [`authProvider`](https://refine.dev/docs/tutorial/understanding-authprovider/index/) methods that carry out authentication and authorization actions such as logging in, logging out, getting roles data, etc. Similarly, the data layer offers another level of abstraction that is equipped with [`dataProvider`](https://refine.dev/docs/tutorial/understanding-dataprovider/index/) methods to handle CRUD operations at appropriate backend API endpoints.

refine provides hassle-free integration with Supabase backend with its supplementary [`@refinedev/supabase`](https://github.com/refinedev/refine/tree/master/packages/supabase) package. It generates `authProvider` and `dataProvider` methods at project initialization, so we don't need to expend much effort to define them ourselves. We just need to choose Supabase as our backend service while creating the app with `create refine-app`.


## Building the app

Let's start building the refine app from scratch.


### Initialize a refine app

We can use [create refine-app](https://refine.dev/docs/tutorial/getting-started/headless/create-project/#launch-the-refine-cli-setup) command to initialize
an app. Run the following in the terminal:

```bash
npm create refine-app@latest -- --preset refine-supabase
```

In the above command, we are using the `refine-supabase` preset which chooses the Supabase supplementary package for our app. We are not using any UI framework, so we'll have a headless UI with plain React and CSS styling.

The `refine-supabase` preset installs the `@refinedev/supabase` package which out-of-the-box includes the Supabase dependency: [supabase-js](https://github.com/supabase/supabase-js).

We also need to install `@refinedev/react-hook-form` and `react-hook-form` packages that allow us to use [React Hook Form](https://react-hook-form.com) inside refine apps. Run:

```bash
npm install @refinedev/react-hook-form react-hook-form
```

With the app initialized and packages installed, at this point before we begin discussing refine concepts, let's try running the app:

```bash
cd app-name
npm run dev
```

We should have a running instance of the app with a Welcome page at `http://localhost:5173`.

Let's move ahead to understand the generated code now.


### Refine `supabaseClient`

The `create refine-app` generated a Supabase client for us in the `src/utility/supabaseClient.ts` file. It has two constants: `SUPABASE_URL` and `SUPABASE_KEY`. We want to replace them as `supabaseUrl` and `supabaseAnonKey` respectively and assign them our own Supabase server's values.

We'll update it with environment variables managed by Vite:

And then, we want to save the environment variables in a `.env.local` file. All you need are the API URL and the `anon` key that you copied [earlier](#get-the-api-keys).

```bash .env.local
VITE_SUPABASE_URL=YOUR_SUPABASE_URL
VITE_SUPABASE_ANON_KEY=YOUR_SUPABASE_ANON_KEY
```

The `supabaseClient` will be used in fetch calls to Supabase endpoints from our app. As we'll see below, the client is instrumental in implementing authentication using Refine's auth provider methods and CRUD actions with appropriate data provider methods.

One optional step is to update the CSS file `src/App.css` to make the app look nice.
You can find the full contents of this file [here](https://raw.githubusercontent.com/supabase/supabase/master/examples/user-management/refine-user-management/src/App.css).

In order for us to add login and user profile pages in this App, we have to tweak the `<Refine />` component inside `App.tsx`.


### The `<Refine />` component

The `App.tsx` file initially looks like this:

We'd like to focus on the [`<Refine />`](https://refine.dev/docs/api-reference/core/components/refine-config/) component, which comes with several props passed to it. Notice the `dataProvider` prop. It uses a `dataProvider()` function with `supabaseClient` passed as argument to generate the data provider object. The `authProvider` object also uses `supabaseClient` in implementing its methods. You can look it up in `src/authProvider.ts` file.


## Customize `authProvider`

If you examine the `authProvider` object you can notice that it has a `login` method that implements a OAuth and Email / Password strategy for authentication. We'll, however, remove them and use Magic Links to allow users sign in with their email without using passwords.

We want to use `supabaseClient` auth's `signInWithOtp` method inside `authProvider.login` method:

```ts name=src/authProvider.ts
login: async ({ email }) => {
  try {
    const { error } = await supabaseClient.auth.signInWithOtp({ email });

    if (!error) {
      alert("Check your email for the login link!");
      return {
        success: true,
      };
    };

    throw error;
  } catch (e: any) {
    alert(e.message);
    return {
      success: false,
      e,
    };
  }
},
```

We also want to remove `register`, `updatePassword`, `forgotPassword` and `getPermissions` properties, which are optional type members and also not necessary for our app. The final `authProvider` object looks like this:


### Set up a login component

We have chosen to use the headless refine core package that comes with no supported UI framework. So, let's set up a plain React component to manage logins and sign ups.

Create and edit `src/components/auth.tsx`:

Notice we are using the [`useLogin()`](https://refine.dev/docs/api-reference/core/hooks/authentication/useLogin/) refine auth hook to grab the `mutate: login` method to use inside `handleLogin()` function and `isLoading` state for our form submission. The `useLogin()` hook conveniently offers us access to `authProvider.login` method for authenticating the user with OTP.


### Account page

After a user is signed in we can allow them to edit their profile details and manage their account.

Let's create a new component for that in `src/components/account.tsx`.

Notice above that, we are using three refine hooks, namely the [`useGetIdentity()`](https://refine.dev/docs/api-reference/core/hooks/authentication/useGetIdentity/), [`useLogOut()`](https://refine.dev/docs/api-reference/core/hooks/authentication/useLogout/) and [`useForm()`](https://refine.dev/docs/packages/documentation/react-hook-form/useForm/) hooks.

`useGetIdentity()` is a auth hook that gets the identity of the authenticated user. It grabs the current user by invoking the `authProvider.getIdentity` method under the hood.

`useLogOut()` is also an auth hook. It calls the `authProvider.logout` method to end the session.

`useForm()`, in contrast, is a data hook that exposes a series of useful objects that serve the edit form. For example, we are grabbing the `onFinish` function to submit the form with the `handleSubmit` event handler. We are also using `formLoading` property to present state changes of the submitted form.

The `useForm()` hook is a higher-level hook built on top of Refine's `useForm()` core hook. It fully supports form state management, field validation and submission using React Hook Form. Behind the scenes, it invokes the `dataProvider.getOne` method to get the user profile data from our Supabase `/profiles` endpoint and also invokes `dataProvider.update` method when `onFinish()` is called.


### Launch!

Now that we have all the components in place, let's define the routes for the pages in which they should be rendered.

Add the routes for `/login` with the `<Auth />` component and the routes for `index` path with the `<Account />` component. So, the final `App.tsx`:

Let's test the App by running the server again:

```bash
npm run dev
```

And then open the browser to [localhost:5173](http://localhost:5173) and you should see the completed app.

![Supabase refine](/docs/img/supabase-refine-demo.png)


## Bonus: Profile photos

Every Supabase project is configured with [Storage](/docs/guides/storage) for managing large files like photos and videos.


### Create an upload widget

Let's create an avatar for the user so that they can upload a profile photo. We can start by creating a new component:

Create and edit `src/components/avatar.tsx`:


### Add the new widget

And then we can add the widget to the Account page at `src/components/account.tsx`:

At this stage, you have a fully functional application!


# Build a User Management App with SolidJS



![Supabase User Management example](/docs/img/user-management-demo.png)


## Building the app

Let's start building the SolidJS app from scratch.


### Initialize a SolidJS app

We can use [degit](https://github.com/Rich-Harris/degit) to initialize an app called `supabase-solid`:

```bash
npx degit solidjs/templates/ts supabase-solid
cd supabase-solid
```

Then let's install the only additional dependency: [supabase-js](https://github.com/supabase/supabase-js)

```bash
npm install @supabase/supabase-js
```

And finally we want to save the environment variables in a `.env`.
All we need are the API URL and the `anon` key that you copied [earlier](#get-the-api-keys).

Now that we have the API credentials in place, let's create a helper file to initialize the Supabase client. These variables will be exposed
on the browser, and that's completely fine since we have [Row Level Security](/docs/guides/auth#row-level-security) enabled on our Database.


### App styling (optional)

An optional step is to update the CSS file `src/index.css` to make the app look nice.
You can find the full contents of this file [here](https://raw.githubusercontent.com/supabase/supabase/master/examples/user-management/solid-user-management/src/index.css).


### Set up a login component

Let's set up a SolidJS component to manage logins and sign ups. We'll use Magic Links, so users can sign in with their email without using passwords.


### Account page

After a user is signed in we can allow them to edit their profile details and manage their account.

Let's create a new component for that called `Account.tsx`.


### Launch!

Now that we have all the components in place, let's update `App.tsx`:

Once that's done, run this in a terminal window:

```bash
npm start
```

And then open the browser to [localhost:3000](http://localhost:3000) and you should see the completed app.

![Supabase SolidJS](/docs/img/supabase-solidjs-demo.png)


## Bonus: Profile photos

Every Supabase project is configured with [Storage](/docs/guides/storage) for managing large files like photos and videos.


### Create an upload widget

Let's create an avatar for the user so that they can upload a profile photo. We can start by creating a new component:


### Add the new widget

And then we can add the widget to the Account page:

At this stage you have a fully functional application!


# Build a User Management App with Svelte



![Supabase User Management example](/docs/img/user-management-demo.png)


## Building the app

Let's start building the Svelte app from scratch.


### Initialize a Svelte app

We can use the Vite Svelte TypeScript Template to initialize an app called `supabase-svelte`:

```bash
npm create vite@latest supabase-svelte -- --template svelte-ts
cd supabase-svelte
npm install
```

Then let's install the only additional dependency: [supabase-js](https://github.com/supabase/supabase-js)

```bash
npm install @supabase/supabase-js
```

And finally we want to save the environment variables in a `.env`.
All we need are the API URL and the `anon` key that you copied [earlier](#get-the-api-keys).

Now that we have the API credentials in place, let's create a helper file to initialize the Supabase client. These variables will be exposed
on the browser, and that's completely fine since we have [Row Level Security](/docs/guides/auth#row-level-security) enabled on our Database.


### App styling (optional)

An optional step is to update the CSS file `src/app.css` to make the app look nice.
You can find the full contents of this file [here](https://raw.githubusercontent.com/supabase/supabase/master/examples/user-management/svelte-user-management/src/app.css).


### Set up a login component

Let's set up a Svelte component to manage logins and sign ups. We'll use Magic Links, so users can sign in with their email without using passwords.


### Account page

After a user is signed in we can allow them to edit their profile details and manage their account.
Let's create a new component for that called `Account.svelte`.


### Launch!

Now that we have all the components in place, let's update `App.svelte`:

Once that's done, run this in a terminal window:

```bash
npm run dev
```

And then open the browser to [localhost:5173](http://localhost:5173) and you should see the completed app.

![Supabase Svelte](/docs/img/supabase-svelte-demo.png)


## Bonus: Profile photos

Every Supabase project is configured with [Storage](/docs/guides/storage) for managing large files like photos and videos.


### Create an upload widget

Let's create an avatar for the user so that they can upload a profile photo. We can start by creating a new component:


### Add the new widget

And then we can add the widget to the Account page:

At this stage you have a fully functional application!


# Build a User Management App with SvelteKit



![Supabase User Management example](/docs/img/user-management-demo.png)


## Building the app

Let's start building the Svelte app from scratch.


### Initialize a Svelte app

We can use the [SvelteKit Skeleton Project](https://kit.svelte.dev/docs) to initialize an app called `supabase-sveltekit` (for this tutorial we will be using TypeScript):

```bash
npm create svelte@latest supabase-sveltekit
cd supabase-sveltekit
npm install
```

Then install the Supabase client library: [supabase-js](https://github.com/supabase/supabase-js)

```bash
npm install @supabase/supabase-js
```

And finally we want to save the environment variables in a `.env`.
All we need are the `SUPABASE_URL` and the `SUPABASE_KEY` key that you copied [earlier](#get-the-api-keys).

Optionally, add `src/styles.css` with the [CSS from the example](https://raw.githubusercontent.com/supabase/supabase/master/examples/user-management/sveltekit-user-management/src/styles.css).


### Creating a Supabase client for SSR

The `ssr` package configures Supabase to use Cookies, which is required for server-side languages and frameworks.

Install the Supabase packages:

```bash
npm install @supabase/ssr @supabase/supabase-js
```

Creating a Supabase client with the `ssr` package automatically configures it to use Cookies. This means your user's session is available throughout the entire SvelteKit stack - page, layout, server, hooks.

Add the code below to your `src/hooks.server.ts` to initialize the client on the server:

If you are using TypeScript the compiler might complain about `event.locals.supabase` and `event.locals.safeGetSession`, this can be fixed by updating your `src/app.d.ts` with the content below:

Create a new `src/routes/+layout.server.ts` file to handle the session on the server-side.

Create a new `src/routes/+layout.ts` file to handle the session and the `supabase` object on the client-side.

Update your `src/routes/+layout.svelte`:


## Set up a login page

Create a magic link login/signup page for your application:

Create a `src/routes/+page.server.ts` file that will handle our magic link form when submitted.


### Email template

Change the email template to support a server-side authentication flow.

Before we proceed, let's change the email template to support sending a token hash:

*   Go to the [Auth templates](/dashboard/project/_/auth/templates) page in your dashboard.
*   Select `Confirm signup` template.
*   Change `{{ .ConfirmationURL }}` to `{{ .SiteURL }}/auth/confirm?token_hash={{ .TokenHash }}&type=email`.
*   Repeat the previous step for `Magic link` template.


### Confirmation endpoint

As we are working in a server-side rendering (SSR) environment, it is necessary to create a server endpoint responsible for exchanging the `token_hash` for a session.

In the following code snippet, we perform the following steps:

*   Retrieve the `token_hash` sent back from the Supabase Auth server using the `token_hash` query parameter.
*   Exchange this `token_hash` for a session, which we store in storage (in this case, cookies).
*   Finally, the user is redirected to the `account` page or the `error` page.


### Authentication error page

If there is an error with confirming the token you will be redirect to this error page.


### Account page

After a user is signed in, they need to be able to edit their profile details and manage their account.
Create a new `src/routes/account/+page.svelte` file with the content below.

Now create the associated `src/routes/account/+page.server.ts` file that will handle loading our data from the server through the `load` function
and handle all our form actions through the `actions` object.

```ts name=src/routes/account/+page.server.ts
import { fail, redirect } from '@sveltejs/kit'
import type { Actions, PageServerLoad } from './$types'

export const load: PageServerLoad = async ({ locals: { supabase, safeGetSession } }) => {
  const { session } = await safeGetSession()

  if (!session) {
    redirect(303, '/')
  }

  const { data: profile } = await supabase
    .from('profiles')
    .select(`username, full_name, website, avatar_url`)
    .eq('id', session.user.id)
    .single()

  return { session, profile }
}

export const actions: Actions = {
  update: async ({ request, locals: { supabase, safeGetSession } }) => {
    const formData = await request.formData()
    const fullName = formData.get('fullName') as string
    const username = formData.get('username') as string
    const website = formData.get('website') as string
    const avatarUrl = formData.get('avatarUrl') as string

    const { session } = await safeGetSession()

    const { error } = await supabase.from('profiles').upsert({
      id: session?.user.id,
      full_name: fullName,
      username,
      website,
      avatar_url: avatarUrl,
      updated_at: new Date(),
    })

    if (error) {
      return fail(500, {
        fullName,
        username,
        website,
        avatarUrl,
      })
    }

    return {
      fullName,
      username,
      website,
      avatarUrl,
    }
  },
  signout: async ({ locals: { supabase, safeGetSession } }) => {
    const { session } = await safeGetSession()
    if (session) {
      await supabase.auth.signOut()
      redirect(303, '/')
    }
  },
}
```


### Launch!

Now that we have all the pages in place, run this in a terminal window:

```bash
npm run dev
```

And then open the browser to [localhost:5173](http://localhost:5173) and you should see the completed app.

![Supabase Svelte](/docs/img/supabase-svelte-demo.png)


## Bonus: Profile photos

Every Supabase project is configured with [Storage](/docs/guides/storage) for managing large files like photos and videos.


### Create an upload widget

Let's create an avatar for the user so that they can upload a profile photo. We can start by creating a new component called `Avatar.svelte` in the `src/routes/account` directory:


### Add the new widget

And then we can add the widget to the Account page:

At this stage you have a fully functional application!


# Build a User Management App with Swift and SwiftUI



![Supabase User Management example](/docs/img/supabase-swift-demo.png)


## Building the app

Let's start building the SwiftUI app from scratch.


### Create a SwiftUI app in Xcode

Open Xcode and create a new SwiftUI project.

Add the [supabase-swift](https://github.com/supabase/supabase-swift) dependency.

Add the `https://github.com/supabase/supabase-swift` package to your app. For instructions, see the [Apple tutorial on adding package dependencies](https://developer.apple.com/documentation/xcode/adding-package-dependencies-to-your-app).

Create a helper file to initialize the Supabase client.
You need the API URL and the `anon` key that you copied [earlier](#get-the-api-keys).
These variables will be exposed on the application, and that's completely fine since you have
[Row Level Security](/docs/guides/auth#row-level-security) enabled on your database.


### Set up a login view

Set up a SwiftUI view to manage logins and sign ups.
Users should be able to sign in using a magic link.


### Account view

After a user is signed in, you can allow them to edit their profile details and manage their account.

Create a new view for that called `ProfileView.swift`.


### Models

In `ProfileView.swift`, you used 2 model types for deserializing the response and serializing the request to Supabase. Add those in a new `Models.swift` file.


### Launch!

Now that you've created all the views, add an entry point for the application. This will verify if the user has a valid session and route them to the authenticated or non-authenticated state.

Add a new `AppView.swift` file.

Update the entry point to the newly created `AppView`. Run in Xcode to launch your application in the simulator.


## Bonus: Profile photos

Every Supabase project is configured with [Storage](/docs/guides/storage) for managing large files like
photos and videos.


### Add `PhotosPicker`

Let's add support for the user to pick an image from the library and upload it.
Start by creating a new type to hold the picked avatar image:


#### Add `PhotosPicker` to profile page

Finally, update your Models.

You no longer need the `UpdateProfileParams` struct, as you can now reuse the `Profile` struct for both request and response calls.

At this stage you have a fully functional application!


# Build a User Management App with Vue 3



![Supabase User Management example](/docs/img/user-management-demo.png)


## Building the app

Let's start building the Vue 3 app from scratch.


### Initialize a Vue 3 app

We can quickly use [Vite with Vue 3 Template](https://vitejs.dev/guide/#scaffolding-your-first-vite-project) to initialize
an app called `supabase-vue-3`:

```bash
# npm 6.x
npm create vite@latest supabase-vue-3 --template vue

# npm 7+, extra double-dash is needed:
npm create vite@latest supabase-vue-3 -- --template vue

cd supabase-vue-3
```

Then let's install the only additional dependency: [supabase-js](https://github.com/supabase/supabase-js)

```bash
npm install @supabase/supabase-js
```

And finally we want to save the environment variables in a `.env`.
All we need are the API URL and the `anon` key that you copied [earlier](#get-the-api-keys).

With the API credentials in place, create an `src/supabase.js` helper file to initialize the Supabase client. These variables are exposed
on the browser, and that's completely fine since we have [Row Level Security](/docs/guides/auth#row-level-security) enabled on our Database.

Optionally, update [src/style.css](https://raw.githubusercontent.com/supabase/supabase/master/examples/user-management/vue3-user-management/src/style.css) to style the app.


### Set up a login component

Set up an `src/components/Auth.vue` component to manage logins and sign ups. We'll use Magic Links, so users can sign in with their email without using passwords.


### Account page

After a user is signed in we can allow them to edit their profile details and manage their account.
Create a new `src/components/Account.vue` component to handle this.


### Launch!

Now that we have all the components in place, let's update `App.vue`:

Once that's done, run this in a terminal window:

```bash
npm run dev
```

And then open the browser to [localhost:5173](http://localhost:5173) and you should see the completed app.

![Supabase Vue 3](/docs/img/supabase-vue-3-demo.png)


## Bonus: Profile photos

Every Supabase project is configured with [Storage](/docs/guides/storage) for managing large files like photos and videos.


### Create an upload widget

Create a new `src/components/Avatar.vue` component that allows users to upload profile photos:


### Add the new widget

And then we can add the widget to the Account page in `src/components/Account.vue`:

At this stage you have a fully functional application!


# Integrations



Supabase integrates with many of your favorite third-party services.


## Vercel Marketplace

Create and manage your Supabase projects directly through Vercel. [Get started with Vercel](/docs/guides/integrations/vercel-marketplace).


## Supabase Marketplace

Browse tools for extending your Supabase project. [Browse the Supabase Marketplace](/partners/integrations).


# Build a Supabase Integration (Beta)

This guide steps through building a Supabase Integration using OAuth2 and the management API, allowing you to manage users' organizations and projects on their behalf.

Using OAuth2.0 you can retrieve an access and refresh token that grant your application full access to the [Management API](https://supabase.com/docs/reference/api/introduction) on behalf of the user.


## Create an OAuth app

1.  In your organization's settings, navigate to the [**OAuth Apps**](/dashboard/org/_/apps) tab.
2.  In the upper-right section of the page, click **Add application**.
3.  Fill in the required details and click **Confirm**.


## Show a "Connect Supabase" button

In your user interface, add a "Connect Supabase" button to kick off the OAuth flow. Follow the design guidelines outlined in our [brand assets](/brand-assets).


## Implementing the OAuth 2.0 flow

Once you've published your OAuth App on Supabase, you can use the OAuth 2.0 protocol get authorization from Supabase users to manage their organizations and projects.

You can use your preferred OAuth2 client or follow the steps below. You can see an example implementation in TypeScript using Supabase Edge Functions [on our GitHub](https://github.com/supabase/supabase/tree/master/examples/edge-functions/supabase/functions/connect-supabase).


### Redirecting to the authorize URL

Within your app's UI, redirect the user to [`https://api.supabase.com/v1/oauth/authorize`](https://api.supabase.com/api/v1#/oauth%20\(beta\)/authorize). Make sure to include all required query parameters such as:

*   `client_id`: Your client id from the app creation above.
*   `redirect_uri`: The URL where Supabase will redirect the user to after providing consent.
*   `response_type`: Set this to `code`.
*   `state`: Information about the state of your app. Note that `redirect_uri` and `state` together cannot exceed 4kB in size.
*   (Recommended) PKCE: We strongly recommend using the PKCE flow for increased security. Generate a random value before taking the user to the authorize endpoint. This value is called code verifier. Hash it with SHA256 and include it as the `code_challenge` parameter, while setting `code_challenge_method` to `S256`. In the next step, you would need to provide the code verifier to get the first access and refresh token.
*   \[deprecated] `scope`: Scopes are configured when you create your OAuth app. Read the [docs](/docs/guides/platform/oauth-apps/oauth-scopes) for more details.

```ts
router.get('/connect-supabase/login', async (ctx) => {
  // Construct the URL for the authorization redirect and get a PKCE codeVerifier.
  const { uri, codeVerifier } = await oauth2Client.code.getAuthorizationUri()
  console.log(uri.toString())
  // console.log: https://api.supabase.com/v1/oauth/authorize?response_type=code&client_id=7673bde9-be72-4d75-bd5e-b0dba2c49b38&redirect_uri=http%3A%2F%2Flocalhost%3A54321%2Ffunctions%2Fv1%2Fconnect-supabase%2Foauth2%2Fcallback&scope=all&code_challenge=jk06R69S1bH9dD4td8mS5kAEFmEbMP5P0YrmGNAUVE0&code_challenge_method=S256

  // Store the codeVerifier in the user session (cookie).
  ctx.state.session.flash('codeVerifier', codeVerifier)

  // Redirect the user to the authorization endpoint.
  ctx.response.redirect(uri)
})
```

Find the full example on [GitHub](https://github.com/supabase/supabase/tree/master/examples/edge-functions/supabase/functions/connect-supabase).


### Handling the callback

Once the user consents to providing API access to your OAuth App, Supabase will redirect the user to the `redirect_uri` provided in the previous step. The URL will contain these query parameters:

*   `code`: An authorization code you should exchange with Supabase to get the access and refresh token.
*   `state`: The value you provided in the previous step, to help you associate the request with the user. The `state` property returned here should be compared to the `state` you sent previously.

Exchange the authorization code for an access and refresh token by calling [`POST https://api.supabase.com/v1/oauth/token`](https://api.supabase.com/api/v1#/oauth%20\(beta\)/token) with the following query parameters as content-type `application/x-www-form-urlencoded`:

*   `grant_type`: The value `authorization_code`.
*   `code`: The `code` returned in the previous step.
*   `redirect_uri`: This must be exactly the same URL used in the first step.
*   (Recommended) `code_verifier`: If you used the PKCE flow in the first step, include the code verifier as `code_verifier`.

As per OAuth2 spec, provide the client id and client secret as basic auth header:

*   `client_id`: The unique client ID identifying your OAuth App.
*   `client_secret`: The secret that authenticates your OAuth App to Supabase.

```ts
router.get('/connect-supabase/oauth2/callback', async (ctx) => {
  // Make sure the codeVerifier is present for the user's session.
  const codeVerifier = ctx.state.session.get('codeVerifier') as string
  if (!codeVerifier) throw new Error('No codeVerifier!')

  // Exchange the authorization code for an access token.
  const tokens = await fetch(config.tokenUri, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      Accept: 'application/json',
      Authorization: `Basic ${btoa(`${config.clientId}:${config.clientSecret}`)}`,
    },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      code: ctx.request.url.searchParams.get('code') || '',
      redirect_uri: config.redirectUri,
      code_verifier: codeVerifier,
    }),
  }).then((res) => res.json())
  console.log('tokens', tokens)

  // Store the tokens in your DB for future use.

  ctx.response.body = 'Success'
})
```

Find the full example on [GitHub](https://github.com/supabase/supabase/tree/master/examples/edge-functions/supabase/functions/connect-supabase).


## Refreshing an access token

You can use the [`POST /v1/oauth/token`](https://api.supabase.com/api/v1#/oauth%20\(beta\)/token) endpoint to refresh an access token using the refresh token returned at the end of the previous section.

If the user has revoked access to your application, you will not be able to refresh a token. Furthermore, access tokens will stop working. Make sure you handle HTTP Unauthorized errors when calling any Supabase API.


## Calling the Management API

Refer to [the Management API reference](/docs/reference/api/introduction#authentication) to learn more about authentication with the Management API.


### Use the JavaScript (TypeScript) SDK

For convenience, when working with JavaScript/TypeScript, you can use the [supabase-management-js](https://github.com/supabase-community/supabase-management-js#supabase-management-js) library.

```ts
import { SupabaseManagementAPI } from 'supabase-management-js'

const client = new SupabaseManagementAPI({ accessToken: '<access token>' })
```


## Integration recommendations

There are a couple common patterns you can consider adding to your integration that can facilitate a great user experience.


### Store API keys in env variables

Some integrations, e.g. like [Cloudflare Workers](/partners/integrations/cloudflare-workers) provide convenient access to the API URL and API keys to allow user to speed up development.

Using the management API, you can retrieve a project's API credentials using the [`/projects/{ref}/api-keys` endpoint](https://api.supabase.com/api/v1#/projects/getProjectApiKeys).


### Pre-fill database connection details

If your integration directly connects to the project's database, you can pref-fill the Postgres connection details for the user, it follows this schema:

    postgresql://postgres:[DB-PASSWORD]@db.[REF].supabase.co:5432/postgres

Note that you cannot retrieve the database password via the management API, so for the user's existing projects you will need to collect their database password in your UI.


### Create new projects

Use the [`/v1/projects` endpoint](https://api.supabase.com/api/v1#/projects/createProject) to create a new project.

When creating a new project, you can either ask the user to provide a database password, or you can generate a secure password for them. In any case, make sure to securely store the database password on your end which will allow you to construct the Postgres URI.


### Configure custom Auth SMTP

You can configure the user's [custom SMTP settings](https://supabase.com/docs/guides/auth/auth-smtp) using the [`/config/auth` endpoint](https://api.supabase.com/api/v1#/projects%20config/updateV1AuthConfig).


### Handling dynamic redirect URLs

To handle multiple, dynamically generated redirect URLs within the same OAuth app, you can leverage the `state` query parameter. When starting the OAuth process, include the desired, encoded redirect URL in the `state` parameter.
Once authorization is complete, we will sends the `state` value back to your app. You can then verify its integrity and extract the correct redirect URL, decoding it and redirecting the user to the correct URL.


## Current limitations

Only some features are available until we roll out fine-grained access control. If you need full database access, you will need to prompt the user for their database password.


# Scopes for your OAuth App

Scopes let you specify the level of access your integration needs

Scopes restrict access to the specific [Supabase Management API endpoints](/docs/reference/api/introduction) for OAuth tokens. All scopes can be specified as read and/or write.

Scopes are set when you [create an OAuth app](/docs/guides/platform/oauth-apps/build-a-supabase-integration#create-an-oauth-app) in the Supabase Dashboard.


## Available scopes

| Name             | Type    | Description                                                                                                                                                                                                                                                                            |
| ---------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Auth`           | `Read`  | Retrieve a project's auth configurationRetrieve a project's SAML SSO providers                                                                                                                                                                                                    |
| `Auth`           | `Write` | Update a project's auth configurationCreate, update, or delete a project's SAML SSO providers                                                                                                                                                                                     |
| `Database`       | `Read`  | Retrieve the database configurationRetrieve the pooler configurationRetrieve SQL snippetsCheck if the database is in read-only modeRetrieve a database's SSL enforcement configurationRetrieve a database's schema typescript types                           |
| `Database`       | `Write` | Create a SQL queryEnable database webhooks on the projectUpdate the project's database configurationUpdate the pooler configurationUpdate a database's SSL enforcement configurationDisable read-only mode for 15minsCreate a PITR backup for a database |
| `Domains`        | `Read`  | Retrieve the custom domains for a projectRetrieve the vanity subdomain configuration for a project                                                                                                                                                                                |
| `Domains`        | `Write` | Activate, initialize, reverify, or delete the custom domain for a projectActivate, delete or check the availability of a vanity subdomain for a project                                                                                                                           |
| `Edge Functions` | `Read`  | Retrieve information about a project's edge functions                                                                                                                                                                                                                                  |
| `Edge Functions` | `Write` | Create, update, or delete an edge function                                                                                                                                                                                                                                             |
| `Environment`    | `Read`  | Retrieve branches in a project                                                                                                                                                                                                                                                         |
| `Environment`    | `Write` | Create, update, or delete a branch                                                                                                                                                                                                                                                     |
| `Organizations`  | `Read`  | Retrieve an organization's metadataRetrieve all members in an organization                                                                                                                                                                                                        |
| `Organizations`  | `Write` | N/A                                                                                                                                                                                                                                                                                    |
| `Projects`       | `Read`  | Retrieve a project's metadataCheck if a project's database is eligible for upgradeRetrieve a project's network restrictionsRetrieve a project's network bans                                                                                                            |
| `Projects`       | `Write` | Create a projectUpgrade a project's databaseRemove a project's network bansUpdate a project's network restrictions                                                                                                                                                      |
| `Rest`           | `Read`  | Retrieve a project's PostgREST configuration                                                                                                                                                                                                                                           |
| `Rest`           | `Write` | Update a project's PostgREST configuration                                                                                                                                                                                                                                             |
| `Secrets`        | `Read`  | Retrieve a project's API keysRetrieve a project's secretsRetrieve a project's pgsodium config                                                                                                                                                                                |
| `Secrets`        | `Write` | Create or update a project's secretsUpdate a project's pgsodium configuration                                                                                                                                                                                                     |


# Supabase Marketplace



The Supabase Marketplace brings together all the tools you need to extend your Supabase project. This includes:

*   [Experts](https://supabase.com/partners/experts) - partners to help you build and support your Supabase project.
*   [Integrations](https://supabase.com/partners/integrations) - extend your projects with external Auth, Caching, Hosting, and Low-code tools.


## Build an integration

Supabase provides several integration points:

*   The [Postgres connection](/docs/guides/database/connecting-to-postgres). Anything that works with Postgres also works with Supabase projects.
*   The [Project REST API](/docs/guides/api#rest-api-overview) & client libraries.
*   The [Project GraphQL API](/docs/guides/api#graphql-api-overview).
*   The [Platform API](/docs/reference/api).


## List your integration

[Apply to the Partners program](https://supabase.com/partners/integrations#become-a-partner) to list your integration in the Partners marketplace and in the Supabase docs.

Integrations are assessed on the following criteria:

*   **Business viability**
    While we welcome everyone to built an integration, we only list companies that are deemed to be long-term viable. This includes an official business registration and bank account, meaningful revenue, or Venture Capital backing. We require this criteria to ensure the health of the marketplace.
*   **Compliance**
    Integrations should not infringe on the Supabase brand/trademark. In short, you cannot use "Supabase" in the name. As the listing appears on the Supabase domain, we don't want to mislead developers into thinking that an integration is an official product.
*   **Service Level Agreements**
    All listings are required to have their own Terms and Conditions, Privacy Policy, and Acceptable Use Policy, and the company must have resources to meet their SLAs.
*   **Maintainability**
    All integrations are required to be maintained and functional with Supabase, and the company may be assessed on your ability to remain functional over a long time horizon.


# Vercel Marketplace



## Overview

The Vercel Marketplace is a feature that allows you to manage third-party resources, such as Supabase, directly from the Vercel platform. This integration offers a seamless experience with unified billing, streamlined authentication, and easy access management for your team.

When you create an organization and projects through Vercel Marketplace, they function just like those created directly within Supabase. However, the billing is handled through your Vercel account, and you can manage your resources directly from the Vercel dashboard or CLI. Additionally, environment variables are automatically synchronized, making them immediately available for your connected projects.

For more information, see [Introducing the Vercel Marketplace](https://vercel.com/blog/introducing-the-vercel-marketplace) blog post.


## Quickstart


### Via template


### Via Vercel Marketplace

Details coming soon..


### Connecting to Supabase project

Supabase Projects created via Vercel Marketplace are automatically synchronized with connected Vercel projects. This synchronization includes setting essential environment variables, such as:

    POSTGRES_URL
    POSTGRES_PRISMA_URL
    POSTGRES_URL_NON_POOLING
    POSTGRES_USER
    POSTGRES_HOST
    POSTGRES_PASSWORD
    POSTGRES_DATABASE
    SUPABASE_SERVICE_ROLE_KEY
    SUPABASE_ANON_KEY
    SUPABASE_URL
    SUPABASE_JWT_SECRET
    NEXT_PUBLIC_SUPABASE_ANON_KEY
    NEXT_PUBLIC_SUPABASE_URL

These variables ensure your applications can connect securely to the database and interact with Supabase APIs.


## Studio support

Accessing Supabase Studio is simple through the Vercel dashboard. You can open Supabase Studio from either the Integration installation page or the Vercel Storage page.
Depending on your entry point, you'll either land on the Supabase dashboard homepage or be redirected to the corresponding Supabase Project.

Supabase Studio provides tools such as:

*   **SQL Editor:** Run SQL queries against your database.
*   **Table Editor:** Create, edit, and delete tables and columns.
*   **Log Explorer:** Inspect real-time logs for your database.
*   **Postgres Upgrades:** Upgrade your Postgres instance to the latest version.
*   **Compute Upgrades:** Scale the compute resources allocated to your database.


## Permissions

There is a direct one-to-one relationship between a Supabase Organization and a Vercel team. Installing the integration or launching your first Supabase Project through Vercel triggers the creation of a corresponding Supabase Organization if one doesn’t already exist.

When Vercel users interact with Supabase, they are automatically assigned Supabase accounts. New users get a Supabase account linked to their primary email, while existing users have their Vercel and Supabase accounts linked.

*   The user who initiates the creation of a Vercel Storage database is assigned the `owner` role in the new Supabase organization.
*   Subsequent users are assigned roles based on their Vercel role, such as `developer` for `member` and `owner` for `owner`.

Role management is handled directly in the Vercel dashboard, and changes are synchronized with Supabase.

Note: you can invite non-Vercel users to your Supabase Organization, but their permissions won't be synchronized with Vercel.


## Pricing

Pricing for databases created through Vercel Marketplace is identical to those created directly within Supabase. Detailed pricing information is available on the [Supabase pricing page](https://supabase.com/pricing).

The [usage page](https://supabase.com/dashboard/org/_/usage) tracks the usage of your Vercel databases, with this information sent to Vercel for billing, which appears on your Vercel invoice.

Note: Supabase Organization billing cycle is separate from Vercel's. Plan changes will reset the billing cycle to the day of the change, with the initial billing cycle starting the day you install the integration.


## Limitations

When using Vercel Marketplace, the following limitations apply:

*   Projects can only be created or removed via the Vercel dashboard.
*   Organizations cannot be removed manually; they are removed only if you uninstall the Vercel Marketplace Integration.
*   Owners cannot be added manually within the Supabase dashboard.
*   Invoices and payments must be managed through the Vercel dashboard, not the Supabase dashboard.


# Local Development & CLI

Learn how to develop locally and use the Supabase CLI

Develop locally while running the Supabase stack on your machine.


## Quickstart

1.  Install the Supabase CLI:

2.  In your repo, initialize the Supabase project:

3.  Start the Supabase stack:

4.  View your local Supabase instance at <http://localhost:54323>.


## Local development

Local development with Supabase allows you to work on your projects in a self-contained environment on your local machine. Working locally has several advantages:

1.  Faster development: You can make changes and see results instantly without waiting for remote deployments.
2.  Offline work: You can continue development even without an internet connection.
3.  Cost-effective: Local development is free and doesn't consume your project's quota.
4.  Enhanced privacy: Sensitive data remains on your local machine during development.
5.  Easy testing: You can experiment with different configurations and features without affecting your production environment.

To get started with local development, you'll need to install the [Supabase CLI](#cli) and Docker. The Supabase CLI allows you to start and manage your local Supabase stack, while Docker is used to run the necessary services.

Once set up, you can initialize a new Supabase project, start the local stack, and begin developing your application using local Supabase services. This includes access to a local Postgres database, Auth, Storage, and other Supabase features.


## CLI

The Supabase CLI is a powerful tool that enables developers to manage their Supabase projects directly from the terminal. It provides a suite of commands for various tasks, including:

*   Setting up and managing local development environments
*   Generating TypeScript types for your database schema
*   Handling database migrations
*   Managing environment variables and secrets
*   Deploying your project to the Supabase platform

With the CLI, you can streamline your development workflow, automate repetitive tasks, and maintain consistency across different environments. It's an essential tool for both local development and CI/CD pipelines.

See the [CLI Getting Started guide](/docs/guides/local-development/cli/getting-started) for more information.


# Supabase CLI

Develop locally, deploy to the Supabase Platform, and set up CI/CD workflows

The Supabase CLI enables you to run the entire Supabase stack locally, on your machine or in a CI environment. With just two commands, you can set up and start a new local project:

1.  `supabase init` to create a new local project
2.  `supabase start` to launch the Supabase services


## Installing the Supabase CLI


## Updating the Supabase CLI

When a new [version](https://github.com/supabase/cli/releases) is released, you can update the CLI using the same methods.

If you have any Supabase containers running locally, stop them and delete their data volumes before proceeding with the upgrade. This ensures that Supabase managed services can apply new migrations on a clean state of the local database.


## Running Supabase locally

The Supabase CLI uses Docker containers to manage the local development stack. Follow the official guide to install and configure [Docker Desktop](https://docs.docker.com/desktop):

Inside the folder where you want to create your project, run:

```bash
supabase init
```

This will create a new `supabase` folder. It's safe to commit this folder to your version control system.

Now, to start the Supabase stack, run:

```bash
supabase start
```

This takes time on your first run because the CLI needs to download the Docker images to your local machine. The CLI includes the entire Supabase toolset, and a few additional images that are useful for local development (like a local SMTP server and a database diff tool).


## Access your project's services

Once all of the Supabase services are running, you'll see output containing your local Supabase credentials. It should look like this, with urls and keys that you'll use in your local project:

```

Started supabase local development setup.

         API URL: http://localhost:54321
          DB URL: postgresql://postgres:postgres@localhost:54322/postgres
      Studio URL: http://localhost:54323
    Inbucket URL: http://localhost:54324
        anon key: eyJh......
service_role key: eyJh......

```


## Stopping local services

When you are finished working on your Supabase project, you can stop the stack (without resetting your local database):

```bash
supabase stop
```


## Learn more

*   [CLI configuration](/docs/guides/local-development/cli/config)
*   [CLI reference](/docs/reference/cli)


# Testing and linting

Using the CLI to test your Supabase project.

The Supabase CLI provides a set of tools to help you test and lint your Postgres database and Edge\` Functions.


## Testing your database

The Supabase CLI provides Postgres linting using the `supabase test db` command.

```markdown
supabase test db --help
Tests local database with pgTAP

Usage:
  supabase test db [flags]
```

This is powered by the [pgTAP](https://supabase.com/docs/guides/database/extensions/pgtap) extension. You can find a full guide to writing and running tests in the [Testing your database](/docs/guides/database/testing) section.


### Test helpers

Our friends at [Basejump](https://usebasejump.com/) have created a useful set of Database [Test Helpers](https://github.com/usebasejump/supabase-test-helpers), with an accompanying [blog post](https://usebasejump.com/blog/testing-on-supabase-with-pgtap).


### Running database tests in CI

Use our GitHub Action to [automate your database tests](/docs/guides/cli/github-action/testing#testing-your-database).


## Testing your Edge Functions

Edge Functions are powered by Deno, which provides a [native set of testing tools](https://deno.land/manual@v1.35.3/basics/testing). We extend this functionality in the Supabase CLI. You can find a detailed guide in the [Edge Functions section](/docs/guides/functions/unit-test).


## Testing Auth emails

The Supabase CLI uses [Inbucket](https://github.com/inbucket/inbucket) to capture emails sent from your local machine. This is useful for testing emails sent from Supabase Auth.


### Accessing Inbucket

By default, Inbucket is available at [localhost:54324](http://localhost:54324) when you run `supabase start`. Open this URL in your browser to view the emails.


### Going into production

The "default" email provided by Supabase is only for development purposes. It is [heavily restricted](/docs/guides/platform/going-into-prod#auth-rate-limits) to ensure that it is not used for spam. Before going into production, you must configure your own email provider. This is as simple as enabling a new SMTP credentials in your [project settings](https://supabase.com/dashboard/project/_/settings/auth).


## Linting your database

The Supabase CLI provides Postgres linting using the `supabase db lint` command:

```markdown
supabase db lint --help
Checks local database for typing error

Usage:
  supabase db lint [flags]

Flags:
  --level [ warning | error ] Error level to emit. (default warning)
  --linked Lints the linked project for schema errors.
  -s, --schema strings List of schema to include. (default all)
```

This is powered by [plpgsql\_check](https://github.com/okbob/plpgsql_check), which leverages the internal Postgres parser/evaluator so you see any errors that would occur at runtime. It provides the following features:

*   validates you are using the correct types for function parameters
*   identifies unused variables and function arguments
*   detection of dead code (any code after an `RETURN` command)
*   detection of missing `RETURN` commands with your Postgres function
*   identifies unwanted hidden casts, which can be a performance issue
*   checks `EXECUTE` statements against SQL injection vulnerability

Check the Reference Docs for [more information](/docs/reference/cli/supabase-db-lint).


# Customizing email templates

Customizing local email templates using config.toml.

You can customize the email templates for local development [using the `config.toml` settings](/docs/guides/cli/config#auth-config).


## Configuring templates

You should provide a relative URL to the `content_path` parameter, pointing to an HTML file which contains the template. For example


## Available email templates

There are several Auth email templates which can be configured:

*   `auth.email.template.invite`
*   `auth.email.template.confirmation`
*   `auth.email.template.recovery`
*   `auth.email.template.magic_link`
*   `auth.email.template.email_change`


## Template variables

The templating system provides the following variables for use:


### `ConfirmationURL`

Contains the confirmation URL. For example, a signup confirmation URL would look like:

    https://project-ref.supabase.co/auth/v1/verify?token={{ .TokenHash }}&type=email&redirect_to=https://example.com/path

**Usage**

```html
<p>Click here to confirm: {{ .ConfirmationURL }}</p>
```


### `Token`

Contains a 6-digit One-Time-Password (OTP) that can be used instead of the `ConfirmationURL`.

**Usage**

```html
<p>Here is your one time password: {{ .Token }}</p>
```


### `TokenHash`

Contains a hashed version of the `Token`. This is useful for constructing your own email link in the email template.

**Usage**

```html
<p>Follow this link to confirm your user:</p>
<p>
  <a href="{{ .SiteURL }}/auth/confirm?token_hash={{ .TokenHash }}&type=email"
    >Confirm your email</a
  >
</p>
```


### `SiteURL`

Contains your application's Site URL. This can be configured in your project's [authentication settings](/dashboard/project/_/auth/url-configuration).

**Usage**

```html
<p>Visit <a href="{{ .SiteURL }}">here</a> to log in.</p>
```


### `Email`

Contains the user's email address.

**Usage**

```html
<p>A recovery request was sent to {{ .Email }}.</p>
```


### `NewEmail`

Contains the new user's email address. This is only available in the `email_change` email template.

**Usage**

```html
<p>You are requesting to update your email address to {{ .NewEmail }}.</p>
```


## Deploying email templates

These settings are for local development. To apply the changes locally, stop and restart the Supabase containers:

```sh
supabase stop && supabase start
```

For hosted projects managed by Supabase, copy the templates into the [Email Templates](/dashboard/project/_/auth/templates) section of the Dashboard.


# Declarative database schemas

Manage your database schemas in one place and generate versioned migrations.

## Overview

Declarative schemas provide a developer-friendly way to maintain .

[Migrations](/docs/guides/deployment/database-migrations) are traditionally managed imperatively (you provide the instructions on how exactly to change the database). This can lead to related information being scattered over multiple migration files. With declarative schemas, you instead declare the state you want your database to be in, and the instructions are generated for you.


## Schema migrations

Schema migrations are SQL statements written in Data Definition Language. They are versioned in your `supabase/migrations` directory to ensure schema consistency between local and remote environments.


### Declaring your schema


### Updating your schema


### Deploying your schema changes


### Managing dependencies

As your database schema evolves, you will probably start using more advanced entities like views and functions. These entities are notoriously verbose to manage using plain migrations because the entire body must be recreated whenever there is a change. Using declarative schema, you can now edit them in-place so it’s much easier to review.

Your schema files are run in lexicographic order by default. The order is important when you have foreign keys between multiple tables as the parent table must be created first. For example, your `supabase` directory may end up with the following structure.

```bash
.
└── supabase/
    ├── schemas/
    │   ├── employees.sql
    │   └── managers.sql
    └── migrations/
        ├── 20241004112233_create_employees_table.sql
        ├── 20241005112233_add_employee_age.sql
        └── 20241006112233_add_managers_table.sql
```

For small projects with only a few tables, the default schema order may be sufficient. However, as your project grows, you might need more control over the order in which schemas are applied. To specify a custom order for applying the schemas, you can declare them explicitly in `config.toml`. Any glob patterns will evaluated, deduplicated, and sorted in lexicographic order. For example, the following pattern ensures `employees.sql` is always executed first.


### Pulling in your production schema

To set up declarative schemas on a existing project, you can pull in your production schema by running:

From there, you can start breaking down your schema into smaller files and generate migrations. You can do this all at once, or incrementally as you make changes to your schema.


### Rolling back a schema change

During development, you may want to rollback a migration to keep your new schema changes in a single migration file. This can be done by resetting your local database to a previous version.

After a reset, you can [edit the schema](#updating-your-schema) and regenerate a new migration file. Note that you should not reset a version that's already deployed to production.

If you need to rollback a migration that's already deployed, you should first revert changes to the schema files. Then you can generate a new migration file containing the down migration. This ensures your production migrations are always rolling forward.


## Known caveats

The `migra` diff tool used for generating schema diff is capable of tracking most database changes. However, there are edge cases where it can fail.

If you need to use any of the entities below, remember to add them through [versioned migrations](/docs/guides/deployment/database-migrations) instead.


### Data manipulation language

*   DML statements such as `insert`, `update`, `delete`, etc., are not captured by schema diff


### View ownership

*   [view owner and grants](https://github.com/djrobstep/migra/issues/160#issuecomment-1702983833)
*   [security invoker on views](https://github.com/djrobstep/migra/issues/234)
*   [materialized views](https://github.com/djrobstep/migra/issues/194)
*   doesn’t recreate views when altering column type


### RLS policies

*   [alter policy statements](https://github.com/djrobstep/schemainspect/blob/master/schemainspect/pg/obj.py#L228)
*   [column privileges](https://github.com/djrobstep/schemainspect/pull/67)


### Other entities

*   schema privileges are not tracked because each schema is diffed separately
*   [comments are not tracked](https://github.com/djrobstep/migra/issues/69)
*   [partitions are not tracked](https://github.com/djrobstep/migra/issues/186)
*   [`alter publication ... add table ...`](https://github.com/supabase/cli/issues/883)
*   [create domain statements are ignored](https://github.com/supabase/cli/issues/2137)
*   [grant statements are duplicated from default privileges](https://github.com/supabase/cli/issues/1864)


# Managing config and secrets



The Supabase CLI uses a `config.toml` file to manage local configuration. This file is located in the `supabase` directory of your project.


## Config reference

The `config.toml` file is automatically created when you run `supabase init`.

There are a wide variety of options available, which can be found in the [CLI Config Reference](/docs/guides/cli/config).

For example, to enable the "Apple" OAuth provider for local development, you can append the following information to `config.toml`:

```toml
[auth.external.apple]
enabled = false
client_id = ""
secret = ""
redirect_uri = "" # Overrides the default auth redirectUrl.
```


## Using secrets inside config.toml

You can reference environment variables within the `config.toml` file using the `env()` function. This will detect any values stored in an `.env` file at the root of your project directory. This is particularly useful for storing sensitive information like API keys, and any other values that you don't want to check into version control.

    .
    ├── .env
    ├── .env.example
    └── supabase
        └── config.toml

For example, if your `.env` contained the following values:

```bash
GITHUB_CLIENT_ID=""
GITHUB_SECRET=""
```

Then you would reference them inside of our `config.toml` like this:

```toml
[auth.external.github]
enabled = true
client_id = "env(GITHUB_CLIENT_ID)"
secret = "env(GITHUB_SECRET)"
redirect_uri = "" # Overrides the default auth redirectUrl.
```


# Local development with schema migrations

Develop locally with the Supabase CLI and schema migrations.

Supabase is a flexible platform that lets you decide how you want to build your projects. You can use the Dashboard directly to get up and running quickly, or use a proper local setup. We suggest you work locally and deploy your changes to a linked project on the [Supabase Platform](https://app.supabase.io/).

Develop locally using the CLI to run a local Supabase stack. You can use the integrated Studio Dashboard to make changes, then capture your changes in schema migration files, which can be saved in version control.

Alternatively, if you're comfortable with migration files and SQL, you can write your own migrations and push them to the local database for testing before sharing your changes.


## Database migrations

Database changes are managed through "migrations." Database migrations are a common way of tracking changes to your database over time.

For this guide, we'll create a table called `employees` and see how we can make changes to it.


### Add sample data

Now that you are managing your database with migrations scripts, it would be great have some seed data to use every time you reset the database.

For this, you can create a seed script in `supabase/seed.sql`.

You should now see the `employees` table, along with your seed data in the Dashboard! All of your database changes are captured in code, and you can reset to a known state at any time, complete with seed data.


### Diffing changes

This workflow is great if you know SQL and are comfortable creating tables and columns. If not, you can still use the Dashboard to create tables and columns, and then use the CLI to diff your changes and create migrations.

Create a new table called `cities`, with columns `id`, `name` and `population`. To see the corresponding SQL for this, you can use the `supabase db diff --schema public` command. This will show you the SQL that will be run to create the table and columns. The output of `supabase db diff` will look something like this:

```
Diffing schemas: public
Finished supabase db diff on branch main.

create table "public"."cities" (
    "id" bigint primary key generated always as identity,
    "name" text,
    "population" bigint
);

```

Alternately, you can view your table definitions directly from the Table Editor:

![SQL Definition](/docs/img/guides/cli/sql-definitions.png)

You can then copy this SQL into a new migration file, and run `supabase db reset` to apply the changes.

The last step is deploying these changes to a live Supabase project.


## Deploy your project

You've been developing your project locally, making changes to your tables via migrations. It's time to deploy your project to the Supabase Platform and start scaling up to millions of users! Head over to [Supabase](https://supabase.com/dashboard) and create a new project to deploy to.


### Log in to the Supabase CLI


### Link your project

Associate your project with your remote project using [`supabase link`](/docs/reference/cli/usage#supabase-link).

```bash
supabase link --project-ref <project-id>
# You can get <project-id> from your project's dashboard URL: https://supabase.com/dashboard/project/<project-id>

supabase db pull
# Capture any changes that you have made to your remote database before you went through the steps above
# If you have not made any changes to the remote database, skip this step
```

`supabase/migrations` is now populated with a migration in `<timestamp>_remote_schema.sql`.
This migration captures any changes required for your local database to match the schema of your remote Supabase project.

Review the generated migration file and once happy, apply the changes to your local instance:

```bash
# To apply the new migration to your local database:
supabase migration up

# To reset your local database completely:
supabase db reset
```


### Deploy database changes

Deploy any local database migrations using [`db push`](/docs/reference/cli/usage#supabase-db-push):

```sh
supabase db push
```

Visiting your live project on [Supabase](https://supabase.com/dashboard), you'll see a new `employees` table, complete with the `department` column you added in the second migration above.


### Deploy Edge Functions

If your project uses Edge Functions, you can deploy these using [`functions deploy`](/docs/reference/cli/usage#supabase-functions-deploy):

```sh
supabase functions deploy <function_name>
```


### Use Auth locally

To use Auth locally, update your project's `supabase/config.toml` file that gets created after running `supabase init`. Add any providers you want, and set enabled to `true`.

```bash supabase/config.toml
[auth.external.github]
enabled = true
client_id = "env(SUPABASE_AUTH_GITHUB_CLIENT_ID)"
secret = "env(SUPABASE_AUTH_GITHUB_SECRET)"
redirect_uri = "http://localhost:54321/auth/v1/callback"
```

As a best practice, any secret values should be loaded from environment variables. You can add them to `.env` file in your project's root directory for the CLI to automatically substitute them.

```bash .env
SUPABASE_AUTH_GITHUB_CLIENT_ID="redacted"
SUPABASE_AUTH_GITHUB_SECRET="redacted"
```

For these changes to take effect, you need to run `supabase stop` and `supabase start` again.

If you have additional triggers or RLS policies defined on your `auth` schema, you can pull them as a migration file locally.

```bash
supabase db pull --schema auth
```


### Sync storage buckets

Your RLS policies on storage buckets can be pulled locally by specifying `storage` schema. For example,

```bash
supabase db pull --schema storage
```

The buckets and objects themselves are rows in the storage tables so they won't appear in your schema. You can instead define them via `supabase/config.toml` file. For example,

```bash supabase/config.toml
[storage.buckets.images]
public = false
file_size_limit = "50MiB"
allowed_mime_types = ["image/png", "image/jpeg"]
objects_path = "./images"
```

This will upload files from `supabase/images` directory to a bucket named `images` in your project with one command.

```bash
supabase seed buckets
```


### Sync any schema with `--schema`

You can synchronize your database with a specific schema using the `--schema` option as follows:

```bash
supabase db pull --schema <schema_name>
```


## Limitations and considerations

The local development environment is not as feature-complete as the Supabase Platform. Here are some of the differences:

*   You cannot update your project settings in the Dashboard. This must be done using the local config file.
*   The CLI version determines the local version of Studio used, so make sure you keep your local [Supabase CLI up to date](https://github.com/supabase/cli#getting-started). We're constantly adding new features and bug fixes.


# Restoring a downloaded backup locally

Restore a backup of a remote database on a local instance to inspect and extract data

You can restore a downloaded backup to a local Supabase instance. This might be useful if your paused project has exceeded its [restoring time limit](/docs/guides/platform/upgrading#time-limits). You can download the latest backup, then load it locally to inspect and extract your data.


## Downloading your backup

First, download your project's backup file from dashboard and identify its backup image version (following the `PG:` prefix):


## Restoring your backup

Given Postgres version `15.6.1.115`, start Postgres locally with `db_cluster.backup` being the path to your backup file.

```sh
supabase init
echo '15.6.1.115' > supabase/.temp/postgres-version
supabase db start --from-backup db_cluster.backup
```

Note that the earliest Supabase Postgres version that supports a local restore is `15.1.0.55`. If your hosted project was running on earlier versions, you will likely run into errors during restore. Before submitting any support ticket, make sure you have attached the error logs from `supabase_db_*` docker container.

Once your local database starts up successfully, you can connect using psql to verify that all your data is restored.

```sh
psql 'postgresql://postgres:postgres@localhost:54322/postgres'
```

If you want to use other services like Auth, Storage, and Studio dashboard together with your restored database, restart the local development stack.

```sh
supabase stop
supabase start
```

A Postgres database started with Supabase CLI is not production ready and should not be used outside of local development.


# Seeding your database

Populate your database with initial data for reproducible environments across local and testing.

## What is seed data?

Seeding is the process of populating a database with initial data, typically used to provide sample or default records for testing and development purposes. You can use this to create "reproducible environments" for local development, staging, and production.


## Using seed files

Seed files are executed every time you run `supabase start` or `supabase db reset`. Seeding occurs *after* all database migrations have been completed. As a best practice, only include data insertions in your seed files, and avoid adding schema statements.

By default, if no specific configuration is provided, the system will look for a seed file matching the pattern `supabase/seed.sql`. This maintains backward compatibility with earlier versions, where the seed file was placed in the `supabase` folder.

You can add any SQL statements to this file. For example:

```sql
insert into countries
  (name, code)
values
  ('United States', 'US'),
  ('Canada', 'CA'),
  ('Mexico', 'MX');
```

If you want to manage multiple seed files or organize them across different folders, you can configure additional paths or glob patterns in your `config.toml` (see the [next section](#splitting-up-your-seed-data) for details).


### Splitting up your seed file

For better modularity and maintainability, you can split your seed data into multiple files. For example, you can organize your seeds by table and include files such as `countries.sql` and `cities.sql`. Configure them in `config.toml` like so:

```toml supabase/config.toml
[db.seed]
enabled = true
sql_paths = ['./countries.sql', './cities.sql']
```

Or to include all `.sql` files under a specific folder you can do:

```toml supabase/config.toml
[db.seed]
enabled = true
sql_paths = ['./seeds/*.sql']
```


## Generating seed data

You can generate seed data for local development using [Snaplet](https://github.com/snaplet/seed).

If this is your first time using Snaplet to seed your project, you'll need to set up Snaplet with the following command:

```bash
npx @snaplet/seed init
```

This command will analyze your database and its structure, and then generate a JavaScript client which can be used to define exactly how your data should be generated using code. The `init` command generates a configuration file, `seed.config.ts` and an example script, `seed.ts`, as a starting point.

In most cases you only want to generate data for specific schemas or tables. This is defined with `select`. Here is an example `seed.config.ts` configuration file:

```ts
export default defineConfig({
  adapter: async () => {
    const client = new Client({
      connectionString: 'postgresql://postgres:postgres@localhost:54322/postgres',
    })
    await client.connect()
    return new SeedPg(client)
  },
  // We only want to generate data for the public schema
  select: ['!*', 'public.*'],
})
```

Suppose you have a database with the following schema:

![An example schema](/docs/img/guides/cli/snaplet-example-schema.png)

You can use the seed script example generated by Snaplet `seed.ts` to define the values you want to generate. For example:

*   A `Post` with the title `"There is a lot of snow around here!"`
*   The `Post.createdBy` user with an email address ending in `"@acme.org"`
*   Three `Post.comments` from three different users.

```ts seed.ts
import { createSeedClient } from '@snaplet/seed'
import { copycat } from '@snaplet/copycat'

async function main() {
  const seed = await createSeedClient({ dryRun: true })

  await seed.Post([
    {
      title: 'There is a lot of snow around here!',
      createdBy: {
        email: (ctx) =>
          copycat.email(ctx.seed, {
            domain: 'acme.org',
          }),
      },
      Comment: (x) => x(3),
    },
  ])

  process.exit()
}

main()
```

Running `npx tsx seed.ts > supabase/seed.sql` generates the relevant SQL statements inside your `supabase/seed.sql` file:

```sql
-- The `Post.createdBy` user with an email address ending in `"@acme.org"`
INSERT INTO "User" (name, email) VALUES ("John Snow", "snow@acme.org")

--- A `Post` with the title `"There is a lot of snow around here!"`
INSERT INTO "Post" (title, content, createdBy) VALUES (
  "There is a lot of snow around here!",
  "Lorem ipsum dolar",
  1)

--- Three `Post.Comment` from three different users.
INSERT INTO "User" (name, email) VALUES ("Stephanie Shadow", "shadow@domain.com")
INSERT INTO "Comment" (text, userId, postId) VALUES ("I love cheese", 2, 1)

INSERT INTO "User" (name, email) VALUES ("John Rambo", "rambo@trymore.dev")
INSERT INTO "Comment" (text, userId, postId) VALUES ("Lorem ipsum dolar sit", 3, 1)

INSERT INTO "User" (name, email) VALUES ("Steven Plank", "s@plank.org")
INSERT INTO "Comment" (text, userId, postId) VALUES ("Actually, that's not correct...", 4, 1)
```

Whenever your database structure changes, you will need to regenerate `@snaplet/seed` to keep it in sync with the new structure. You can do this by running:

```bash
npx @snaplet/seed sync
```

You can further enhance your seed script by using Large Language Models to generate more realistic data. To enable this feature, set one of the following environment variables in your `.env` file:

```plaintext
OPENAI_API_KEY=<your_openai_api_key>
GROQ_API_KEY=<your_groq_api_key>
```

After setting the environment variables, run the following commands to sync and generate the seed data:

```bash
npx @snaplet/seed sync
npx tsx seed.ts > supabase/seed.sql
```

For more information, check out Snaplet's [seed documentation](https://snaplet-seed.netlify.app/seed/integrations/supabase)


# Testing Overview



Testing is a critical part of database development, especially when working with features like Row Level Security (RLS) policies. This guide provides a comprehensive approach to testing your Supabase database.


## Testing approaches


### Database unit testing with pgTAP

[pgTAP](https://pgtap.org) is a unit testing framework for Postgres that allows testing:

*   Database structure: tables, columns, constraints
*   Row Level Security (RLS) policies
*   Functions and procedures
*   Data integrity

This example demonstrates setting up and testing RLS policies for a simple todo application:

1.  Create a test table with RLS enabled:

    ```sql
    -- Create a simple todos table
    create table todos (
    id uuid primary key default gen_random_uuid(),
    task text not null,
    user_id uuid references auth.users not null,
    completed boolean default false
    );

    -- Enable RLS
    alter table todos enable row level security;

    -- Create a policy
    create policy "Users can only access their own todos"
    on todos for all -- this policy applies to all operations
    to authenticated
    using ((select auth.uid()) = user_id);
    ```

2.  Set up your testing environment:

    ```bash
    # Create a new test for our policies using supabase cli
    supabase test new todos_rls.test
    ```

3.  Write your RLS tests:

    ```sql
    begin;
    -- install tests utilities
    -- install pgtap extension for testing
    create extension if not exists pgtap with schema extensions;
    -- Start declare we'll have 4 test cases in our test suite
    select plan(4);

    -- Setup our testing data
    -- Set up auth.users entries
    insert into auth.users (id, email) values
    	('123e4567-e89b-12d3-a456-426614174000', 'user1@test.com'),
    	('987fcdeb-51a2-43d7-9012-345678901234', 'user2@test.com');

    -- Create test todos
    insert into public.todos (task, user_id) values
    	('User 1 Task 1', '123e4567-e89b-12d3-a456-426614174000'),
    	('User 1 Task 2', '123e4567-e89b-12d3-a456-426614174000'),
    	('User 2 Task 1', '987fcdeb-51a2-43d7-9012-345678901234');

    -- as User 1
    set local role authenticated;
    set local request.jwt.claim.sub = '123e4567-e89b-12d3-a456-426614174000';

    -- Test 1: User 1 should only see their own todos
    select results_eq(
    	'select count(*) from todos',
    	ARRAY[2::bigint],
    	'User 1 should only see their 2 todos'
    );

    -- Test 2: User 1 can create their own todo
    select lives_ok(
    	$$insert into todos (task, user_id) values ('New Task', '123e4567-e89b-12d3-a456-426614174000'::uuid)$$,
    	'User 1 can create their own todo'
    );

    -- as User 2
    set local request.jwt.claim.sub = '987fcdeb-51a2-43d7-9012-345678901234';

    -- Test 3: User 2 should only see their own todos
    select results_eq(
    	'select count(*) from todos',
    	ARRAY[1::bigint],
    	'User 2 should only see their 1 todo'
    );

    -- Test 4: User 2 cannot modify User 1's todo
    SELECT results_ne(
    	$$ update todos set task = 'Hacked!' where user_id = '123e4567-e89b-12d3-a456-426614174000'::uuid returning 1 $$,
    	$$ values(1) $$,
    	'User 2 cannot modify User 1 todos'
    );

    select * from finish();
    rollback;
    ```

4.  Run the tests:

    ```bash
    supabase test db
    psql:todos_rls.test.sql:4: NOTICE:  extension "pgtap" already exists, skipping
    ./todos_rls.test.sql .. ok
    All tests successful.
    Files=1, Tests=6,  0 wallclock secs ( 0.01 usr +  0.00 sys =  0.01 CPU)
    Result: PASS
    ```


### Application-Level testing

Testing through application code provides end-to-end verification. Unlike database-level testing with pgTAP, application-level tests cannot use transactions for isolation.

Here's an example using TypeScript that mirrors the pgTAP tests above:

```typescript
import { createClient } from '@supabase/supabase-js'
import { beforeAll, describe, expect, it } from 'vitest'
import crypto from 'crypto'

describe('Todos RLS', () => {
  // Generate unique IDs for this test suite to avoid conflicts with other tests
  const USER_1_ID = crypto.randomUUID()
  const USER_2_ID = crypto.randomUUID()

  const supabase = createClient(process.env.SUPABASE_URL!, process.env.SUPABASE_ANON_KEY!)

  beforeAll(async () => {
    // Setup test data specific to this test suite
    const adminSupabase = createClient(process.env.SUPABASE_URL!, process.env.SERVICE_ROLE_KEY!)

    // Create test users with unique IDs
    await adminSupabase.auth.admin.createUser({
      id: USER_1_ID,
      email: `user1-${USER_1_ID}@test.com`,
      password: 'password123',
      // We want the user to be usable right away without email confirmation
      email_confirm: true,
    })
    await adminSupabase.auth.admin.createUser({
      id: USER_2_ID,
      email: `user2-${USER_2_ID}@test.com`,
      password: 'password123',
      email_confirm: true,
    })

    // Create initial todos
    await adminSupabase.from('todos').insert([
      { task: 'User 1 Task 1', user_id: USER_1_ID },
      { task: 'User 1 Task 2', user_id: USER_1_ID },
      { task: 'User 2 Task 1', user_id: USER_2_ID },
    ])
  })

  it('should allow User 1 to only see their own todos', async () => {
    // Sign in as User 1
    await supabase.auth.signInWithPassword({
      email: `user1-${USER_1_ID}@test.com`,
      password: 'password123',
    })

    const { data: todos } = await supabase.from('todos').select('*')

    expect(todos).toHaveLength(2)
    todos?.forEach((todo) => {
      expect(todo.user_id).toBe(USER_1_ID)
    })
  })

  it('should allow User 1 to create their own todo', async () => {
    await supabase.auth.signInWithPassword({
      email: `user1-${USER_1_ID}@test.com`,
      password: 'password123',
    })

    const { error } = await supabase.from('todos').insert({ task: 'New Task', user_id: USER_1_ID })

    expect(error).toBeNull()
  })

  it('should allow User 2 to only see their own todos', async () => {
    // Sign in as User 2
    await supabase.auth.signInWithPassword({
      email: `user2-${USER_2_ID}@test.com`,
      password: 'password123',
    })

    const { data: todos } = await supabase.from('todos').select('*')
    expect(todos).toHaveLength(1)
    todos?.forEach((todo) => {
      expect(todo.user_id).toBe(USER_2_ID)
    })
  })

  it('should prevent User 2 from modifying User 1 todos', async () => {
    await supabase.auth.signInWithPassword({
      email: `user2-${USER_2_ID}@test.com`,
      password: 'password123',
    })

    // Attempt to update the todos we shouldn't have access to
    // result will be a no-op
    await supabase.from('todos').update({ task: 'Hacked!' }).eq('user_id', USER_1_ID)

    // Log back in as User 1 to verify their todos weren't changed
    await supabase.auth.signInWithPassword({
      email: `user1-${USER_1_ID}@test.com`,
      password: 'password123',
    })

    // Fetch User 1's todos
    const { data: todos } = await supabase.from('todos').select('*')

    // Verify that none of the todos were changed to "Hacked!"
    expect(todos).toBeDefined()
    todos?.forEach((todo) => {
      expect(todo.task).not.toBe('Hacked!')
    })
  })
})
```


#### Test isolation strategies

For application-level testing, consider these approaches for test isolation:

1.  **Unique Identifiers**: Generate unique IDs for each test suite to prevent data conflicts
2.  **Cleanup After Tests**: If necessary, clean up created data in an `afterAll` or `afterEach` hook
3.  **Isolated Data Sets**: Use prefixes or namespaces in data to separate test cases


### Continuous integration testing

Set up automated database testing in your CI pipeline:

1.  Create a GitHub Actions workflow `.github/workflows/db-tests.yml`:

```yaml
name: Database Tests

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Setup Supabase CLI
        uses: supabase/setup-cli@v1

      - name: Start Supabase
        run: supabase start

      - name: Run Tests
        run: supabase test db
```


## Best practices

1.  **Test Data Setup**

    *   Use begin and rollback to ensure test isolation
    *   Create realistic test data that covers edge cases
    *   Use different user roles and permissions in tests

2.  **RLS Policy Testing**

    *   Test Create, Read, Update, Delete operations
    *   Test with different user roles: anonymous and authenticated
    *   Test edge cases and potential security bypasses
    *   Always test negative cases: what users should not be able to do

3.  **CI/CD Integration**
    *   Run tests automatically on every pull request
    *   Include database tests in deployment pipeline
    *   Keep test runs fast using transactions


## Real-World examples

For more complex, real-world examples of database testing, check out:

*   [Database Tests Example Repository](https://github.com/usebasejump/basejump/tree/main/supabase/tests/database) - A production-grade example of testing RLS policies
*   [RLS Guide and Best Practices](https://github.com/orgs/supabase/discussions/14576)


## Troubleshooting

Common issues and solutions:

1.  **Test Failures Due to RLS**

    *   Ensure you've set the correct role `set local role authenticated;`
    *   Verify JWT claims are set `set local "request.jwt.claims"`
    *   Check policy definitions match your test assumptions

2.  **CI Pipeline Issues**
    *   Verify Supabase CLI is properly installed
    *   Ensure database migrations are run before tests
    *   Check for proper test isolation using transactions


## Additional resources

*   [pgTAP Documentation](https://pgtap.org)
*   [Supabase CLI Reference](https://supabase.com/docs/reference/cli/supabase-test)
*   [pgTAP Supabase reference](https://supabase.com/docs/guides/database/extensions/pgtap?queryGroups=database-method\&database-method=sql#testing-rls-policies)
*   [Database testing reference](https://supabase.com/docs/guides/database/testing)


# Advanced pgTAP Testing



While basic pgTAP provides excellent testing capabilities, you can enhance the testing workflow using database development tools and helper packages. This guide covers advanced testing techniques using database.dev and community-maintained test helpers.


## Using database.dev

[Database.dev](https://database.dev) is a package manager for Postgres that allows installation and use of community-maintained packages, including testing utilities.


### Setting up dbdev

To use database development tools and packages, install some prerequisites:

```sql
create extension if not exists http with schema extensions;
create extension if not exists pg_tle;
drop extension if exists "supabase-dbdev";
select pgtle.uninstall_extension_if_exists('supabase-dbdev');
select
    pgtle.install_extension(
        'supabase-dbdev',
        resp.contents ->> 'version',
        'PostgreSQL package manager',
        resp.contents ->> 'sql'
    )
from http(
    (
        'GET',
        'https://api.database.dev/rest/v1/'
        || 'package_versions?select=sql,version'
        || '&package_name=eq.supabase-dbdev'
        || '&order=version.desc'
        || '&limit=1',
        array[
            ('apiKey', 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6InhtdXB0cHBsZnZpaWZyYndtbXR2Iiwicm9sZSI6ImFub24iLCJpYXQiOjE2ODAxMDczNzIsImV4cCI6MTk5NTY4MzM3Mn0.z2CN0mvO2No8wSi46Gw59DFGCTJrzM0AQKsu_5k134s')::http_header
        ],
        null,
        null
    )
) x,
lateral (
    select
        ((row_to_json(x) -> 'content') #>> '{}')::json -> 0
) resp(contents);
create extension "supabase-dbdev";
select dbdev.install('supabase-dbdev');

-- Drop and recreate the extension to ensure a clean installation
drop extension if exists "supabase-dbdev";
create extension "supabase-dbdev";
```


### Installing test helpers

The Test Helpers package provides utilities that simplify testing Supabase-specific features:

```sql
select dbdev.install('basejump-supabase_test_helpers');
create extension if not exists "basejump-supabase_test_helpers" version '0.0.6';
```


## Test helper benefits

The test helpers package provides several advantages over writing raw pgTAP tests:

1.  **Simplified User Management**

    *   Create test users with `tests.create_supabase_user()`
    *   Switch contexts with `tests.authenticate_as()`
    *   Retrieve user IDs using `tests.get_supabase_uid()`

2.  **Row Level Security (RLS) Testing Utilities**

    *   Verify RLS status with `tests.rls_enabled()`
    *   Test policy enforcement
    *   Simulate different user contexts

3.  **Reduced Boilerplate**
    *   No need to manually insert auth.users
    *   Simplified JWT claim management
    *   Clean test setup and cleanup


## Schema-wide Row Level Security testing

When working with Row Level Security, it's crucial to ensure that RLS is enabled on all tables that need it. Create a simple test to verify RLS is enabled across an entire schema:

```sql
begin;
select plan(1);

-- Verify RLS is enabled on all tables in the public schema
select tests.rls_enabled('public');

select * from finish();
rollback;
```


## Test file organization

When working with multiple test files that share common setup requirements, it's beneficial to create a single "pre-test" file that handles the global environment setup. This approach reduces duplication and ensures consistent test environments.


### Creating a pre-test hook

Since pgTAP test files are executed in alphabetical order, create a setup file that runs first by using a naming convention like `000-setup-tests-hooks.sql`:

```bash
supabase test new 000-setup-tests-hooks
```

This setup file should contain:

1.  All shared extensions and dependencies
2.  Common test utilities
3.  A simple always green test to verify the setup

Here's an example setup file:

```sql
-- install tests utilities
-- install pgtap extension for testing
create extension if not exists pgtap with schema extensions;
/*
---------------------
---- install dbdev ----
----------------------
Requires:
  - pg_tle: https://github.com/aws/pg_tle
  - pgsql-http: https://github.com/pramsey/pgsql-http
*/
create extension if not exists http with schema extensions;
create extension if not exists pg_tle;
drop extension if exists "supabase-dbdev";
select pgtle.uninstall_extension_if_exists('supabase-dbdev');
select
    pgtle.install_extension(
        'supabase-dbdev',
        resp.contents ->> 'version',
        'PostgreSQL package manager',
        resp.contents ->> 'sql'
    )
from http(
    (
        'GET',
        'https://api.database.dev/rest/v1/'
        || 'package_versions?select=sql,version'
        || '&package_name=eq.supabase-dbdev'
        || '&order=version.desc'
        || '&limit=1',
        array[
            ('apiKey', 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6InhtdXB0cHBsZnZpaWZyYndtbXR2Iiwicm9sZSI6ImFub24iLCJpYXQiOjE2ODAxMDczNzIsImV4cCI6MTk5NTY4MzM3Mn0.z2CN0mvO2No8wSi46Gw59DFGCTJrzM0AQKsu_5k134s')::http_header
        ],
        null,
        null
    )
) x,
lateral (
    select
        ((row_to_json(x) -> 'content') #>> '{}')::json -> 0
) resp(contents);
create extension "supabase-dbdev";
select dbdev.install('supabase-dbdev');
drop extension if exists "supabase-dbdev";
create extension "supabase-dbdev";
-- Install test helpers
select dbdev.install('basejump-supabase_test_helpers');
create extension if not exists "basejump-supabase_test_helpers" version '0.0.6';

-- Verify setup with a no-op test
begin;
select plan(1);
select ok(true, 'Pre-test hook completed successfully');
select * from finish();
rollback;
```


### Benefits

This approach provides several advantages:

*   Reduces code duplication across test files
*   Ensures consistent test environment setup
*   Makes it easier to maintain and update shared dependencies
*   Provides immediate feedback if the setup process fails

Your subsequent test files (`001-auth-tests.sql`, `002-rls-tests.sql`) can focus solely on their specific test cases, knowing that the environment is properly configured.


## Example: Advanced RLS testing

Here's a complete example using test helpers to verify RLS policies putting it all together:

```sql
begin;
-- Assuming 000-setup-tests-hooks.sql file is present to use tests helpers
select plan(4);

-- Set up test data

-- Create test supabase users
select tests.create_supabase_user('user1@test.com');
select tests.create_supabase_user('user2@test.com');

-- Create test data
insert into public.todos (task, user_id) values
  ('User 1 Task 1', tests.get_supabase_uid('user1@test.com')),
  ('User 1 Task 2', tests.get_supabase_uid('user1@test.com')),
  ('User 2 Task 1', tests.get_supabase_uid('user2@test.com'));

-- Test as User 1
select tests.authenticate_as('user1@test.com');

-- Test 1: User 1 should only see their own todos
select results_eq(
  'select count(*) from todos',
  ARRAY[2::bigint],
  'User 1 should only see their 2 todos'
);

-- Test 2: User 1 can create their own todo
select lives_ok(
  $$insert into todos (task, user_id) values ('New Task', tests.get_supabase_uid('user1@test.com'))$$,
  'User 1 can create their own todo'
);

-- Test as User 2
select tests.authenticate_as('user2@test.com');

-- Test 3: User 2 should only see their own todos
select results_eq(
  'select count(*) from todos',
  ARRAY[1::bigint],
  'User 2 should only see their 1 todo'
);

-- Test 4: User 2 cannot modify User 1's todo
SELECT results_ne(
    $$ update todos set task = 'Hacked!' where user_id = tests.get_supabase_uid('user1@test.com') returning 1 $$,
    $$ values(1) $$,
    'User 2 cannot modify User 1 todos'
);

select * from finish();
rollback;
```


## Not another todo app: Testing complex organizations

Todo apps are great for learning, but this section explores testing a more realistic scenario: a multi-tenant content publishing platform. This example demonstrates testing complex permissions, plan restrictions, and content management.


### System overview

This demo app implements:

*   Organizations with tiered plans (free/pro/enterprise)
*   Role-based access (owner/admin/editor/viewer)
*   Content management (posts/comments)
*   Premium content restrictions
*   Plan-based limitations


### What makes this complex?

1.  **Layered Permissions**

    *   Role hierarchies affect access rights
    *   Plan types influence user capabilities
    *   Content state (draft/published) affects permissions

2.  **Business Rules**
    *   Free plan post limits
    *   Premium content visibility
    *   Cross-organization security


### Testing focus areas

When writing tests, verify:

*   Organization member access control
*   Content visibility across roles
*   Plan limitation enforcement
*   Cross-organization data isolation


#### 1. App schema definitions

The app schema tables are defined like this:

```sql
create table public.profiles (
  id uuid references auth.users(id) primary key,
  username text unique not null,
  full_name text,
  bio text,
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

create table public.organizations (
  id bigint primary key generated always as identity,
  name text not null,
  slug text unique not null,
  plan_type text not null check (plan_type in ('free', 'pro', 'enterprise')),
  max_posts int not null default 5,
  created_at timestamptz default now()
);

create table public.org_members (
  org_id bigint references public.organizations(id) on delete cascade,
  user_id uuid references auth.users(id) on delete cascade,
  role text not null check (role in ('owner', 'admin', 'editor', 'viewer')),
  created_at timestamptz default now(),
  primary key (org_id, user_id)
);

create table public.posts (
  id bigint primary key generated always as identity,
  title text not null,
  content text not null,
  author_id uuid references public.profiles(id) not null,
  org_id bigint references public.organizations(id),
  status text not null check (status in ('draft', 'published', 'archived')),
  is_premium boolean default false,
  scheduled_for timestamptz,
  category text,
  view_count int default 0,
  published_at timestamptz,
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

create table public.comments (
  id bigint primary key generated always as identity,
  post_id bigint references public.posts(id) on delete cascade,
  author_id uuid references public.profiles(id),
  content text not null,
  is_deleted boolean default false,
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);
```


#### 2. RLS policies declaration

Now to setup the RLS policies for each tables:

```sql
-- Create a private schema to store all security definer functions utils
-- As such functions should never be in a API exposed schema
create schema if not exists private;
-- Helper function for role checks
create or replace function private.get_user_org_role(org_id bigint, user_id uuid)
returns text
set search_path = ''
as $$
  select role from public.org_members
  where org_id = $1 and user_id = $2;
-- Note the use of security definer to avoid RLS checking recursion issue
-- see: https://supabase.com/docs/guides/database/postgres/row-level-security#use-security-definer-functions
$$ language sql security definer;
-- Helper utils to check if an org is below the max post limit
create or replace function private.can_add_post(org_id bigint)
returns boolean
set search_path = ''
as $$
  select (select count(*)
          from public.posts p
          where p.org_id = $1) < o.max_posts
  from public.organizations o
  where o.id = $1
$$ language sql security definer;


-- Enable RLS for all tables
alter table public.profiles enable row level security;
alter table public.organizations enable row level security;
alter table public.org_members enable row level security;
alter table public.posts enable row level security;
alter table public.comments enable row level security;

-- Profiles policies
create policy "Public profiles are viewable by everyone"
  on public.profiles for select using (true);

create policy "Users can insert their own profile"
  on public.profiles for insert with check ((select auth.uid()) = id);

create policy "Users can update their own profile"
  on public.profiles for update using ((select auth.uid()) = id)
  with check ((select auth.uid()) = id);

-- Organizations policies
create policy "Public org info visible to all"
  on public.organizations for select using (true);

create policy "Org management restricted to owners"
  on public.organizations for all using (
    private.get_user_org_role(id, (select auth.uid())) = 'owner'
  );

-- Org Members policies
create policy "Members visible to org members"
  on public.org_members for select using (
    private.get_user_org_role(org_id, (select auth.uid())) is not null
  );

create policy "Member management restricted to admins and owners"
  on public.org_members for all using (
    private.get_user_org_role(org_id, (select auth.uid())) in ('owner', 'admin')
  );

-- Posts policies
create policy "Complex post visibility"
  on public.posts for select using (
    -- Published non-premium posts are visible to all
    (status = 'published' and not is_premium)
    or
    -- Premium posts visible to org members only
    (status = 'published' and is_premium and
    private.get_user_org_role(org_id, (select auth.uid())) is not null)
    or
    -- All posts visible to editors and above
    private.get_user_org_role(org_id, (select auth.uid())) in ('owner', 'admin', 'editor')
  );

create policy "Post creation rules"
  on public.posts for insert with check (
    -- Must be org member with appropriate role
    private.get_user_org_role(org_id, (select auth.uid())) in ('owner', 'admin', 'editor')
    and
    -- Check org post limits for free plans
    (
      (select o.plan_type != 'free'
      from organizations o
      where o.id = org_id)
      or
      (select private.can_add_post(org_id))
    )
  );

create policy "Post update rules"
  on public.posts for update using (
    exists (
      select 1
      where
        -- Editors can update non-published posts
        (private.get_user_org_role(org_id, (select auth.uid())) = 'editor' and status != 'published')
        or
        -- Admins and owners can update any post
        private.get_user_org_role(org_id, (select auth.uid())) in ('owner', 'admin')
    )
  );

-- Comments policies
create policy "Comments on published posts are viewable by everyone"
  on public.comments for select using (
    exists (
      select 1 from public.posts
      where id = post_id
      and status = 'published'
    )
    and not is_deleted
  );

create policy "Authenticated users can create comments"
  on public.comments for insert with check ((select auth.uid()) = author_id);

create policy "Users can update their own comments"
  on public.comments for update using (author_id = (select auth.uid()));
```


#### 3. Test cases:

Now everything is setup, let's write RLS test cases, note that each section could be in its own test:

```sql
-- Assuming we already have: 000-setup-tests-hooks.sql file we can use tests helpers
begin;
-- Declare total number of tests
select plan(10);

-- Create test users
select tests.create_supabase_user('org_owner', 'owner@test.com');
select tests.create_supabase_user('org_admin', 'admin@test.com');
select tests.create_supabase_user('org_editor', 'editor@test.com');
select tests.create_supabase_user('premium_user', 'premium@test.com');
select tests.create_supabase_user('free_user', 'free@test.com');
select tests.create_supabase_user('scheduler', 'scheduler@test.com');
select tests.create_supabase_user('free_author', 'free_author@test.com');

-- Create profiles for test users
insert into profiles (id, username, full_name)
values
  (tests.get_supabase_uid('org_owner'), 'org_owner', 'Organization Owner'),
  (tests.get_supabase_uid('org_admin'), 'org_admin', 'Organization Admin'),
  (tests.get_supabase_uid('org_editor'), 'org_editor', 'Organization Editor'),
  (tests.get_supabase_uid('premium_user'), 'premium_user', 'Premium User'),
  (tests.get_supabase_uid('free_user'), 'free_user', 'Free User'),
  (tests.get_supabase_uid('scheduler'), 'scheduler', 'Scheduler User'),
  (tests.get_supabase_uid('free_author'), 'free_author', 'Free Author');

-- First authenticate as service role to bypass RLS for initial setup
select tests.authenticate_as_service_role();

-- Create test organizations and setup data
with new_org as (
  insert into organizations (name, slug, plan_type, max_posts)
  values
    ('Test Org', 'test-org', 'pro', 100),
    ('Premium Org', 'premium-org', 'enterprise', 1000),
    ('Schedule Org', 'schedule-org', 'pro', 100),
    ('Free Org', 'free-org', 'free', 2)
  returning id, slug
),
-- Setup members and posts
member_setup as (
  insert into org_members (org_id, user_id, role)
  select
    org.id,
    user_id,
    role
  from new_org org cross join (
    values
      (tests.get_supabase_uid('org_owner'), 'owner'),
      (tests.get_supabase_uid('org_admin'), 'admin'),
      (tests.get_supabase_uid('org_editor'), 'editor'),
      (tests.get_supabase_uid('premium_user'), 'viewer'),
      (tests.get_supabase_uid('scheduler'), 'editor'),
      (tests.get_supabase_uid('free_author'), 'editor')
  ) as members(user_id, role)
  where org.slug = 'test-org'
     or (org.slug = 'premium-org' and role = 'viewer')
     or (org.slug = 'schedule-org' and role = 'editor')
     or (org.slug = 'free-org' and role = 'editor')
)
-- Setup initial posts
insert into posts (title, content, org_id, author_id, status, is_premium, scheduled_for)
select
  title,
  content,
  org.id,
  author_id,
  status,
  is_premium,
  scheduled_for
from new_org org cross join (
  values
    ('Premium Post', 'Premium content', tests.get_supabase_uid('premium_user'), 'published', true, null),
    ('Free Post', 'Free content', tests.get_supabase_uid('premium_user'), 'published', false, null),
    ('Future Post', 'Future content', tests.get_supabase_uid('scheduler'), 'published', false, '2024-01-02 12:00:00+00'::timestamptz)
) as posts(title, content, author_id, status, is_premium, scheduled_for)
where org.slug in ('premium-org', 'schedule-org');

-- Test owner privileges
select tests.authenticate_as('org_owner');
select lives_ok(
  $$
    update organizations
    set name = 'Updated Org'
    where id = (select id from organizations limit 1)
  $$,
  'Owner can update organization'
);

-- Test admin privileges
select tests.authenticate_as('org_admin');
select results_eq(
    $$select count(*) from org_members$$,
    ARRAY[6::bigint],
    'Admin can view all members'
);

-- Test editor restrictions
select tests.authenticate_as('org_editor');
select throws_ok(
  $$
    insert into org_members (org_id, user_id, role)
    values (
      (select id from organizations limit 1),
      (select tests.get_supabase_uid('org_editor')),
      'viewer'
    )
  $$,
  '42501',
  'new row violates row-level security policy for table "org_members"',
  'Editor cannot manage members'
);

-- Premium Content Access Tests
select tests.authenticate_as('premium_user');
select results_eq(
    $$select count(*) from posts where org_id = (select id from organizations where slug = 'premium-org')$$,
    ARRAY[3::bigint],
    'Premium user can see all posts'
);

select tests.clear_authentication();
select results_eq(
    $$select count(*) from posts where org_id = (select id from organizations where slug = 'premium-org')$$,
    ARRAY[2::bigint],
    'Anonymous users can only see free posts'
);

-- Time-Based Publishing Tests
select tests.authenticate_as('scheduler');
select tests.freeze_time('2024-01-01 12:00:00+00'::timestamptz);

select results_eq(
    $$select count(*) from posts where scheduled_for > now() and org_id = (select id from organizations where slug = 'schedule-org')$$,
    ARRAY[1::bigint],
    'Can see scheduled posts'
);

select tests.freeze_time('2024-01-02 13:00:00+00'::timestamptz);

select results_eq(
    $$select count(*) from posts where scheduled_for < now() and org_id = (select id from organizations where slug = 'schedule-org')$$,
    ARRAY[1::bigint],
    'Can see posts after schedule time'
);

select tests.unfreeze_time();

-- Plan Limit Tests
select tests.authenticate_as('free_author');

select lives_ok(
  $$
    insert into posts (title, content, org_id, author_id, status)
    select 'Post 1', 'Content 1', id, auth.uid(), 'draft'
    from organizations where slug = 'free-org' limit 1
  $$,
  'First post creates successfully'
);

select lives_ok(
  $$
    insert into posts (title, content, org_id, author_id, status)
    select 'Post 2', 'Content 2', id, auth.uid(), 'draft'
    from organizations where slug = 'free-org' limit 1
  $$,
  'Second post creates successfully'
);

select throws_ok(
  $$
    insert into posts (title, content, org_id, author_id, status)
    select 'Post 3', 'Content 3', id, auth.uid(), 'draft'
    from organizations where slug = 'free-org' limit 1
  $$,
  '42501',
  'new row violates row-level security policy for table "posts"',
  'Cannot exceed free plan post limit'
);

select * from finish();
rollback;
```


## Additional resources

*   [Test Helpers Documentation](https://database.dev/basejump/supabase_test_helpers)
*   [Test Helpers Reference](https://github.com/usebasejump/supabase-test-helpers)
*   [Row Level Security Writing Guide](https://usebasejump.com/blog/testing-on-supabase-with-pgtap)
*   [Database.dev Package Registry](https://database.dev)
*   [Row Level Security Performance and Best Practices](https://github.com/orgs/supabase/discussions/14576)


# Supabase Platform



Supabase is a hosted platform which makes it very simple to get started without needing to manage any infrastructure.

Visit [supabase.com/dashboard](https://supabase.com/dashboard) and sign in to start creating projects.


## Projects

Each project on Supabase comes with:

*   A dedicated [Postgres database](/docs/guides/database)
*   [Auto-generated APIs](/docs/guides/database/api)
*   [Auth and user management](/docs/guides/auth)
*   [Edge Functions](/docs/guides/functions)
*   [Realtime API](/docs/guides/realtime)
*   [Storage](/docs/guides/storage)


## Organizations

Organizations are a way to group your projects. Each organization can be configured with different team members and billing settings.
Refer to [access control](/docs/guides/platform/access-control) for more information on how to manage team members within an organization.


## Platform status

If Supabase experiences outages, we keep you as informed as possible, as early as possible. We provide the following feedback channels:

*   Status page: [status.supabase.com](https://status.supabase.com/)
*   RSS Feed: [status.supabase.com/history.rss](https://status.supabase.com/history.rss)
*   Atom Feed: [status.supabase.com/history.atom](https://status.supabase.com/history.atom)
*   Slack Alerts: You can receive updates via the RSS feed, using Slack's [built-in RSS functionality](https://slack.com/help/articles/218688467-Add-RSS-feeds-to-Slack) `/feed subscribe https://status.supabase.com/history.atom`

Make sure to review our [SLA](/docs/company/sla) for details on our commitment to Platform Stability.


# Access Control



Supabase provides granular access controls to manage permissions across your organizations and projects.

For each organization and project, a member can have one of the following roles:

*   **Owner**: full access to everything in organization and project resources.
*   **Administrator**: full access to everything in organization and project resources **except** updating organization settings, transferring projects outside of the organization, and adding new owners.
*   **Developer**: read-only access to organization resources and content access to project resources but cannot change any project settings.
*   **Read-Only**: read-only access to organization and project resources.

When you first create an account, a default organization is created for you and you'll be assigned as the **Owner**. Any organizations you create will assign you as **Owner** as well.


## Manage organization members

To invite others to collaborate, visit your organization's team [settings](/dashboard/org/_/team) to send an invite link to another user's email. The invite is valid for 24 hours. For project scoped roles, you may only assign a role to a single project for the user when sending the invite. You can assign roles to multiple projects after the user accepts the invite.


### Transferring ownership of an organization

Each Supabase organization must have at least one owner. If your organization has other owners then you can relinquish ownership and leave the organization by clicking **Leave team** in your organization's team [settings](/dashboard/org/_/team).

Otherwise, you'll need to invite a user as **Owner**, and they need to accept the invitation, or promote an existing organization member to **Owner** before you can leave the organization.


### Organization scoped roles vs project scoped roles

Each member in the organization can be assigned a role scoped to the organization or to specific projects. If the member has a role at the organization level, they will have the equivalent permissions for that role across all current and future projects in the organization.

With project scoped permissions, you can assign members to roles scoped to specific projects.


### Organization permissions across roles

The table below shows the actions each role can take on the resources belonging to the organization.

| Resource                                                                                                    | Action     |                  Owner                  |              Administrator              |                Developer                |              Read-Only\[^1]              |
| ----------------------------------------------------------------------------------------------------------- | ---------- | :-------------------------------------: | :-------------------------------------: | :-------------------------------------: | :-------------------------------------: |
|                                         |            |                                         |                                         |                                         |                                         |
| Organization Management                                                                                     | Update     |  |                      |                      |                      |
|                                                                                                             | Delete     |  |                      |                      |                      |
| OpenAI Telemetry Configuration\[^2]                                                                          | Update     |  |                      |                      |                      |
|                                        |            |                                         |                                         |                                         |                                         |
| Organization Members                                                                                        | List       |  |  |  |  |
| Owner                                                                                                       | Add        |  |                      |                      |                      |
|                                                                                                             | Remove     |  |                      |                      |                      |
| Administrator                                                                                               | Add        |  |  |                      |                      |
|                                                                                                             | Remove     |  |  |                      |                      |
| Developer                                                                                                   | Add        |  |  |                      |                      |
|                                                                                                             | Remove     |  |  |                      |                      |
| Owner (Project-Scoped)                                                                                      | Add        |  |                      |                      |                      |
|                                                                                                             | Remove     |  |                      |                      |                      |
| Administrator (Project-Scoped)                                                                              | Add        |  |  |                      |                      |
|                                                                                                             | Remove     |  |  |                      |                      |
| Developer (Project-Scoped)                                                                                  | Add        |  |  |                      |                      |
|                                                                                                             | Remove     |  |  |                      |                      |
| Invite                                                                                                      | Revoke     |  |  |                      |                      |
|                                                                                                             | Resend     |  |  |                      |                      |
|                                                                                                             | Accept\[^3] |  |  |  |  |
|                                      |            |                                         |                                         |                                         |                                         |
| Invoices                                                                                                    | List       |  |  |  |  |
| Billing Email                                                                                               | View       |  |  |  |  |
|                                                                                                             | Update     |  |  |                      |                      |
| Subscription                                                                                                | View       |  |  |  |  |
|                                                                                                             | Update     |  |  |                      |                      |
| Billing Address                                                                                             | View       |  |  |  |  |
|                                                                                                             | Update     |  |  |                      |                      |
| Tax Codes                                                                                                   | View       |  |  |  |  |
|                                                                                                             | Update     |  |  |                      |                      |
| Payment Methods                                                                                             | View       |  |  |  |  |
|                                                                                                             | Update     |  |  |                      |                      |
| Usage                                                                                                       | View       |  |  |  |  |
|  |            |                                         |                                         |                                         |                                         |
| Authorize GitHub                                                                                            | -          |  |  |                      |                      |
| Add GitHub Repositories                                                                                     | -          |  |  |                      |                      |
| GitHub Connections                                                                                          | Create     |  |  |                      |                      |
|                                                                                                             | Update     |  |  |                      |                      |
|                                                                                                             | Delete     |  |  |                      |                      |
|                                                                                                             | View       |  |  |  |  |
| Vercel Connections                                                                                          | Create     |  |  |                      |                      |
|                                                                                                             | Update     |  |  |                      |                      |
|                                                                                                             | Delete     |  |  |                      |                      |
|                                                                                                             | View       |  |  |  |  |
|                                       |            |                                         |                                         |                                         |                                         |
| OAuth Apps                                                                                                  | Create     |  |  |                      |                      |
|                                                                                                             | Update     |  |  |                      |                      |
|                                                                                                             | Delete     |  |  |                      |                      |
|                                                                                                             | List       |  |  |  |  |
|                                       |            |                                         |                                         |                                         |                                         |
| View Audit logs                                                                                             | -          |  |  |  |  |
|                        |            |                                         |                                         |                                         |                                         |
| SOC2 Type 2 Report                                                                                          | Download   |  |  |  |  |
| Security Questionnaire                                                                                      | Download   |  |  |  |  |


### Project permissions across roles

The table below shows the actions each role can take on the resources belonging to the project.

| Resource                                                                                               | Action                 |                  Owner                  |                  Admin                  |                Developer                |                        Read-Only\[^4]\[^6]                        |
| ------------------------------------------------------------------------------------------------------ | ---------------------- | :-------------------------------------: | :-------------------------------------: | :-------------------------------------: | :-------------------------------------------------------------: |
|                                 |                        |                                         |                                         |                                         |                                                                 |
| Project Management                                                                                     | Transfer               |  |                      |                      |                                              |
|                                                                                                        | Create                 |  |  |                      |                                              |
|                                                                                                        | Delete                 |  |  |                      |                                              |
|                                                                                                        | Update (Name)          |  |  |                      |                                              |
|                                                                                                        | Pause                  |  |  |                      |                                              |
|                                                                                                        | Restore                |  |  |                      |                                              |
|                                                                                                        | Restart                |  |  |  |                                              |
| Custom Domains                                                                                         | View                   |  |  |  |                          |
|                                                                                                        | Update                 |  |  |                      |                                              |
| Data (Database)                                                                                        | View                   |  |  |  |       |
|                                                                                                        | Manage                 |  |  |  |                                              |
|            |                        |                                         |                                         |                                         |                                                                 |
| Read Replicas                                                                                          | List                   |  |  |  |                          |
|                                                                                                        | Create                 |  |  |                      |                                              |
|                                                                                                        | Delete                 |  |  |                      |                                              |
| Add-ons                                                                                                | Update                 |  |  |                      |                                              |
|        |                        |                                         |                                         |                                         |                                                                 |
| Authorize GitHub                                                                                       | -                      |  |  |  |                          |
| Add GitHub Repositories                                                                                | -                      |  |  |  |                          |
| GitHub Connections                                                                                     | Create                 |  |  |                      |                                              |
|                                                                                                        | Update                 |  |  |                      |                                              |
|                                                                                                        | Delete                 |  |  |                      |                                              |
|                                                                                                        | View                   |  |  |  |                          |
| Vercel Connections                                                                                     | Create                 |  |  |                      |                                              |
|                                                                                                        | Update                 |  |  |                      |                                              |
|                                                                                                        | Delete                 |  |  |                      |                                              |
|                                                                                                        | View                   |  |  |  |                          |
|  |                        |                                         |                                         |                                         |                                                                 |
| Reset Password                                                                                         | -                      |  |  |                      |                                              |
| Pooling Settings                                                                                       | View                   |  |  |  |                          |
|                                                                                                        | Update                 |  |  |                      |                                              |
| SSL Configuration                                                                                      | View                   |  |  |  |                          |
|                                                                                                        | Update                 |  |  |                      |                                              |
| Disk Size Configuration                                                                                | View                   |  |  |  |                          |
|                                                                                                        | Update                 |  |  |                      |                                              |
| Network Restrictions                                                                                   | View                   |  |  |  |                          |
|                                                                                                        | Create                 |  |  |                      |                                              |
|                                                                                                        | Delete                 |  |  |                      |                                              |
| Network Bans                                                                                           | View                   |  |  |  |                          |
|                                                                                                        | Unban                  |  |  |                      |                                              |
|                 |                        |                                         |                                         |                                         |                                                                 |
| API Keys                                                                                               | Read service key       |  |  |  |                                              |
|                                                                                                        | Read anon key          |  |  |  |                                              |
| JWT Secret                                                                                             | View                   |  |  |  |                                              |
|                                                                                                        | Generate new           |  |  |                      |                                              |
| API settings                                                                                           | View                   |  |  |  |                          |
|                                                                                                        | Update                 |  |  |                      |                                              |
|              |                        |                                         |                                         |                                         |                                                                 |
| Auth Settings                                                                                          | View                   |  |  |  |                          |
|                                                                                                        | Update                 |  |  |                      |                                              |
| SMTP Settings                                                                                          | View                   |  |  |  |                          |
|                                                                                                        | Update                 |  |  |  |                                              |
| Advanced Settings                                                                                      | View                   |  |  |  |                          |
|                                                                                                        | Update                 |  |  |                      |                                              |
|     |                        |                                         |                                         |                                         |                                                                 |
| Upload Limit                                                                                           | View                   |  |  |  |                          |
|                                                                                                        | Update                 |  |  |                      |                                              |
| S3 Access Keys                                                                                         | View                   |  |  |  |                                              |
|                                                                                                        | Create                 |  |  |                      |                                              |
|                                                                                                        | Delete                 |  |  |                      |                                              |
|    |                        |                                         |                                         |                                         |                                                                 |
| Secrets                                                                                                | View                   |  |  |  |  \[^5] |
|                                                                                                        | Create                 |  |  |                      |                                              |
|                                                                                                        | Delete                 |  |  |                      |                                              |
|                        |                        |                                         |                                         |                                         |                                                                 |
| Queries                                                                                                | Create                 |  |  |  |                          |
|                                                                                                        | Update                 |  |  |  |                          |
|                                                                                                        | Delete                 |  |  |  |                          |
|                                                                                                        | View                   |  |  |  |                          |
|                                                                                                        | List                   |  |  |  |                          |
|                                                                                                        | Run                    |  |  |  |  \[^7] |
|                              |                        |                                         |                                         |                                         |                                                                 |
| Scheduled Backups                                                                                      | View                   |  |  |  |                          |
|                                                                                                        | Download               |  |  |  |                                              |
|                                                                                                        | Restore                |  |  |  |                                              |
| Physical backups (PITR)                                                                                | View                   |  |  |  |                          |
|                                                                                                        | Restore                |  |  |  |                                              |
|                                |                        |                                         |                                         |                                         |                                                                 |
| Users                                                                                                  | Create                 |  |  |  |                                              |
|                                                                                                        | Delete                 |  |  |  |                                              |
|                                                                                                        | List                   |  |  |  |                          |
|                                                                                                        | Send OTP               |  |  |  |                                              |
|                                                                                                        | Send password recovery |  |  |  |                                              |
|                                                                                                        | Send magic link        |  |  |  |                                              |
|                                                                                                        | Remove MFA factors     |  |  |  |                                              |
| Providers                                                                                              | View                   |  |  |  |                          |
|                                                                                                        | Update                 |  |  |                      |                                              |
| Rate Limits                                                                                            | View                   |  |  |  |                          |
|                                                                                                        | Update                 |  |  |                      |                                              |
| Email Templates                                                                                        | View                   |  |  |  |                          |
|                                                                                                        | Update                 |  |  |                      |                                              |
| URL Configuration                                                                                      | View                   |  |  |  |                          |
|                                                                                                        | Update                 |  |  |                      |                                              |
| Hooks                                                                                                  | View                   |  |  |  |                          |
|                                                                                                        | Create                 |  |  |  |                                              |
|                                                                                                        | Delete                 |  |  |  |                                              |
|                                |                        |                                         |                                         |                                         |                                                                 |
| Buckets                                                                                                | Create                 |  |  |  |                                              |
|                                                                                                        | Update                 |  |  |  |                                              |
|                                                                                                        | Delete                 |  |  |  |                                              |
|                                                                                                        | View                   |  |  |  |                          |
|                                                                                                        | List                   |  |  |  |                          |
| Files                                                                                                  | Create (Upload)        |  |  |  |                                              |
|                                                                                                        | Update                 |  |  |  |                                              |
|                                                                                                        | Delete                 |  |  |  |                                              |
|                                                                                                        | List                   |  |  |  |                          |
|                               |                        |                                         |                                         |                                         |                                                                 |
| Edge Functions                                                                                         | Update                 |  |  |  |                                              |
|                                                                                                        | Delete                 |  |  |  |                                              |
|                                                                                                        | View                   |  |  |  |                          |
|                                                                                                        | List                   |  |  |  |                          |
|                      |                        |                                         |                                         |                                         |                                                                 |
| Custom Report                                                                                          | Create                 |  |  |  |                                              |
|                                                                                                        | Update                 |  |  |  |                                              |
|                                                                                                        | Delete                 |  |  |  |                                              |
|                                                                                                        | View                   |  |  |  |                          |
|                                                                                                        | List                   |  |  |  |                          |
|                    |                        |                                         |                                         |                                         |                                                                 |
| Queries                                                                                                | Create                 |  |  |  |                          |
|                                                                                                        | Update                 |  |  |  |                          |
|                                                                                                        | Delete                 |  |  |  |                          |
|                                                                                                        | View                   |  |  |  |                          |
|                                                                                                        | List                   |  |  |  |                          |
|                                                                                                        | Run                    |  |  |  |                          |
| Events Collections                                                                                     | Create                 |  |  |                      |                                              |
|                                                                                                        | Update                 |  |  |                      |                                              |
|                                                                                                        | Delete                 |  |  |                      |                                              |
|                                                                                                        | View                   |  |  |  |                          |
|                                                                                                        | List                   |  |  |  |                          |
| Warehouse Access Tokens                                                                                | Create                 |  |  |                      |                                              |
|                                                                                                        | Revoke                 |  |  |                      |                                              |
|                                                                                                        | List                   |  |  |  |                                              |
|                           |                        |                                         |                                         |                                         |                                                                 |
| Enable branching                                                                                       | -                      |  |  |                      |                                              |
| Disable branching                                                                                      | -                      |  |  |                      |                                              |
|                                                                                                        | Create                 |  |  |  |                                              |
|                                                                                                        | Delete                 |  |  |  |                                              |
|                                                                                                        | List                   |  |  |  |                          |

\[^1]: Available on the Team and Enterprise Plans.
\[^2]: Sending anonymous data to OpenAI is opt in and can improve Studio AI Assistant's responses.
\[^3]: Invites sent from a SSO account can only be accepted by another SSO account coming from the same identity provider. This is a security measure that prevents accidental invites to accounts not managed by your company's enterprise systems.
\[^4]: Available on the Enterprise Plan.
\[^5]: Read-Only role is able to access secrets.
\[^6]: Listed permissions are for the API and Dashboard.
\[^7]: Limited to executing SELECT queries. SQL Query Snippets run by the Read-Only role are run against the database using the **supabase\_read\_only\_user**. This role has the [predefined Postgres role pg\_read\_all\_data](https://www.postgresql.org/docs/current/predefined-roles.html).


# Database Backups



Database backups are an integral part of any disaster recovery plan. Disasters come in many shapes and sizes. It could be as simple as accidentally deleting a table column, the database crashing, or even a natural calamity wiping out the underlying hardware a database is running on. The risks and impact brought by these scenarios can never be fully eliminated, but only minimized or even mitigated. Having database backups is a form of insurance policy. They are essentially snapshots of the database at various points in time. When disaster strikes, database backups allow the project to be brought back to any of these points in time, therefore averting the crisis.


## Types of backups

Database backups can be categorized into two types: **logical** and **physical**. You can learn more about them [here](https://supabase.com/blog/postgresql-physical-logical-backups).

As a general rule of thumb, projects will either have logical or physical backups based on plan, database size, and add-ons:

| Plan       | Database Size (0-15GB) | [Database Size (>15GB)](#backup-process-for-large-databases) | [PITR](#point-in-time-recovery) | [Read Replicas](./read-replicas#prerequisites) |
| ---------- | ---------------------- | ------------------------------------------------------------ | ------------------------------- | ---------------------------------------------- |
| Pro        | logical                | physical                                                     | physical                        | physical                                       |
| Team       | logical                | physical                                                     | physical                        | physical                                       |
| Enterprise | physical               | physical                                                     | physical                        | physical                                       |

You can confirm your project's backup type by navigating to [Database Backups > Scheduled backups](https://supabase.com/dashboard/project/_/database/backups/scheduled) and if you can download a backup then it is logical, otherwise it is physical.

However, if your project has the Point-in-Time Recovery (PITR) add-on then the backups are physical and you can view them in [Database Backups > Point in time](https://supabase.com/dashboard/project/_/database/backups/pitr).


## Frequency of backups

When deciding how often a database should be backed up, the key business metric Recovery Point Objective (RPO) should be considered. RPO is the threshold for how much data, measured in time, a business could lose when disaster strikes. This amount is fully dependent on a business and its underlying requirements. A low RPO would mean that database backups would have to be taken at an increased cadence throughout the day. Each Supabase project has access to two forms of backups, Daily Backups and Point-in-Time Recovery (PITR). The agreed upon RPO would be a deciding factor in choosing which solution best fits a project.


## Daily backups

All Pro, Team and Enterprise Plan Supabase projects are backed up automatically on a daily basis. In terms of Recovery Point Objective (RPO), Daily Backups would be suitable for projects willing to lose up to 24 hours worth of data if disaster hits at the most inopportune time. If a lower RPO is required, enabling Point-in-Time Recovery should be considered.


### Backup process \[#daily-backups-process]

The Postgres utility [pg\_dumpall](https://www.postgresql.org/docs/current/app-pg-dumpall.html) is used to perform daily backups. An SQL file is generated, zipped up, and sent to our storage servers for safe keeping.

You can access daily backups in the [Scheduled backups](https://supabase.com/dashboard/project/_/database/backups/scheduled) settings in the Dashboard. Pro Plan projects can access the last 7 days' worth of daily backups. Team Plan projects can access the last 14 days' worth of daily backups, while Enterprise Plan projects can access up to 30 days' worth of daily backups. Users can restore their project to any one of the backups. If you wish to generate a logical backup on your own, you can do so through the [Supabase CLI](/docs/reference/cli/supabase-db-dump).


#### Backup process for large databases

Databases larger than 15GB\[^1], if they're on a recent build\[^2] of the Supabase platform, get automatically transitioned\[^3] to use daily physical backups. Physical backups are a more performant backup mechanism that lowers the overhead and impact on the database being backed up, and also avoids holding locks on objects in your database for a long period of time. While restores are unaffected, the backups created using this method cannot be downloaded from the Backups section of the dashboard.

This class of physical backups only allows for recovery to a fixed time each day, similar to daily backups. You can upgrade to [PITR](#point-in-time-recovery) for access to more granular recovery options.

Once a database is transitioned to using physical backups, it continues to use physical backups, even if the database size falls back below the threshold for the transition.

\[^1]: The threshold for transitioning will be slowly lowered over time. Eventually, all projects will be transitioned to using physical backups.
\[^2]: Projects created or upgraded after the 14th of July 2022 are eligible.
\[^3]: The transition to physical backups is handled transparently and does not require any user intervention. It involves a single restart of the database to pick up new configuration that can only be loaded at start; the expected downtime for the restart is a few seconds.


### Restoration process \[#daily-backups-restoration-process]

When selecting a backup to restore to, select the closest available one made before the desired point in time to restore to. Earlier backups can always be chosen too but do consider the number of days' worth of data that could be lost.

The Dashboard will then prompt for a confirmation before proceeding with the restoration. The project will be inaccessible following this. As such, do ensure to allot downtime beforehand. This is dependent on the size of the database. The larger it is, the longer the downtime will be. Once the confirmation has been given, the underlying SQL of the chosen backup is then run against the project. The Postgres utility [psql](https://www.postgresql.org/docs/current/app-psql.html) is used to facilitate the restoration. The Dashboard will display a notification once the restoration completes.

If your project is using subscriptions or replication slots, you will need to drop them prior to the restoration, and re-create them afterwards. The slot used by Realtime is exempted from this, and will be handled automatically.


## Point-in-Time recovery

Point-in-Time Recovery (PITR) allows a project to be backed up at much shorter intervals. This provides users an option to restore to any chosen point of up to seconds in granularity. Even with daily backups, a day's worth of data could still be lost. With PITR, backups could be performed up to the point of disaster.


### Backup process \[#pitr-backup-process]

As discussed [here](https://supabase.com/blog/postgresql-physical-logical-backups), PITR is made possible by a combination of taking physical backups of a project, as well as archiving [Write Ahead Log (WAL)](https://www.postgresql.org/docs/current/wal-intro.html) files. Physical backups provide a snapshot of the underlying directory of the database, while WAL files contain records of every change made in the database.

Supabase uses [WAL-G](https://github.com/wal-g/wal-g), an open source archival and restoration tool, to handle both aspects of PITR. On a daily basis, a snapshot of the database is taken and sent to our storage servers. Throughout the day, as database transactions occur, WAL files are generated and uploaded.

By default, WAL files are backed up at two minute intervals. If these files cross a certain file size threshold, they are backed up immediately. As such, during periods of high amount of transactions, WAL file backups become more frequent. Conversely, when there is no activity in the database, WAL file backups are not made. Overall, this would mean that at the worst case scenario or disaster, the PITR achieves a Recovery Point Objective (RPO) of two minutes.

![PITR dashboard](/docs/img/backups-pitr-dashboard.png)

You can access PITR in the [Point in Time](https://supabase.com/dashboard/project/_/database/backups/pitr) settings in the Dashboard. The recovery period of a project is indicated by the earliest and latest points of recoveries displayed in your preferred timezone. If need be, the maximum amount of this recovery period can be modified accordingly.

Note that the latest restore point of the project could be significantly far from the current time. This occurs when there has not been any recent activity in the database, and therefore no WAL file backups have been made recently. This is perfectly fine as the state of the database at the latest point of recovery would still be indicative of the state of the database at the current time given that no transactions have been made in between.


### Restoration process \[#pitr-restoration-process]

![PITR: Calendar view](/docs/img/backups-pitr-calendar-view.png)

A date and time picker will be provided upon pressing the `Start a restore` button. The process will only proceed if the selected date and time fall within the earliest and latest points of recoveries.

![PITR: Confirmation modal](/docs/img/backups-pitr-confirmation-modal.png)

After locking in the desired point in time to recover to, The Dashboard will then prompt for a review and confirmation before proceeding with the restoration. The project will be inaccessible following this. As such, do ensure to allot for downtime beforehand. This is dependent on the size of the database. The larger it is, the longer the downtime will be. Once the confirmation has been given, the latest physical backup available is downloaded to the project and the database is partially restored. WAL files generated after this physical backup up to the specified point-in-time are then downloaded. The underlying records of transactions in these files are replayed against the database to complete the restoration. The Dashboard will display a notification once the restoration completes.


### Pricing

For a detailed breakdown of how charges are calculated, refer to [Manage Point-in-Time Recovery usage](/docs/guides/platform/manage-your-usage/point-in-time-recovery).


## Restore to a new project

Supabase provides a convenient way to restore data from an existing project into a completely new one. Whether you're using physical backups or Point-in-Time recovery (PITR), this feature allows you to duplicate project data with ease, perform testing safely, or recover data for analysis. Access to this feature is exclusive to users on paid plans and requires that physical backups are enabled for the source project.

To begin, switch to the source project—the project containing the data you wish to restore—and go to the [database backups](https://supabase.com/dashboard/project/_/database/backups/restore-to-new-project) page. Select the **Restore to a New Project** tab.

A list of available backups is displayed. Select the backup you want to use and click the "Restore" button. For projects with PITR enabled, use the date and time selector to specify the exact point in time from which you wish to restore data.

Once you’ve made your choice, Supabase takes care of the rest. A new project is automatically created, replicating key configurations from the original, including the compute instance size, disk attributes, SSL enforcement settings, and network restrictions. The data will remain in the same region as the source project to ensure compliance with data residency requirements. The entire process is fully automated.

There are a few important restrictions to be aware of with the "Restore to a New Project" process:

*   Projects that are created through the restoration process cannot themselves be used as a source for further clones at this time.
*   The feature is only accessible to paid plan users with physical backups enabled, ensuring that the necessary resources and infrastructure are available for the restore process.

Before starting the restoration, you’ll be presented with an overview of the costs associated with creating the new project. The new project will incur additional monthly expenses based on the mirrored resources from the source project. It’s important to review these costs carefully before proceeding.

Once the restoration is complete, the new project will be available in your dashboard and will include all data, tables, schemas, and selected settings from the chosen backup source. It is recommended to thoroughly review the new project and perform any necessary tests to ensure everything has been restored as expected.

New projects are completely independent of their source, and as such can be modified and used as desired.

Restoring to a new project is an excellent way to manage environments more effectively. You can use this feature to create staging environments for testing, experiment with changes without risk to production data, or swiftly recover from unexpected data loss scenarios.


## Troubleshooting


### Logical backups


#### `search_path` issues

During the `pg_restore` process, the `search_path` is set to an empty string for predictability, and security. Using unqualified references to functions or relations can cause restorations using logical backups to fail, as the database will not be able to locate the function or relation being referenced. This can happen even if the database functions without issues during normal operations, as the `search_path` is usually set to include several schemas during normal operations. Therefore, you should always use schema-qualified names within your SQL code.

You can refer to [an example PR](https://github.com/supabase/supabase/pull/28393/files) on how to update SQL code to use schema-qualified names.


#### Invalid check constraints

Postgres requires that [check constraints](https://www.postgresql.org/docs/current/ddl-constraints.html#DDL-CONSTRAINTS-CHECK-CONSTRAINTS) be:

1.  immutable
2.  not reference table data other than the new or updated row being checked

Violating these requirements can result in numerous failure scenarios, including during logical restorations.

Common examples of check constraints that can result in such failures are:

*   validating against the current time, e.g. that the row being inserted references a future event
*   validating the contents of a row against the contents of another table


# Billing FAQ

This documentation covers frequently asked questions around subscription plans, payments, invoices and billing in general

## Organizations and projects


#### What are organizations and projects?

The Supabase Platform has "organizations" and "projects". An organization may contain multiple projects. Each project is a dedicated Supabase instance with all of its sub-services including Storage, Auth, Functions and Realtime.
Each organization only has a single subscription with a single plan (Free, Pro, Team or Enterprise). Project add-ons such as [Compute](/docs/guides/platform/compute-add-ons), [IPv4](/docs/guides/platform/ipv4-address), [Log Drains](/docs/guides/platform/log-drains), [Advanced MFA](/docs/guides/auth/auth-mfa/phone), [Custom Domains](https://supabase.com/docs/guides/platform/custom-domains) and [PITR](https://supabase.com/docs/guides/platform/backups#point-in-time-recovery) are configured per project and are added to your organization subscription.

Read more on [About billing on Supabase](https://supabase.com/docs/guides/platform/billing-on-supabase#organization-based-billing).


#### How many free projects can I have?

You are entitled to two active free projects. Paused projects do not count towards your quota. Note that within an organization, we count the free project limits from all members that are either Owner or Admin. If you’ve got another organization member with the Admin or Owner role that has already exhausted their free project quota, you won’t be able to launch another free project in that organization. You can create another Free Plan organization or change the role of the affected member in your [organization’s team settings](https://supabase.com/dashboard/org/_/team).


#### Can I mix free and paid projects in a single organization?

The subscription plan is set on the organization level and it is not possible to mix paid and non-paid projects inside a single organization. However, you can have a paid and a free organization and make use of the [self-serve project transfers](https://supabase.com/docs/guides/platform/project-transfer) to organize your projects. All projects in an organization benefit from the subscription plan. If your organization is on the Pro Plan, all projects within the organization benefit from no project pausing, automated backups and so on.


#### Can I transfer my projects to another organization?

Yes, you can transfer your projects to another organization. You can find instructions on how to transfer your projects [here](https://supabase.com/docs/guides/platform/project-transfer).


#### Can I transfer my credits to another organization?

Yes, you can transfer the credits to another organization. Submit a [support ticket](https://supabase.help).


## Pricing

See the [Pricing page](https://supabase.com/pricing) for details.


#### Are there any charges for paused projects?

No, we do not charge for paused projects. Compute hours are only counted for active instances. Paused projects do not incur any compute usage charges.


#### How are multiple projects billed under a paid organization?

We provide a dedicated server for every Supabase project. Each paid organization comes with $10 in Compute Credits to cover one project on the default compute size. Additional projects start at ~$10 a month (billed hourly).

Running 3 projects in a Pro Plan organization on the default Micro instance:

*   $25 Pro Plan
*   $30 for 3 projects on the default compute size
*   $10 Compute credits
    ⇒ $45 / month

Refer to our [Compute](/docs/guides/platform/manage-your-usage/compute#billing-examples) docs for more examples and insights.


#### How does compute billing work?

Each Supabase project is a dedicated VM and Postgres database. By default, your instance runs on the Micro compute instance. You have the option to upgrade your compute size in your [Project settings](https://supabase.com/dashboard/project/_/settings/addons). See [Compute Add-ons](https://supabase.com/docs/guides/platform/compute-add-ons) for available options.

When you change your compute size, there are no immediate upfront charges. Instead, you will be billed based on the compute hours during your billing cycle reset.

If you launch additional instances on your paid plan, we will add the corresponding compute hours to your final invoice.

If you upgrade your project to a larger instance for 10 hours and then downgrade, you’ll only pay for the larger instance for the 10 hours of usage at the end of your billing cycle. You can see your current compute usage on your [organization’s usage page](https://supabase.com/dashboard/org/_/usage).

Read more about [Compute usage](/docs/guides/platform/manage-your-usage/compute).


#### What is unified egress and how is it billed?

Unified egress refers to the total egress quota available to each organization. This quota can be utilized for various purposes such as Storage, Realtime, Auth, Functions, Supavisor, Log Drains and Database. Each plan includes a specific egress quota, and any additional usage beyond that quota is billed accordingly.

Read more about [Egress usage](/docs/guides/platform/manage-your-usage/egress).


## Plans and subscriptions


#### How do I change my subscription plan?

Change your subscription plan in your [organization's billing settings](https://supabase.com/dashboard/org/_/billing). To upgrade to an Enterprise Plan, complete the [Enterprise request form](https://forms.supabase.com/enterprise).


#### What happens if I cancel my subscription?

The organization is given [credits](/docs/guides/platform/credits) for unused time on the subscription plan. The credits will not expire and can be used again in the future. You may see an additional charge for unbilled excessive usage charges from your previous billing cycle.

Read more about [downgrades](/docs/guides/platform/manage-your-subscription#downgrade).


#### I mistakenly upgraded the wrong organization and then downgraded it. Could you issue a refund?

We can transfer the amount as [credits](/docs/guides/platform/credits) to another organization of your choice. You can use these credits to upgrade the organization, or if you have already upgraded, the credits will be used to pay the next month's invoice. Please create a [support ticket](https://supabase.help) for this case.


## Quotas and spend caps


#### What will happen when I exceed the Free Plan quota?

You will be notified when you exceed the Free Plan quota. It is important to take action at this point. If you continue to exceed the limits without reducing your usage, service restrictions will apply. To avoid service restrictions, you have two options: reduce your usage or upgrade to a paid plan. Learn more about restrictions in the [Fair Use Policy](#fair-use-policy) section.


#### What will happen when I exceed the Pro Plan quota and have the spend cap on?

You will be notified when you exceed your Pro Plan quota. To unblock yourself, you can toggle off your spend cap in your [organization’s billing settings](https://supabase.com/dashboard/org/_/billing) to pay for over-usage beyond the Pro plans limits. If you continue to exceed the limits without reducing your usage or turning off the spend cap, restrictions will apply. Learn more about restrictions in the [Fair Use Policy](#fair-use-policy) section.


#### How do I scale beyond the limits of my Pro Plan?

The Pro Plan has a Spend Cap enabled by default to keep costs under control. If you want to scale beyond the plan's included quota, switch off the Spend Cap to pay for additional usage beyond the plans included limits. You can toggle the Spend Cap in the [organization's billing settings](https://supabase.com/dashboard/org/_/billing). Read more about the [Spend Cap](/docs/guides/platform/cost-control#spend-cap).


## Fair Use Policy


#### What is the Fair Use Policy?

Our Fair Use Policy gives developers the freedom to build and experiment with Supabase, while protecting our infrastructure. Under the Fair Use policy, service restrictions may apply to your organization if:

*   You continually exceed the Free Plan quota
*   You continually exceed Pro Plan quota and have the spend cap enabled
*   You have overdue invoices
*   You have an expired credit card

You will receive a notification before Fair Use Policy restrictions are applied. However, in some cases, like suspected abuse of our services, restrictions may be applied without prior notice.


#### How is the Fair Use Policy applied?

The Fair Use Policy is applied through service restrictions. This could mean:

*   Pausing projects
*   Switching databases to read-only mode
*   Disabling new project launches/transfers
*   Responding with a [402 status code](/docs/guides/platform/http-status-codes#402-service-restriction) for all API requests

The Fair Use Policy is generally applied to all projects of the restricted organization.


#### How can I remove restrictions applied from the Fair Use Policy?

To remove restrictions, you will need to address the issue that caused the restriction. This could be reducing your usage, paying overdue invoices, updating your payment method, or any other issue that caused the restriction. Once the issue is resolved, the restriction will be lifted.

Restrictions due to usage limits are lifted with the next billing cycle as your quota refills at the beginning of each cycle. You can see when your current billing cycle ends on the [billing page](https://supabase.com/dashboard/org/_/billing) under "Upcoming Invoice". If your organization is on the Free Plan, you can also lift restrictions immediately by [upgrading](https://supabase.com/dashboard/org/_/billing?panel=subscriptionPlan) to Pro.


## Reports and invoices


#### Where do I find my invoices?

You can find all invoices from your organization on your [organization’s invoices page](https://supabase.com/dashboard/org/_/billing#invoices).


#### Where can I see a breakdown of usage?

You can find the breakdown of your usage on your [organization’s usage page](https://supabase.com/dashboard/org/_/usage).


#### Where can I check my credit balance?

You can check your Credit balance on the [organization’s billing page](https://supabase.com/dashboard/org/_/billing). Credits will be used on future invoices before charging your payment method. If you have enough credits to cover an invoice, there is no charge at all.


#### Can I include the VAT number?

You can update your VAT number in the Tax ID section of your [organization’s billing page](https://supabase.com/dashboard/org/_/billing).


#### Can I change the details of an existing invoice?

Any changes made to your billing details will only be reflected in your upcoming invoices. Our payment provider cannot regenerate previous invoices. Therefore, make sure to update the billing details before the upcoming invoices are finalized.


## Payments and billing cycle


#### What payment methods are available?

We accept credit card payments only. If you cannot pay via credit card, we do offer alternatives for larger upfront payments. Create a [support ticket](https://supabase.help) in case you’re interested.


#### What credit card brands are supported?

Visa, Mastercard, American Express, Japan Credit Bureau (JCB), China UnionPay (CUP), Cartes Bancaires


#### What currency can I pay in?

All our invoices are issued in USD, but you can pay in any currency so long as the credit card provider allows charging in USD after conversion.


#### Can I change the payment method?

Yes, you will have to add the new payment method before being allowed to remove the old one.
This can be done from your dashboard on the [organization’s billing page](https://supabase.com/dashboard/org/_/billing).

Read more on [Manage your payment methods](/docs/guides/platform/manage-your-subscription#manage-your-payment-methods).


#### Can I pay upfront for multiple months?

You can top up your credit balance to cover multiple months through your [organization’s billing page](https://supabase.com/dashboard/org/_/billing).

Read more on [Credit top-ups](/docs/guides/platform/credits#credit-top-ups).


#### When are payments taken?

Payments are taken at the beginning of each billing cycle. You will be charged once a month. You can see the current billing cycle and upcoming invoice in your [organization's billing settings](https://supabase.com/dashboard/org/_/billing). The subscription plan fee is charged upfront, whereas usage-charges, including compute, are charged in arrears based on your usage.

Read more on [Your monthly invoice](/docs/guides/platform/your-monthly-invoice).


#### Where can I change my billing details?

You can update your billing details on the [organization’s billing page](https://supabase.com/dashboard/org/_/billing).
Note that any changes made to your billing details will only be reflected in your upcoming invoices. Our payment provider cannot regenerate previous invoices.


#### What happens if I am unable to make the payment?

When an invoice becomes overdue, we will pause your projects and downgrade your organization to the Free Plan. You will be able to restore your projects once you have paid all outstanding invoices.


#### Why am I overdue?

We were unable to charge your payment method. This likely means that the payment was not successfully processed with the credit card on your account profile.
You can be overdue when

*   A card is expired
*   The bank declined the payment
*   You had insufficient funds
*   There was no card on record

Check your payment methods in your [organization’s billing page](https://supabase.com/dashboard/org/_/billing) to ensure there are no expired payment methods and the correct payment method is marked as default.
If you are still facing issues, raise a [support ticket](https://supabase.help).

Payments are always in USD and may show up as coming from Singapore, given our payment entity is in Singapore. Make sure you allow payments from Singapore and in USD


#### Can I delay my payment?

No, you cannot delay your payment.


#### Can I get a refund of my unused credits?

No, we do not provide refunds. Please refer to our [Terms of Service](https://supabase.com/terms#1-fees).


#### What do I do if my bill looks wrong?

Take a moment to review our [Your monthly invoice](/docs/guides/platform/your-monthly-invoice) page, which may help clarify any questions about your invoice. If it still looks wrong, submit a [support ticket](https://supabase.help) through the dashboard. Select the affected organization and provide the invoice number for us to look at your case.


# About billing on Supabase



## Subscription plans

Supabase offers different subscription plans—Free, Pro, Team, and Enterprise. For a closer look at each plan's features and pricing, visit our [pricing page](https://supabase.com/pricing).


### Free Plan

The Free Plan helps you get started and explore the platform. You are granted two free projects. The project limit applies across all organizations where you are an Owner or Administrator. This means you could have two Free Plan organizations with one project each, or one Free Plan organization with two projects. Paused projects do not count towards your free project limit.


### Paid plans

Upgrading your organization to a paid plan provides additional features, and you receive a higher [usage quota](/docs/guides/platform/billing-on-supabase#variable-usage-fees-and-quotas). You unlock the benefits of the paid plan for all projects within your organization - for example, no projects in your Pro Plan organization will be paused.


## Organization-based billing

Supabase bills separately for each organization. Each organization has its own subscription, including a unique subscription plan (Free, Pro, Team, or Enterprise), payment method, billing cycle, and invoices.

Different plans cannot be mixed within a single organization. For example, you cannot have both a Pro Plan project and a Free Plan project in the same organization. To have projects on different plans, you must create separate organizations. See [Project Transfers](/docs/guides/platform/project-transfer) if you need to move a project to a different organization.


## Costs

Monthly costs for paid plans include a fixed subscription fee based on your chosen plan and variable usage fees. To learn more about billing and cost management, refer to the following resources.

*   [Your monthly invoice](/docs/guides/platform/your-monthly-invoice) - For a detailed breakdown of what a monthly invoice includes
*   [Manage your usage](/docs/guides/platform/manage-your-usage) - For details on how the different usage items are billed, and how to optimize usage and reduce costs
*   [Control your costs]() - For details on how you can control your costs in case unexpected high usage occurs


### Compute costs for projects

An organization can have multiple projects. Each project includes a dedicated Postgres instance running on its own server. You are charged for the Compute resources of that server, independent of your database usage.

Read more about [Compute costs](/docs/guides/platform/manage-your-usage/compute).


## Variable Usage Fees and Quotas

Each subscription plan includes a built-in quota for some selected usage items, such as [Egress](/docs/guides/platform/manage-your-usage/egress), [Storage Size](/docs/guides/platform/manage-your-usage/storage-size), or [Edge Function Invocations](/docs/guides/platform/manage-your-usage/edge-function-invocations). This quota represents your free usage allowance. If you stay within it, you incur no extra charges for these items. Only usage beyond the quota is billed as overage.

For usage items without a quota, such as [Compute](/docs/guides/platform/manage-your-usage/compute) or [Custom Domains](/docs/guides/platform/manage-your-usage/custom-domains), you are charged for your entire usage.

The quota is applied to your entire organization, independent of how many projects you launch within that organization. For billing purposes, we sum the usage across all projects in a monthly invoice.

| Usage Item                       | Free                     | Pro/Team                                           | Enterprise |
| -------------------------------- | ------------------------ | -------------------------------------------------- | ---------- |
| Egress                           | 5 GB                     | 250 GB included, then $0.09 per GB                 | Custom     |
| Database Size                    | 500 MB                   | 8 GB disk per project included, then $0.125 per GB | Custom     |
| Monthly Active Users             | 50,000 MAU               | 100,000 MAU included, then $0.00325 per MAU        | Custom     |
| Monthly Active Third-Party Users | 50 MAU                   | 50 MAU included, then $0.00325 per MAU             | Custom     |
| Monthly Active SSO Users         | Unavailable on Free Plan | 50 MAU included, then $0.015 per MAU               | Custom     |
| Storage Size                     | 1 GB                     | 100 GB included, then $0.021 per GB                | Custom     |
| Storage Images Transformed       | Unavailable on Free Plan | 100 included, then $5 per 1000                     | Custom     |
| Edge Function Invocations        | 500,000                  | 2 million included, then $2 per million            | Custom     |
| Realtime Message Count           | 2 million                | 5 million included, then $2.5 per million          | Custom     |
| Realtime Peak Connections        | 200                      | 500 included, then $10 per 1000                    | Custom     |

You can find a detailed breakdown of all usage items and how they are billed on the [Manage your usage](/docs/guides/platform/manage-your-usage) page.


## Project add-ons

While your subscription plan applies to your entire organization and is charged only once, you can enhance individual projects by opting into various add-ons.

*   [Compute](/docs/guides/platform/compute-and-disk#compute) to scale your database up to 64 cores and 256 GB RAM
*   [Read Replicas](/docs/guides/platform/read-replicas) to scale read operations and provide resiliency
*   [Disk](/docs/guides/platform/compute-and-disk#disk) to provision extra IOPS/throughput or use a high-performance SSD
*   [Log Drains](/docs/guides/telemetry/log-drains) to sync Supabase logs to a logging system of your choice
*   [Custom Domains](/docs/guides/platform/custom-domains) to provide a branded experience
*   [PITR](/docs/guides/platform/backups#point-in-time-recovery) to roll back to any specific point in time, down to the minute
*   [IPv4](/docs/guides/platform/ipv4-address) for a dedicated IPv4 address
*   [Advanced MFA](/docs/guides/auth/auth-mfa/phone) to provide other options than TOTP


# Compute and Disk



## Compute

Every project on the Supabase Platform comes with its own dedicated Postgres instance.

The following table describes the base instances, Nano (free plan) and Micro (paid plans), with additional compute instance sizes available if you need extra performance when scaling up.

| Compute Size | Hourly Price USD | Monthly Price USD                                                                                                           | CPU                     | Memory       | Max DB Size (Recommended)\[^2] |
| ------------ | ---------------- | --------------------------------------------------------------------------------------------------------------------------- | ----------------------- | ------------ | ----------------------------- |
| Nano\[^3]     | $0               | $0                                                                                                                          | Shared                  | Up to 0.5 GB | 500 MB                        |
| Micro        | $0.01344         | ~$10                                                                                                                        | 2-core ARM (shared)     | 1 GB         | 10 GB                         |
| Small        | $0.0206          | ~$15                                                                                                                        | 2-core ARM (shared)     | 2 GB         | 50 GB                         |
| Medium       | $0.0822          | ~$60                                                                                                                        | 2-core ARM (shared)     | 4 GB         | 100 GB                        |
| Large        | $0.1517          | ~$110                                                                                                                       | 2-core ARM (dedicated)  | 8 GB         | 200 GB                        |
| XL           | $0.2877          | ~$210                                                                                                                       | 4-core ARM (dedicated)  | 16 GB        | 500 GB                        |
| 2XL          | $0.562           | ~$410                                                                                                                       | 8-core ARM (dedicated)  | 32 GB        | 1 TB                          |
| 4XL          | $1.32            | ~$960                                                                                                                       | 16-core ARM (dedicated) | 64 GB        | 2 TB                          |
| 8XL          | $2.562           | ~$1,870                                                                                                                     | 32-core ARM (dedicated) | 128 GB       | 4 TB                          |
| 12XL         | $3.836           | ~$2,800                                                                                                                     | 48-core ARM (dedicated) | 192 GB       | 6 TB                          |
| 16XL         | $5.12            | ~$3,730                                                                                                                     | 64-core ARM (dedicated) | 256 GB       | 10 TB                         |
| >16XL        | -                | [Contact Us](https://supabase.com/dashboard/support/new?category=sales\&subject=Enquiry%20about%20larger%20instance%20sizes) | Custom                  | Custom       | Custom                        |

\[^1]: Database max connections are recommended values and can be customized depending on your use case.
\[^2]: Database size for each compute instance is the default recommendation but the actual performance of your database has many contributing factors, including resources available to it and the size of the data contained within it. See the [shared responsibility model](https://supabase.com/docs/guides/platform/shared-responsibility-model) for more information.
\[^3]: Compute resources on the Free plan are subject to change.

Compute sizes can be changed by first selecting your project in the dashboard [here](https://supabase.com/dashboard/project/_/settings/compute-and-disk) and the upgrade process will [incur downtime](/docs/guides/platform/compute-and-disk#upgrade-downtime).

We charge hourly for additional compute based on your usage. Read more about [usage-based billing for compute](/docs/guides/platform/manage-your-usage/compute).


### Dedicated vs shared CPU

All Postgres databases on Supabase run in isolated environments. Compute instances smaller than `Large` compute size have CPUs which can burst to higher performance levels for short periods of time. Instances bigger than `Large` have predictable performance levels and do not exhibit the same burst behavior.


### Compute upgrades \[#upgrades]

When considering compute upgrades, assess whether your bottlenecks are hardware-constrained or software-constrained. For example, you may want to look into [optimizing the number of connections](/docs/guides/platform/performance#optimizing-the-number-of-connections) or [examining query performance](/docs/guides/platform/performance#examining-query-performance). When you're happy with your Postgres instance's performance, then you can focus on additional compute resources. For example, you can load test your application in staging to understand your compute requirements. You can also start out on a smaller tier, [create a report](https://supabase.com/dashboard/project/_/reports) in the Dashboard to monitor your CPU utilization, and upgrade as needed.


## Disk

Supabase databases are backed by high performance SSD disks. The *effective performance* depends on a combination of all the following factors:

*   Compute size
*   Provisioned Disk Throughput
*   Provisioned Disk IOPS: Input/Output Operations per Second, which measures the number of read and write operations.
*   Disk type: io2 or gp3
*   Disk size

The following sections explain how these attributes affect disk performance.


### Compute size

The compute size of your project sets the upper limit for disk throughput and IOPS. The table below shows the limits for each instance size. For instance, an 8XL compute instance has a maximum throughput of 9,500 Mbps and a maximum IOPS of 40,000.

| Compute Instance | Disk Throughput | IOPS        |
| ---------------- | --------------- | ----------- |
| Nano (free)      | 43 Mbps         | 250 IOPS    |
| Micro            | 87 Mbps         | 500 IOPS    |
| Small            | 174 Mbps        | 1,000 IOPS  |
| Medium           | 347 Mbps        | 2,000 IOPS  |
| Large            | 630 Mbps        | 3,600 IOPS  |
| XL               | 1,188 Mbps      | 6,000 IOPS  |
| 2XL              | 2,375 Mbps      | 12,000 IOPS |
| 4XL              | 4,750 Mbps      | 20,000 IOPS |
| 8XL              | 9,500 Mbps      | 40,000 IOPS |
| 12XL             | 14,250 Mbps     | 50,000 IOPS |
| 16XL             | 19,000 Mbps     | 80,000 IOPS |

Smaller compute instances like Nano, Micro, Small, and Medium have baseline performance levels that can occasionally be exceeded for short periods of time. If it does exceed the baseline, you should consider upgrading your instance size for a more reliable performance.

Larger compute instances (4XL and above) are designed for sustained, high performance with specific IOPS and throughput limits which you can [configure](/docs/guides/platform/manage-your-usage/disk-throughput). If you hit your IOPS or throughput limit, throttling will occur.


### Choosing the right compute instance for consistent disk performance

If you need consistent disk performance, choose the 4XL or larger compute instance. If you're unsure of how much throughput or IOPS your application requires, you can load test your project and inspect these [metrics in the Dashboard](https://supabase.com/dashboard/project/_/reports). If the `Disk IO % consumed` stat is more than 1%, it indicates that your workload has exceeded the baseline IO throughput during the day. If this metric goes to 100%, the workload has used up all available disk IO budget. Projects that use any disk IO budget are good candidates for upgrading to a larger compute instance with higher throughput.


### Provisioned disk throughput and IOPS

The default disk type is gp3, which comes with a baseline throughput of 125 MB/s and a default IOPS of 3,000. You can provision additional IOPS and throughput from the [Database Settings](https://supabase.com/dashboard/project/_/settings/compute-and-disk) page, but keep in mind that the effective IOPS and throughput will be limited by the compute instance size. This requires Large compute size or above.


### Disk types

When selecting your disk, it's essential to focus on the performance needs of your workload. Here's a comparison of our available disk types:

|                   | General Purpose SSD (gp3)                                                                                                                     | High Performance SSD (io2)                                                                           |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| **Use Case**      | General workloads, development environments, small to medium databases                                                                        | High-performance needs, large-scale databases, mission-critical applications                         |
| **Max Disk Size** | 16 TB                                                                                                                                         | 60 TB                                                                                                |
| **Max IOPS**      | 16,000 IOPS (at 32 GB disk size)                                                                                                              | 80,000 IOPS (at 80 GB disk size)                                                                     |
| **Throughput**    | 125 MB/s (default) to 1,000 MB/s (maximum)                                                                                                    | Automatically scales with IOPS                                                                       |
| **Best For**      | Great value for most use cases                                                                                                                | Low latency and very high IOPS requirements                                                          |
| **Pricing**       | Disk: 8 GB included, then $0.125 per GBIOPS: 3,000 included, then $0.024 per IOPSThroughput: 125 MB/s included, then $0.95 per MB/s | Disk: $0.195 per GBIOPS: $0.119 per IOPSThroughput: Scales with IOPS at no additional cost |

For general, day-to-day operations, gp3 should be more than enough. If you need high throughput and IOPS for critical systems, io2 will provide the performance required.


### Disk size

*   General Purpose (gp3) disks come with a baseline of 3,000 IOPS and 125 MB/s. You can provision additional 500 IOPS for every GB of disk size and additional 0.25 MB/s throughput per provisioned IOPS.
*   High Performance (io2) disks can be provisioned with 1,000 IOPS per GB of disk size.


## Limits and constraints


### Postgres replication slots, WAL senders, and connections

[Replication Slots](https://postgresqlco.nf/doc/en/param/max_replication_slots) and [WAL Senders](https://postgresqlco.nf/doc/en/param/max_wal_senders/) are used to enable [Postgres Replication](/docs/guides/database/replication). Each compute instance also has limits on the maximum number of database connections and connection pooler clients it can handle.

The maximum number of replication slots, WAL senders, database connections, and pooler clients depends on your compute instance size, as follows:

| Compute instance | Max Replication Slots | Max WAL Senders | Database Max Connections\[^1] | Connection Pooler Max Clients |
| ---------------- | --------------------- | --------------- | ---------------------------- | ----------------------------- |
| Nano (free)      | 5                     | 5               | 60                           | 200                           |
| Micro            | 5                     | 5               | 60                           | 200                           |
| Small            | 5                     | 5               | 90                           | 400                           |
| Medium           | 5                     | 5               | 120                          | 600                           |
| Large            | 8                     | 8               | 160                          | 800                           |
| XL               | 24                    | 24              | 240                          | 1,000                         |
| 2XL              | 80                    | 80              | 380                          | 1,500                         |
| 4XL              | 80                    | 80              | 480                          | 3,000                         |
| 8XL              | 80                    | 80              | 490                          | 6,000                         |
| 12XL             | 80                    | 80              | 500                          | 9,000                         |
| 16XL             | 80                    | 80              | 500                          | 12,000                        |


### Constraints

*   After **any** disk attribute change, there is a cooldown period of approximately six hours before you can make further adjustments. During this time, no changes are allowed. If you encounter throttling, you’ll need to wait until the cooldown period concludes before making additional modifications.
*   You can increase disk size but cannot decrease it.


# Control your costs



## Spend Cap

The Spend Cap determines whether your organization can exceed your subscription plan's quota for any usage item. Scenarios that could lead to high usage—and thus high costs—include system attacks or bugs in your software. The Spend Cap can protect you from these unexpected costs for certain usage items.

This feature is available only with the Pro Plan. However, you will not be charged while using the Free Plan.


### What happens when the Spend Cap is on?

After exceeding the quota for a usage item, further usage of that item is disallowed until the next billing cycle. You don't get charged for over-usage but your services will be restricted according to our [Fair Use Policy](/docs/guides/platform/billing-faq#fair-use-policy) if you consistently exceed the quota.


### What happens when the Spend Cap is off?

Your projects will continue to operate after exceeding the quota for a usage item. Any additional usage will be charged based on the item's cost per unit, as outlined on the [pricing page](https://supabase.com/pricing).


### Usage items covered by the Spend Cap

*   [Disk Size](/docs/guides/platform/manage-your-usage/disk-size)
*   [Egress](/docs/guides/platform/manage-your-usage/egress)
*   [Edge Function Invocations](/docs/guides/platform/manage-your-usage/edge-function-invocations)
*   [Monthly Active Users](/docs/guides/platform/manage-your-usage/monthly-active-users)
*   [Monthly Active SSO Users](/docs/guides/platform/manage-your-usage/monthly-active-users-sso)
*   [Monthly Active Third Party Users](/docs/guides/platform/manage-your-usage/monthly-active-users-third-party)
*   [Realtime Messages](/docs/guides/platform/manage-your-usage/realtime-messages)
*   [Realtime Peak Connections](/docs/guides/platform/manage-your-usage/realtime-peak-connections)
*   [Storage Image Transformations](/docs/guides/platform/manage-your-usage/storage-image-transformations)
*   [Storage Size](/docs/guides/platform/manage-your-usage/storage-size)


### Usage items not covered by the Spend Cap

Usage items that are predictable and explicitly opted into by the user are excluded.

*   [Compute](/docs/guides/platform/manage-your-usage/compute)
*   [Branching Compute](/docs/guides/platform/manage-your-usage/branching)
*   [Read Replica Compute](/docs/guides/platform/manage-your-usage/read-replicas)
*   [Custom Domain](/docs/guides/platform/manage-your-usage/custom-domains)
*   Additionally provisioned [Disk IOPS](/docs/guides/platform/manage-your-usage/disk-iops)
*   Additionally provisioned [Disk Throughput](/docs/guides/platform/manage-your-usage/disk-throughput)
*   [IPv4 address](/docs/guides/platform/manage-your-usage/ipv4)
*   [Log Drain Hours](/docs/guides/platform/manage-your-usage/log-drains#log-drain-hours)
*   [Log Drain Events](/docs/guides/platform/manage-your-usage/log-drains#log-drain-events)
*   [Multi-Factor Authentication Phone](/docs/guides/platform/manage-your-usage/advanced-mfa-phone)
*   [Point-in-Time-Recovery](/docs/guides/platform/manage-your-usage/point-in-time-recovery)


### What the Spend Cap is not

The Spend Cap doesn't allow for fine-grained cost control, such as setting budgets for specific usage item or receiving notifications when certain costs are reached. We plan to make cost control more flexible in the future.


### Configure the Spend Cap

You can configure the Spend Cap when creating an organization on the Pro Plan or at any time in the Cost Control section of the [organization's billing page](https://supabase.com/dashboard/org/_/billing).


## Keep track of your usage and costs

You can monitor your usage on the [organization's usage page](https://supabase.com/dashboard/org/_/usage). The Upcoming Invoice section of the [organization's billing page](https://supabase.com/dashboard/org/_/billing) shows your current spending and provides an estimate of your total costs for the billing cycle based on your usage.


# Credits



## Credit balance

Each organization has a credit balance. Credits are applied to future invoices to reduce the amount due. As long as the credit balance is greater than $0, credits will be used before charging your payment method on file.

You can find the credit balance on the [organization's billing page](https://supabase.com/dashboard/org/_/billing).


### What causes the credit balance to change?

**Subscription plan downgrades:** Upon subscription downgrade, any prepaid subscription fee will be credited back to your organization for unused time in the billing cycle.\
As an example, if you start a Pro Plan subscription on January 1 and downgrade to the Free Plan on January 15, your organization will receive about 50% of the subscription fee as credits for the unused time between January 15 and January 31.

**Credit top-ups:** You self-served a credit top-up or have signed an upfront credits deal with our growth team.


## Credit top-ups

You can top up credits at any time, with a maximum of $999 per top-up. These credits do not expire and are non-refundable.

You may want to consider this option to avoid issues with recurring payments, gain more control over how often your credit card is charged, and potentially make things easier for your accounting department.


### How to top up credits

1.  On the [organization's billing page](https://supabase.com/dashboard/org/_/billing), go to section **Credit Balance**
2.  Click **Top Up**
3.  Choose the amount
4.  Choose a payment method or add a new payment method
5.  Click **Top Up**


## Credit FAQ


### Will I get an invoice for the credits purchase?

Yes, once the payment is confirmed, you will get a matching invoice that can be accessed through your [organization's invoices page](/dashboard/org/_/billing#invoices).


### Can I transfer credits to another organization?

Yes, you can transfer credits to another organization. Submit a [support ticket](https://supabase.help).


### Can I get a refund of my unused credits?

No, we do not provide refunds. Please refer to our [Terms of Service](https://supabase.com/terms#1-fees).


# Custom Domains



Custom domains allow you to present a branded experience to your users. These are available as an [add-on for projects on a paid plan](/dashboard/project/_/settings/addons?panel=customDomain).

There are two types of domains supported by Supabase:

1.  Custom domains, where you use a domain such as `api.example.com` instead of the project's default domain.
2.  Vanity subdomains (experimental), where you can set up a different subdomain on `supabase.co` for your project.

You can choose either a custom domain or vanity subdomain for each project.


## Custom domains

Custom domains change the way your project's URLs appear to your users. This is useful when:

*   You are using [OAuth (Social Login)](/docs/guides/auth/social-login) with Supabase Auth and the project's URL is shown on the OAuth consent screen.
*   You are creating APIs for third-party systems, for example, implementing webhooks or external API calls to your project via [Edge Functions](/docs/guides/functions).
*   You are storing URLs in a database or encoding them in QR codes.

Custom domains help you keep your APIs portable for the long term. By using a custom domain you can migrate from one Supabase project to another, or make it easier to version APIs in the future.


### Configure a custom domain using the Supabase dashboard

Follow the **Custom Domains** steps in the [General Settings](https://supabase.com/dashboard/project/_/settings/general) page in the Dashboard to set up a custom domain for your project.


### Configure a custom domain using the Supabase CLI

This example assumes your Supabase project is `abcdefghijklmnopqrst` with a corresponding API URL `abcdefghijklmnopqrst.supabase.co` and configures a custom domain at `api.example.com`.

To get started:

1.  [Install](/docs/guides/resources/supabase-cli) the latest version of the Supabase CLI.
2.  [Log in](/docs/guides/cli/local-development#log-in-to-the-supabase-cli) to your Supabase account using the CLI.
3.  Ensure you have [Owner or Admin permissions](/docs/guides/platform/access-control#manage-team-members) for the project.
4.  Get a custom domain from a DNS provider. Currently, only subdomains are supported.
    *   Use `api.example.com` instead of `example.com`.


### Add a CNAME record

You need to add a CNAME record to your domain's DNS settings to ensure your custom domain points to the Supabase project.

If your project's default domain is `abcdefghijklmnopqrst.supabase.co` you should:

*   Create a CNAME record for `api.example.com` that resolves to `abcdefghijklmnopqrst.supabase.co.`.
*   Use a low TTL value to quickly propagate changes in case you make a mistake.


### Verify ownership of the domain

Register your domain with Supabase to prove that you own it. You need to download two TXT records and add them to your DNS settings.

In the CLI, run [`domains create`](/docs/reference/cli/supabase-domains-create) to register the domain and Supabase and get your verification records:

```bash
supabase domains create --project-ref abcdefghijklmnopqrst --custom-hostname api.example.com
```

A single TXT records is returned. For example:

```text
[...]
Required outstanding validation records:
        _acme-challenge.api.example.com. TXT -> ca3-F1HvR9i938OgVwpCFwi1jTsbhe1hvT0Ic3efPY3Q
```

Add the record to your domains' DNS settings. Make sure to trim surrounding whitespace. Use a low TTL value so you can quickly change the records if you make a mistake.

Some DNS registrars automatically append your domain name to the DNS entries being created. As such, creating a DNS record for `api.example.com` might instead create a record for `api.example.com.example.com`. In such cases, remove the domain name from the records you're creating; as an example, you would create a TXT record for `api`, instead of `api.example.com`.


### Verify your domain

Make sure you've configured all required DNS settings:

*   CNAME for your custom domain pointing to the Supabase project domain.
*   TXT record for `_acme-challenge.<your-custom-domain>`.

Use the [`domains reverify`](/docs/reference/cli/supabase-domains-reverify) command to begin the verification process of your domain. You may need to run this command a few times because DNS records take a while to propagate.

```bash
supabase domains reverify --project-ref abcdefghijklmnopqrst
```

In the background, Supabase will check your DNS records and use [Let's Encrypt](https://letsencrypt.org) to issue a SSL certificate for your domain. This process can take up to 30 minutes.


### Prepare to activate your domain

Before you activate your domain, prepare your applications and integrations for the domain change:

*   The project's Supabase domain remains active.
    *   You do not need to change the Supabase URL in your applications immediately.
    *   You can use it interchangeably with the custom domain.
*   Supabase Auth will use the custom domain immediately once activated.
    *   OAuth flows will advertise the custom domain as a callback URL.
    *   SAML will use the custom domain instead. This means that the `EntityID` of your project has changed, and this may cause SAML with existing identity providers to stop working.

To prevent issues for your users, follow these steps:

1.  For each of your Supabase OAuth providers:
    *   In the provider's developer console (not in the Supabase dashboard), find the OAuth application and add the custom domain Supabase Auth callback URL **in addition to the Supabase project URL.** Example:
        *   `https://abcdefghijklmnopqrst.supabase.co/auth/v1/callback` **and**
        *   `https://api.example.com/auth/v1/callback`
    *   [Sign in with Twitter](/docs/guides/auth/social-login/auth-twitter) uses cookies bound to the project's domain. Make sure your frontend code uses the custom domain instead of the default project's domain.
2.  For each of your SAML identity providers:
    *   Contact your provider and ask them to update the metadata for the SAML application. They should use `https://api.example.com/auth/v1/...` instead of `https://abcdefghijklmnopqrst.supabase.co/auth/v1/sso/saml/{metadata,acs,slo}`.
    *   Once these changes are made, SAML Single Sign-On will likely stop working until the domain is activated. Plan for this ahead of time.


### Activate your domain

Once you've done the necessary preparations to activate the new domain for your project, you can activate it using the [`domains activate`](/docs/reference/cli/supabase-domains-activate) CLI command.

```bash
supabase domains activate --project-ref abcdefghijklmnopqrst
```

When this step completes, Supabase will serve the requests from your new domain. The Supabase project domain **continues to work** and serve requests so you do not need to rush to change client code URLs.

If you wish to use the new domain in client code, change the URL used in your Supabase client libraries:

```js
import { createClient } from '@supabase/supabase-js'

// Use a custom domain as the supabase URL
const supabase = createClient('https://api.example.com', 'public-anon-key')
```

Similarly, your Edge Functions will now be available at `https://api.example.com/functions/v1/your_function_name`, and your Storage objects at `https://api.example.com/storage/v1/object/public/your_file_path.ext`.


### Remove a custom domain

Removing a custom domain may cause some issues when using Supabase Auth with OAuth or SAML. You may have to reverse the changes made in the *[Prepare to activate your domain](#prepare-to-activate-your-domain)* step above.

To remove an activated custom domain you can use the [`domains delete`](/docs/reference/cli/supabase-domains-delete) CLI command.

```bash
supabase domains delete --project-ref abcdefghijklmnopqrst
```


## Vanity subdomains

Vanity subdomains allow you to present a basic branded experience, compared to custom domains. They allow you to host your services at a custom subdomain on Supabase (e.g., `my-example-brand.supabase.co`) instead of the default, randomly assigned `abcdefghijklmnopqrst.supabase.co`.

To get started:

1.  [Install](/docs/guides/resources/supabase-cli) the latest version of the Supabase CLI.
2.  [Log in](/docs/guides/cli/local-development#log-in-to-the-supabase-cli) to your Supabase account using the CLI.
3.  Ensure that you have [Owner or Admin permissions](/docs/guides/platform/access-control#manage-team-members) for the project you'd like to set up a vanity subdomain for.
4.  Ensure that your organization is on a paid plan (Pro/Team/Enterprise Plan) in the [Billing page of the Dashboard](https://supabase.com/dashboard/org/_/billing).


### Configure a vanity subdomain

You can configure vanity subdomains via the CLI only.

Let's assume your Supabase project's domain is `abcdefghijklmnopqrst.supabase.co` and you wish to configure a vanity subdomain at `my-example-brand.supabase.co`.


### Check subdomain availability

Use the [`vanity-subdomains check-availability`](/docs/reference/cli/supabase-vanity-subdomains-check-availability) command of the CLI to check if your desired subdomain is available for use:

```bash
supabase vanity-subdomains --project-ref abcdefghijklmnopqrst check-availability --desired-subdomain my-example-brand --experimental
```


### Prepare to activate the subdomain

Before you activate your vanity subdomain, prepare your applications and integrations for the subdomain change:

*   The project's Supabase domain remains active and will not go away.
    *   You do not need to change the Supabase URL in your applications immediately or at once.
    *   You can use it interchangeably with the custom domain.
*   Supabase Auth will use the subdomain immediately once activated.
    *   OAuth flows will advertise the subdomain as a callback URL.
    *   SAML will use the subdomain instead. This means that the `EntityID` of your project has changed, and this may cause SAML with existing identity providers to stop working.

To prevent issues for your users, make sure you have gone through these steps:

1.  Go through all of your Supabase OAuth providers:
    *   In the provider's developer console (not in the Supabase dashboard!), find the OAuth application and add the subdomain Supabase Auth callback URL **in addition to the Supabase project URL.** Example:
        *   `https://abcdefghijklmnopqrst.supabase.co/auth/v1/callback` **and**
        *   `https://my-example-brand.supabase.co/auth/v1/callback`
    *   [Sign in with Twitter](/docs/guides/auth/social-login/auth-twitter) uses cookies bound to the project's domain. In this case make sure your frontend code uses the subdomain instead of the default project's domain.
2.  Go through all of your SAML identity providers:
    *   You will need to reach out via email to all of your existing identity providers and ask them to update the metadata for the SAML application (your project). Use `https://example-brand.supabase.co/auth/v1/...` instead of `https://abcdefghijklmnopqrst.supabase.co/auth/v1/sso/saml/{metadata,acs,slo}`.
    *   Once these changes are made, SAML Single Sign-On will likely stop working until the domain is activated. Plan for this ahead of time.


### Activate a subdomain

Once you've chosen an available subdomain and have done all the necessary preparations for it, you can reconfigure your Supabase project to start using it.

Use the [`vanity-subdomains activate`](/docs/reference/cli/supabase-vanity-subdomains-activate) command to activate and claim your subdomain:

```bash
supabase vanity-subdomains --project-ref abcdefghijklmnopqrst activate --desired-subdomain my-example-brand
```

If you wish to use the new domain in client code, you can set it up like so:

```js
import { createClient } from '@supabase/supabase-js'

// Use a custom domain as the supabase URL
const supabase = createClient('https://my-example-brand.supabase.co', 'public-anon-key')
```

When using [Sign in with Twitter](/docs/guides/auth/social-login/auth-twitter) make sure your frontend code is using the subdomain only.


### Remove a vanity subdomain

Removing a subdomain may cause some issues when using Supabase Auth with OAuth or SAML. You may have to reverse the changes made in the *[Prepare to activate the subdomain](#prepare-to-activate-the-subdomain)* step above.

Use the [`vanity-subdomains delete`](/docs/reference/cli/supabase-vanity-subdomains-delete) command of the CLI to remove the subdomain `my-example-brand.supabase.co` from your project.

```bash
supabase vanity-subdomains delete --project-ref abcdefghijklmnopqrst --experimental
```


## Pricing

For a detailed breakdown of how charges are calculated, refer to [Manage Custom Domain usage](/docs/guides/platform/manage-your-usage/custom-domains).


# Understanding Database and Disk Size



Disk metrics refer to the storage usage reported by Postgres. These metrics are updated daily. As you read through this document, we will refer to "database size" and "disk size":

*   *Database size*: Displays the actual size of the data within your Postgres database. This can be found on the [Database Reports page](https://supabase.com/dashboard/project/_/reports/database).

*   *Disk size*: Shows the overall disk space usage, which includes both the database size and additional files required for Postgres to function like the Write Ahead Log (WAL) and other system log files. You can view this on the [Database Settings page](https://supabase.com/dashboard/project/_/settings/database).


## Database size

This SQL query will show the size of all databases in your Postgres cluster:

```sql
select
  pg_size_pretty(sum(pg_database_size(pg_database.datname)))
from pg_database;
```

This value is reported in the [database report page](https://supabase.com/dashboard/project/_/reports/database).

Database size is consumed primarily by your data, indexes, and materialized views. You can reduce your database size by removing any of these and running a Vacuum operation.


### Disk space usage

Your database size is part of the disk usage for your Supabase project, there are many components to Postgres that consume additional disk space. One of the primary components, is the [Write Ahead Log (WAL)](https://www.postgresql.org/docs/current/wal-intro.html). Postgres will store database changes in log files that are cleared away after they are applied to the database. These same files are also used by [Read Replicas](/docs/guides/platform/read-replicas) or other replication methods.

If you would like to determine the size of the WAL files stored on disk, Postgres provides `pg_ls_waldir` as a helper function; the following query can be run:

```sql
select pg_size_pretty(sum(size)) as wal_size from pg_ls_waldir();
```


### Vacuum operations

Postgres does not immediately reclaim the physical space used by dead tuples (i.e., deleted rows) in the DB. They are marked as "removed" until a [vacuum operation](https://www.postgresql.org/docs/current/routine-vacuuming.html) is executed. As a result, deleting data from your database may not immediately reduce the reported disk usage. You can use the [Supabase CLI](https://supabase.com/docs/guides/cli/getting-started) `inspect db bloat` command to view all dead tuples in your database. Alternatively, you can run the [query](https://github.com/supabase/cli/blob/c9cce58025fded16b4c332747f819a44f45c3b83/internal/inspect/bloat/bloat.go#L17) found in the CLI's GitHub repo in the [SQL Editor](https://supabase.com/dashboard/project/_/sql/)

```bash
# Login to the CLI
npx supabase login

# Initialize a local supabase directory
npx supabase init

# Link a project
npx supabase link

# Detect bloat
npx supabase inspect db bloat --linked
```

If you find a table you would like to immediately clean, you can run the following in the [SQL Editor](https://supabase.com/dashboard/project/_/sql/new):

```sql
vacuum full <table name>;
```

Supabase projects have automatic vacuuming enabled, which ensures that these operations are performed regularly to keep the database healthy and performant.
It is possible to [fine-tune](https://www.percona.com/blog/2018/08/10/tuning-autovacuum-in-postgresql-and-autovacuum-internals/) the [autovacuum parameters](https://www.enterprisedb.com/blog/postgresql-vacuum-and-analyze-best-practice-tips), or [manually initiate](https://www.postgresql.org/docs/current/sql-vacuum.html) vacuum operations.
Running a manual vacuum after deleting large amounts of data from your DB could help reduce the database size reported by Postgres.


### Preoccupied space

New Supabase projects have a database size of ~40-60mb. This space includes pre-installed extensions, schemas, and default Postgres data. Additional database size is used when installing extensions, even if those extensions are inactive.


## Disk size

Supabase uses network-attached storage to balance performance with scalability. The disk scaling behavior depends on your billing plan.


### Paid plan behavior

Projects on the Pro Plan and higher have auto-scaling disks.

Disk size expands automatically when the database reaches 90% of the allocated disk size. The disk is expanded to be 50% larger (for example, 8 GB -> 12 GB). Auto-scaling can only take place once every 6 hours. If within those 6 hours you reach 95% of the disk space, your project will enter read-only mode.

Disk size can also be manually expanded on the [Database settings page](https://supabase.com/dashboard/project/_/settings/database). The maximum disk size for the Pro/Team Plan is 60 TB. If you need more than this, [contact us](https://forms.supabase.com/enterprise) to learn more about the Enterprise Plan.


### Free Plan behavior

Free Plan projects enter [read-only](#read-only-mode) mode when you exceed the 500 MB limit. Once in read-only mode, you have these options:

*   [Upgrade to the Pro Plan](https://supabase.com/dashboard/org/_/billing) to increase the limit to 8 GB. [Disable the Spend Cap](https://app.supabase.com/org/_/billing?panel=costControl) if you want your Pro instance to auto-scale beyond the 8 GB disk size limit.
*   [Disable read-only mode](#disabling-read-only-mode) and reduce your database size.


### Read-only mode

In some cases Supabase may put your database into read-only mode to prevent your database from exceeding the billing or disk limitations.

In read-only mode, clients will encounter errors such as `cannot execute INSERT in a read-only transaction`. Regular operation (read-write mode) is automatically re-enabled once usage is below 95% of the disk size,


### Disabling read-only mode

You manually override read-only mode to reduce disk size. To do this, run the following in the [SQL Editor](https://supabase.com/dashboard/project/_/sql):

First, change the [transaction access mode](https://www.postgresql.org/docs/current/sql-set-transaction.html):

```sql
set session characteristics as transaction read write;
```

This allows you to delete data from within the session. After deleting data, consider running a vacuum to reclaim as much space as possible:

```sql
vacuum;
```

Once you have reclaimed space, you can run the following to disable [read-only](https://www.postgresql.org/docs/current/runtime-config-client.html#GUC-DEFAULT-TRANSACTION-READ-ONLY) mode:

```sql
set default_transaction_read_only = 'off';
```


### Disk size distribution

You can check the distribution of your disk size on your [project's compute and disk page](/dashboard/_/settings/compute-and-disk).

![Disk Size Distribution](/docs/img/guides/platform/database-size/disk-size-distribution.png)

Your disk size usage falls in three categories:

*   **Database** - Disk usage by the database. This includes the actual data, indexes, materialized views, ...
*   **WAL** - Disk usage by the write-ahead log. The usage depends on your WAL settings and the amount of data being written to the database.
*   **System** - Disk usage reserved by the system to ensure the database can operate smoothly. Users cannot modify this and it should only take very little space.


### Reducing disk size

Disks don't automatically downsize during normal operation. Once you have [reduced your database size](/docs/guides/platform/database-size#database-size), they *will* automatically "right-size" during a [project upgrade](/docs/guides/platform/upgrading). The final disk size after the upgrade is 1.2x the size of the database with a minimum of 8 GB. For example, if your database size is 100GB, and you have a 200GB disk, the size after a project upgrade will be 120 GB.

In case you have a large WAL directory, you may [modify WAL settings](/docs/guides/database/custom-postgres-config) such as `max_wal_size`. Use at your own risk as changing these settings can have side effects. To query your current WAL size, use `SELECT SUM(size) FROM pg_ls_waldir()`.

In the event that your project is already on the latest version of Postgres and cannot be upgraded, a new version of Postgres will be released approximately every week which you can then upgrade to once it becomes available.


# Get set up for billing



Correct billing settings are essential for ensuring successful payment processing and uninterrupted services. Additionally, it's important to configure all invoicing-related data early, as this information cannot be changed once an invoice is issued. Review these key points to ensure everything is set up correctly from the start.


## Payments


### Ensuring valid credit card details

Paid plans require a credit card to be on file. Ensure the correct credit card is set as active and

*   has not expired
*   has sufficient funds
*   has a sufficient transaction limit

For more information on managing payment methods, see [Manage your payment methods](/docs/guides/platform/manage-your-subscription#manage-your-payment-methods).


### Alternatives to monthly charges

Instead of having your credit card charged every month, you can make an upfront payment by topping up your credit balance.

You may want to consider this option to avoid issues with recurring payments, gain more control over how often your credit card is charged, and potentially make things easier for your accounting department.

For more information on credits and credit top-ups, see the [Credits page](/docs/guides/platform/credits).


## Billing details

Billing details cannot be changed once an invoice is issued, so it's crucial to configure them correctly from the start.

You can update your billing email address, billing address and tax ID on the [organization's billing page](https://supabase.com/dashboard/org/_/billing).


# HIPAA Projects



You can use Supabase to store and process Protected Health Information (PHI). If you want to start developing healthcare apps on Supabase, reach out to the Supabase team [here](https://forms.supabase.com/hipaa2) to sign the Business Associate Agreement (BAA).


## Configuring a HIPAA project

When the HIPAA add-on is enabled on an organization, projects within the organization can be configured as *High Compliance*. This configuration can be found in the [General Project Settings page](https://supabase.com/dashboard/project/_/settings) of the dashboard.
Once enabled, additional security checks will be run against the project to ensure the deployed configuration is compliant. These checks are performed on a continual basis and security warnings will appear in the [Security Advisor](https://supabase.com/dashboard/project/_/advisors/security) if a non-compliant setting is detected.

The required project configuration is outlined in the [shared responsibility model](https://supabase.com/docs/guides/deployment/shared-responsibility-model#managing-healthcare-data) for managing healthcare data.

These include:

*   Enabling [Point in Time Recovery](/docs/guides/platform/backups#point-in-time-recovery) which requires at least a [small compute add-on](/docs/guides/platform/compute-add-ons).
*   Turning on [SSL Enforcement](/docs/guides/platform/ssl-enforcement).
*   Enabling [Network Restrictions](/docs/guides/platform/network-restrictions).

Additional security checks and controls will be added as the security advisor is extended and additional security controls are made available.


# Dedicated IPv4 Address for Ingress

Attach an IPv4 address to your database

The Supabase IPv4 add-on provides a dedicated IPv4 address for your Postgres database connection. It can be configured in the [Add-ons Settings](/dashboard/project/_/settings/addons).


## Understanding IP addresses

The Internet Protocol (IP) addresses devices on the internet. There are two main versions:

*   **IPv4**: The older version, with a limited address space.
*   **IPv6**: The newer version, offering a much larger address space and the future-proof option.


## When you need the IPv4 add-on:

*   When using the direct connection string in an IPv6-incompatible network instead of Supavisor or client libraries.
*   When you need a dedicated IP address for your direct connection string


## Enabling the IPv4 add-on

You can enable the IPv4 add-on in your project's [add-ons settings](/dashboard/project/_/settings/addons).


## Read replicas and IPv4 add-on

When using the add-on, each database (including read replicas) receives an IPv4 address. Each replica adds to the total IPv4 cost.


## Changes and updates

*   While the IPv4 address generally remains the same, actions like pausing/unpausing the project or enabling/disabling the add-on can lead to a new IPv4 address.


## Supabase and IPv6 compatibility

By default, Supabase Postgres use IPv6 addresses. If your system doesn't support IPv6, you have the following options:

1.  **Supavisor Connection Strings**: The Supavisor connection strings are IPv4-compatible alternatives to direct connections
2.  **Supabase Client Libraries**: These libraries are compatible with IPv4
3.  **Dedicated IPv4 Add-On (Pro Plans+)**: For a guaranteed IPv4 and static database address for the direct connection, enable this paid add-on.


### Checking your network IPv6 support

You can check if your personal network is IPv6 compatible at https://test-ipv6.com.


### Checking platforms for IPv6 support:

The majority of services are IPv6 compatible. However, there are a few prominent ones that only accept IPv4 connections:

*   [Retool](https://retool.com/)
*   [Vercel](https://vercel.com/)
*   [GitHub Actions](https://docs.github.com/en/actions)
*   [Render](https://render.com/)


## Finding your database's IP address

Use an IP lookup website or this command (replace `<PROJECT_REF>`):

```sh
nslookup db.<PROJECT_REF>.supabase.co
```


## Identifying your connections

The pooler and direct connection strings can be found in the [database settings](https://supabase.com/dashboard/project/_/settings/database):


#### Direct connection

IPv6 unless IPv4 Add-On is enabled

```sh
# Example direct connection string
postgresql://postgres:[YOUR-PASSWORD]@db.ajrbwkcuthywfihaarmflo.supabase.co:5432/postgres
```


#### Supavisor in transaction mode (port 6543)

Always uses an IPv4 address

```sh
# Example transaction string
postgresql://postgres.ajrbwkcuthywddfihrmflo:[YOUR-PASSWORD]@aws-0-us-east-1.pooler.supabase.com:6543/postgres
```


#### Supavisor in session mode (port 5432)

Always uses an IPv4 address

```sh
# Example session string
postgresql://postgres.ajrbwkcuthywfddihrmflo:[YOUR-PASSWORD]@aws-0-us-east-1.pooler.supabase.com:5432/postgres
```


## Pricing

For a detailed breakdown of how charges are calculated, refer to [Manage IPv4 usage](/docs/guides/platform/manage-your-usage/ipv4).


# Manage your subscription



## Manage your subscription plan

To change your subscription plan

1.  On the [organization's billing page](https://supabase.com/dashboard/org/_/billing), go to section **Subscription Plan**
2.  Click **Change subscription plan**
3.  On the side panel, choose a subscription plan
4.  Follow the prompts


### Upgrade

Upgrades take effect immediately. During the process, you are informed of the associated costs.

If you still have credits in your account, we will use the credits first before charging your card.


### Downgrade

Downgrades take effect immediately. During the process, you are informed of the implications.


#### Credits upon downgrade

Upon subscription downgrade, any prepaid subscription fee will be credited back to your organization for unused time in the billing cycle. These credits do not expire and will be applied to future invoices.

**Example:**
If you start a Pro Plan subscription on January 1 and downgrade to the Free Plan on January 15, your organization will receive about 50% of the subscription fee as credits for the unused time between January 15 and January 31.

As stated in our [Terms of Service](https://supabase.com/terms#1-fees), we do not offer refunds to the payment method on file.


#### Charges on downgrade

When you downgrade from a paid plan to the Free Plan, you will get credits for the unused time on the paid plan. However, you will also be charged for any excessive usage in the billing cycle.

The plan line item (e.g. Pro Plan) gets charged upfront, whereas all usage charges get charged in arrears, as we only know your usage by the end of the billing cycle. Excessive usage is charged whenever a billing cycle resets, so either when your monthly cycle resets, or whenever you do a plan change.

If you got charged after downgrading to the Free Plan, you had excessive usage in the previous billing cycle. You can check your invoices to see what exactly you were charged for.


## Manage your payment methods

You can add multiple payment methods, but only one can be active at a time.


### Add a payment method

1.  On the [organization's billing page](https://supabase.com/dashboard/org/_/billing), go to section **Payment Methods**
2.  Click **Add new card**
3.  Provide your credit card details
4.  Click **Add payment method**


### Delete a payment method

1.  On the [organization's billing page](https://supabase.com/dashboard/org/_/billing), go to section **Payment Methods**
2.  In the context menu of the payment method you want to delete, click **Delete card**
3.  Click **Confirm**


### Set a payment method as active

1.  On the [organization's billing page](https://supabase.com/dashboard/org/_/billing), go to section **Payment Methods**
2.  In the context menu of the payment method you want to delete, click **Use this card**
3.  Click **Confirm**


## Manage your billing details

You can update your billing email address, billing address and tax ID on the [organization's billing page](https://supabase.com/dashboard/org/_/billing).


# Manage your usage



Each subpage breaks down a specific usage item and details what you're charged for, how costs are calculated, and how to optimize usage and reduce costs.

*   [Compute](/docs/guides/platform/manage-your-usage/compute)
*   [Read Replicas](/docs/guides/platform/manage-your-usage/read-replicas)
*   [Branching](/docs/guides/platform/manage-your-usage/branching)
*   [Egress](/docs/guides/platform/manage-your-usage/egress)
*   [Disk Size](/docs/guides/platform/manage-your-usage/disk-size)
*   [Disk Throughput](/docs/guides/platform/manage-your-usage/disk-throughput)
*   [Disk IOPS](/docs/guides/platform/manage-your-usage/disk-iops)
*   [Monthly Active Users](/docs/guides/platform/manage-your-usage/monthly-active-users)
*   [Monthly Active Third-Party Users](/docs/guides/platform/manage-your-usage/monthly-active-users-third-party)
*   [Monthly Active SSO Users](/docs/guides/platform/manage-your-usage/monthly-active-users-sso)
*   [Storage Size](/docs/guides/platform/manage-your-usage/storage-size)
*   [Storage Image Transformations](/docs/guides/platform/manage-your-usage/storage-image-transformations)
*   [Edge Function Invocations](/docs/guides/platform/manage-your-usage/edge-function-invocations)
*   [Realtime Messages](/docs/guides/platform/manage-your-usage/realtime-messages)
*   [Realtime Peak Connections](/docs/guides/platform/manage-your-usage/realtime-peak-connections)
*   [Custom Domains](/docs/guides/platform/manage-your-usage/custom-domains)
*   [Point-in-Time Recovery](/docs/guides/platform/manage-your-usage/point-in-time-recovery)
*   [IPv4](/docs/guides/platform/manage-your-usage/ipv4)
*   [MFA Phone](/docs/guides/platform/manage-your-usage/advanced-mfa-phone)
*   [Log Drains](/docs/guides/platform/manage-your-usage/log-drains)


# Manage Advanced MFA Phone usage



## What you are charged for

You are charged for having the feature [Advanced Multi-Factor Authentication Phone](/docs/guides/auth/auth-mfa/phone) enabled for your project.


## How charges are calculated

MFA Phone is charged by the hour, meaning you are charged for the exact number of hours that the feature is enabled for a project. If the feature is enabled for part of an hour, you are still charged for the full hour.


### Example

Your billing cycle runs from January 1 to January 31. On January 10 at 4:30 PM, you enable the MFA Phone feature for your project. At the end of the billing cycle you are billed for 512 hours.

| Time Window                                 | MFA Phone | Hours Billed | Description         |
| ------------------------------------------- | --------- | ------------ | ------------------- |
| January 1, 00:00 AM - January 10, 4:00 PM   | Disabled  | 0            |                     |
| January 10, 04:00 PM - January 10, 4:30 PM  | Disabled  | 0            |                     |
| January 10, 04:30 PM - January 10, 5:00 PM  | Enabled   | 1            | full hour is billed |
| January 10, 05:00 PM - January 31, 23:59 PM | Enabled   | 511          |                     |


### Usage on your invoice

Usage is shown as "Auth MFA Phone Hours" on your invoice.


## Pricing


## Billing examples


### One project

The project has MFA Phone activated throughout the entire billing cycle.

| Line Item                     | Hours | Costs    |
| ----------------------------- | ----- | -------- |
| Pro Plan                      | -     | $25      |
| Compute Hours Micro Project 1 | 744   | $10      |
| MFA Phone Hours               | 744   | $75      |
| **Subtotal**                  |       | **$110** |
| Compute Credits               |       | -$10     |
| **Total**                     |       | **$100** |


### Multiple projects

All projects have MFA Phone activated throughout the entire billing cycle.

| Line Item                     | Hours | Costs    |
| ----------------------------- | ----- | -------- |
| Pro Plan                      | -     | $25      |
|                               |       |          |
| Compute Hours Micro Project 1 | 744   | $10      |
| MFA Phone Hours Project 1     | 744   | $75      |
|                               |       |          |
| Compute Hours Micro Project 2 | 744   | $10      |
| MFA Phone Hours Project 2     | 744   | $10      |
|                               |       |          |
| Compute Hours Micro Project 3 | 744   | $10      |
| MFA Phone Hours Project 3     | 744   | $10      |
|                               |       |          |
| **Subtotal**                  |       | **$150** |
| Compute Credits               |       | -$10     |
| **Total**                     |       | **$140** |


# Manage Branching usage



## What you are charged for

Each [Preview branch](/docs/guides/deployment/branching) is a separate environment with all Supabase services (Database, Auth, Storage, etc.). You're charged for usage within that environment—such as [Compute](/docs/guides/platform/manage-your-usage/compute), [Disk Size](/docs/guides/platform/manage-your-usage/disk-size), [Egress](/docs/guides/platform/manage-your-usage/egress), and [Storage](/docs/guides/platform/manage-your-usage/storage-size)—just like the project you branched from.

Usage by Preview branches counts toward your subscription plan's quota.


## How charges are calculated

Refer to individual [usage items](/docs/guides/platform/manage-your-usage) for details on how charges are calculated. Branching charges are the sum of all these items.


### Usage on your invoice

Compute incurred by Preview branches is shown as "Branching Compute Hours" on your invoice. Other usage items are not shown separately for branches and are rolled up into the project.


## Pricing


## Billing examples

The project has a Preview branch "XYZ", that runs for 30 hours, incurring Compute and Egress costs. Disk Size usage remains within the 8 GB included in the subscription plan, so no additional charges apply.

| Line Item                      | Costs     |
| ------------------------------ | --------- |
| Pro Plan                       | $25       |
|                                |           |
| Compute Hours Small Project 1  | $15       |
| Egress Project 1               | $7        |
| Disk Size Project 1            | $3        |
|                                |           |
| Compute Hours Micro Branch XYZ | $0.4      |
| Egress Branch XYZ              | $1        |
| Disk Size Branch XYZ           | $0        |
|                                |           |
| **Subtotal**                   | **$51.4** |
| Compute Credits                | -$10      |
| **Total**                      | **$41.4** |


## View usage

You can view Branching usage on the [organization's usage page](https://supabase.com/dashboard/org/_/usage). The page shows the usage of all projects by default. To view the usage for a specific project, select it from the dropdown. You can also select a different time period.

In the Usage Summary section, you can see how many hours your Preview branches existed during the selected time period. Hover over "Branches Compute Hours" for a detailed breakdown.


## Optimize usage

*   Merge Preview branches as soon as they are ready
*   Delete Preview branches that are no longer in use
*   Check whether your [persistent branches](/docs/guides/deployment/branching#persistent-branches) need to be defined as persistent, or if they can be ephemeral instead. Persistent branches will remain active even after the underlying PR is closed.


## FAQ


### Do Compute Credits apply to Branching Compute?

No, Compute Credits do not apply to Branching Compute.


# Manage Compute usage



## What you are charged for

Each project on the Supabase platform includes a dedicated Postgres instance running on its own server. You are charged for the [Compute](/docs/guides/platform/compute-and-disk#compute) resources of that server, independent of your database usage.

Paused projects do not count towards Compute usage.


## How charges are calculated

Compute is charged by the hour, meaning you are charged for the exact number of hours that a project is running and, therefore, incurring Compute usage. If a project runs for part of an hour, you are still charged for the full hour.


### Example

Your billing cycle runs from January 1 to January 31. On January 10 at 4:30 PM, you switch your project from the Micro Compute size to the Small Compute size. At the end of the billing cycle you are billed for 233 hours of Micro Compute size and 511 hours of Small Compute size.

| Time Window                                 | Compute Size | Hours Billed | Description         |
| ------------------------------------------- | ------------ | ------------ | ------------------- |
| January 1, 00:00 AM - January 10, 4:00 PM   | Micro        | 232          |                     |
| January 10, 04:00 PM - January 10, 4:30 PM  | Micro        | 1            | full hour is billed |
| January 10, 04:30 PM - January 10, 5:00 PM  | Small        | 1            | full hour is billed |
| January 10, 05:00 PM - January 31, 23:59 PM | Small        | 511          |                     |


### Usage on your invoice

Usage is shown as "Compute Hours" on your invoice.


## Compute Credits

Paid plans include $10 in Compute Credits, which cover one project running on the Micro/Nano Compute size or portions of other Compute sizes. Compute Credits are applied to your Compute costs and are provided to an organization each month. They reset monthly and do not accumulate.


## Pricing

| Compute Size | Hourly Price USD | Monthly Price USD                                                                                                           |
| ------------ | ---------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Nano\[^1]     | $0               | $0                                                                                                                          |
| Micro        | $0.01344         | ~$10                                                                                                                        |
| Small        | $0.0206          | ~$15                                                                                                                        |
| Medium       | $0.0822          | ~$60                                                                                                                        |
| Large        | $0.1517          | ~$110                                                                                                                       |
| XL           | $0.2877          | ~$210                                                                                                                       |
| 2XL          | $0.562           | ~$410                                                                                                                       |
| 4XL          | $1.32            | ~$960                                                                                                                       |
| 8XL          | $2.562           | ~$1,870                                                                                                                     |
| 12XL         | $3.836           | ~$2,800                                                                                                                     |
| 16XL         | $5.12            | ~$3,730                                                                                                                     |
| >16XL        | -                | [Contact Us](https://supabase.com/dashboard/support/new?category=sales\&subject=Enquiry%20about%20larger%20instance%20sizes) |

\[^1]: Compute resources on the Free Plan are subject to change.


## Billing examples


### One project

The project runs on the same Compute size throughout the entire billing cycle.

| Line Item                     | Hours | Costs   |
| ----------------------------- | ----- | ------- |
| Pro Plan                      | -     | $25     |
| Compute Hours Micro Project 1 | 744   | $10     |
| **Subtotal**                  |       | **$35** |
| Compute Credits               |       | -$10    |
| **Total**                     |       | **$25** |


### Multiple projects

All projects run on the same Compute size throughout the entire billing cycle.

| Line Item                     | Hours | Costs   |
| ----------------------------- | ----- | ------- |
| Pro Plan                      | -     | $25     |
| Compute Hours Micro Project 1 | 744   | $10     |
| Compute Hours Micro Project 2 | 744   | $10     |
| Compute Hours Micro Project 3 | 744   | $10     |
| **Subtotal**                  |       | **$55** |
| Compute Credits               |       | -$10    |
| **Total**                     |       | **$45** |


### One project on different Compute sizes

The project's Compute size changes throughout the billing cycle.

| Line Item                     | Hours | Costs   |
| ----------------------------- | ----- | ------- |
| Pro Plan                      | -     | $25     |
| Compute Hours Micro Project 1 | 233   | $3      |
| Compute Hours Small Project 1 | 511   | $11     |
| **Subtotal**                  |       | **$39** |
| Compute Credits               |       | -$10    |
| **Total**                     |       | **$29** |


## View usage

You can view Compute usage on the [organization's usage page](https://supabase.com/dashboard/org/_/usage). The page shows the usage of all projects by default. To view the usage for a specific project, select it from the dropdown. You can also select a different time period.

In the Compute Hours section, you can see how many hours of a specific Compute size your projects have used during the selected time period. Hover over a specific date for a daily breakdown.


## Optimize usage

*   Start out on a smaller Compute size, [create a report](https://supabase.com/dashboard/project/_/reports) on the Dashboard to monitor your CPU and memory utilization, and upgrade the Compute size as needed
*   Load test your application in staging to understand your Compute requirements
*   [Transfer projects](/docs/guides/platform/project-transfer) to a Free Plan organization to reduce Compute usage
*   Delete unused projects


## FAQ


### Do Compute Credits apply to line items other than Compute?

No, Compute Credits apply only to Compute and do not cover other line items, including Read Replica Compute and Branching Compute.


# Manage Custom Domain usage



## What you are charged for

You can configure a [custom domain](/docs/guides/platform/custom-domains) for a project by enabling the [Custom Domain add-on](https://supabase.com/dashboard/project/_/settings/addons?panel=customDomain). You are charged for all custom domains configured across your projects.


## How charges are calculated

Custom domains are charged by the hour, meaning you are charged for the exact number of hours that a custom domain is active. If a custom domain is active for part of an hour, you are still charged for the full hour.


### Example

Your billing cycle runs from January 1 to January 31. On January 10 at 4:30 PM, you activate a custom domain for your project. At the end of the billing cycle you are billed for 512 hours.

| Time Window                                 | Custom Domain Activated | Hours Billed | Description         |
| ------------------------------------------- | ----------------------- | ------------ | ------------------- |
| January 1, 00:00 AM - January 10, 4:00 PM   | No                      | 0            |                     |
| January 10, 04:00 PM - January 10, 4:30 PM  | No                      | 0            |                     |
| January 10, 04:30 PM - January 10, 5:00 PM  | Yes                     | 1            | full hour is billed |
| January 10, 05:00 PM - January 31, 23:59 PM | Yes                     | 511          |                     |


### Usage on your invoice

Usage is shown as "Custom Domain Hours" on your invoice.


## Pricing

$0.0137 per hour ($10 per month).


## Billing examples


### One project

The project has a custom domain activated throughout the entire billing cycle.

| Line Item                     | Hours | Costs   |
| ----------------------------- | ----- | ------- |
| Pro Plan                      | -     | $25     |
| Compute Hours Micro Project 1 | 744   | $10     |
| Custom Domain Hours           | 744   | $10     |
| **Subtotal**                  |       | **$45** |
| Compute Credits               |       | -$10    |
| **Total**                     |       | **$35** |


### Multiple projects

All projects have a custom domain activated throughout the entire billing cycle.

| Line Item                     | Hours | Costs   |
| ----------------------------- | ----- | ------- |
| Pro Plan                      | -     | $25     |
|                               |       |         |
| Compute Hours Micro Project 1 | 744   | $10     |
| Custom Domain Hours Project 1 | 744   | $10     |
|                               |       |         |
| Compute Hours Micro Project 2 | 744   | $10     |
| Custom Domain Hours Project 2 | 744   | $10     |
|                               |       |         |
| **Subtotal**                  |       | **$65** |
| Compute Credits               |       | -$10    |
| **Total**                     |       | **$55** |


## Optimize usage

*   Regularly check your projects and remove custom domains that are no longer needed
*   Use free [Vanity subdomains](/docs/guides/platform/custom-domains#vanity-subdomains) where applicable


# Manage Disk IOPS usage



## What you are charged for

Each database has a dedicated disk, and you are charged for its provisioned disk IOPS. However, unless you explicitly opt in for additional IOPS, no charges apply.

Refer to our [disk guide](/docs/guides/platform/compute-and-disk#disk) for details on how disk IOPS, disk throughput, disk size, disk type and compute size interact, along with their limitations and constraints.


## How charges are calculated

Disk IOPS is charged by IOPS-Hrs. 1 IOPS-Hr represents 1 IOPS being provisioned for 1 hour. For example, having 10 IOPS provisioned for 5 hours results in 50 IOPS-Hrs (10 IOPS × 5 hours).


### Usage on your invoice

Usage is shown as "Disk IOPS-Hrs" on your invoice.


## Pricing

Pricing depends on the [disk type](/docs/guides/platform/compute-and-disk#disk-types), with type gp3 being the default.


### General purpose disks (gp3)

$0.00003288 per IOPS-Hr ($0.024 per IOPS per month). gp3 disks come with a default IOPS of 3,000. You are only charged for provisioned IOPS exceeding these 3,000 IOPS.

| Plan       | Included Disk IOPS | Over-Usage per IOPS per month | Over-Usage per IOPS-Hr |
| ---------- | ------------------ | ----------------------------- | ---------------------- |
| Pro        | 3,000              | $0.024                        | $0.00003288            |
| Team       | 3,000              | $0.024                        | $0.00003288            |
| Enterprise | Custom             | Custom                        | Custom                 |


### High performance disks (io2)

$0.000163 per IOPS-Hr ($0.119 per IOPS per month).
Unlike general purpose disks, high performance disks are billed from the first provisioned IOPS.

| Plan       | Included Disk IOPS | Usage per IOPS per month | Usage per IOPS-Hr |
| ---------- | ------------------ | ------------------------ | ----------------- |
| Pro        | 0                  | $0.119                   | $0.000163         |
| Team       | 0                  | $0.119                   | $0.000163         |
| Enterprise | Custom             | Custom                   | Custom            |


## Billing examples


### Gp3

Project 1 doesn't exceed the included IOPS, so no charges for IOPS apply. Project 2 exceeds the included IOPS by 600, incurring charges for this additional usage.

| Line Item                     | Units      | Costs       |
| ----------------------------- | ---------- | ----------- |
| Pro Plan                      | 1          | $25         |
|                               |            |             |
| Compute Hours Micro Project 1 | 744 hours  | $10         |
| Disk IOPS Project 1           | 3,000 IOPS | $0          |
|                               |            |             |
| Compute Hours Large Project 2 | 744 hours  | $110        |
| Disk IOPS Project 2           | 3,600 IOPS | $14.40      |
|                               |            |             |
| **Subtotal**                  |            | **$159.40** |
| Compute Credits               |            | -$10        |
| **Total**                     |            | **$149.40** |


### Io2

This disk type is billed from the first IOPS provisioned, meaning for 8000 IOPS.

| Line Item                     | Units      | Costs      |
| ----------------------------- | ---------- | ---------- |
| Pro Plan                      | 1          | $25        |
| Compute Hours Large Project 1 | 744 hours  | $110       |
| Disk IOPS Project 1           | 8,000 IOPS | $952       |
| **Subtotal**                  |            | **$1,087** |
| Compute Credits               |            | -$10       |
| **Total**                     |            | **$1,077** |


# Manage Disk size usage



## What you are charged for

Each database has a dedicated [disk](/docs/guides/platform/compute-and-disk#disk). You are charged for the provisioned disk size.


## How charges are calculated

Disk size is charged by Gigabyte-Hours (GB-Hrs). 1 GB-Hr represents 1 GB being provisioned for 1 hour.
For example, having 10 GB provisioned for 5 hours results in 50 GB-Hrs (10 GB × 5 hours).


### Usage on your invoice

Usage is shown as "Disk Size GB-Hrs" on your invoice.


## Pricing

Pricing depends on the [disk type](/docs/guides/platform/compute-and-disk#disk-types), with gp3 being the default disk type.


### General purpose disks (gp3)

$0.000171 per GB-Hr ($0.125 per GB per month). The primary database of your project gets provisioned with an 8 GB disk. You are only charged for provisioned disk size exceeding these 8 GB.

| Plan       | Included Disk Size | Over-Usage per GB per month | Over-Usage per GB-Hr |
| ---------- | ------------------ | --------------------------- | -------------------- |
| Pro        | 8 GB               | $0.125                      | $0.000171            |
| Team       | 8 GB               | $0.125                      | $0.000171            |
| Enterprise | Custom             | Custom                      | Custom               |


### High performance disks (io2)

$0.000267 per GB-Hr ($0.195 per GB per month).
Unlike general purpose disks, high performance disks are billed from the first byte of provisioned disk.

| Plan       | Included Disk size | Usage per GB per month | Usage per GB-Hr |
| ---------- | ------------------ | ---------------------- | --------------- |
| Pro        | 0 GB               | $0.195                 | $0.000267       |
| Team       | 0 GB               | $0.195                 | $0.000267       |
| Enterprise | Custom             | Custom                 | Custom          |


## Billing examples


### Gp3

Project 1 and 2 don't exceed the included disk size, so no charges for Disk size apply. Project 3 exceeds the included disk size by 42 GB, incurring charges for this additional usage.

| Line Item                     | Units     | Costs      |
| ----------------------------- | --------- | ---------- |
| Pro Plan                      | 1         | $25        |
|                               |           |            |
| Compute Hours Micro Project 1 | 744 hours | $10        |
| Disk Size Project 1           | 8 GB      | $0         |
|                               |           |            |
| Compute Hours Micro Project 2 | 744 hours | $10        |
| Disk Size Project 2           | 8 GB      | $0         |
|                               |           |            |
| Compute Hours Micro Project 3 | 744 hours | $10        |
| Disk Size Project 3           | 50 GB     | $5.25      |
|                               |           |            |
| **Subtotal**                  |           | **$50.25** |
| Compute Credits               |           | -$10       |
| **Total**                     |           | **$40.25** |


### Io2

This disk type is billed from the first byte of provisioned disk, meaning for 66 GB across all projects.

| Line Item                     | Units     | Costs      |
| ----------------------------- | --------- | ---------- |
| Pro Plan                      | 1         | $25        |
|                               |           |            |
| Compute Hours Micro Project 1 | 744 hours | $10        |
| Disk Size Project 1           | 8 GB      | $1.56      |
|                               |           |            |
| Compute Hours Micro Project 2 | 744 hours | $10        |
| Disk Size Project 2           | 8 GB      | $1.56      |
|                               |           |            |
| Compute Hours Micro Project 3 | 744 hours | $10        |
| Disk Size Project 3           | 50 GB     | $9.75      |
|                               |           |            |
| **Subtotal**                  |           | **$67.87** |
| Compute Credits               |           | -$10       |
| **Total**                     |           | **$57.87** |


## View usage

You can view Disk size usage on the [organization's usage page](https://supabase.com/dashboard/org/_/usage). The page shows the usage of all projects by default. To view the usage for a specific project, select it from the dropdown.

In the Disk size section, you can see how much disk size your projects have provisioned.


### Disk size distribution

To see how your disk usage is distributed across Database, WAL, and System categories, refer to [Disk size distribution](/docs/guides/platform/database-size#disk-size-distribution).


## Reduce Disk size

To see how you can downsize your disk, refer to [Reducing disk size](/docs/guides/platform/database-size#reducing-disk-size)


# Manage Disk Throughput usage



## What you are charged for

Each database has a dedicated disk, and you are charged for its provisioned disk throughput. However, unless you explicitly opt in for additional throughput, no charges apply.

Refer to our [disk guide](/docs/guides/platform/compute-and-disk#disk) for details on how disk throughput, disk IOPS, disk size, disk type and compute size interact, along with their limitations and constraints.


## How charges are calculated

Disk throughput is charged by MB/s-Hrs (MB/s stands for megabytes per second). 1 MB/s-Hr represents disk throughput of 1 MB/s being provisioned for 1 hour. For example, having 10 MB/s provisioned for 5 hours results in 50 MB/s-Hrs (10 MB/s × 5 hours).


### Usage on your invoice

Usage is shown as "Disk Throughput MB/s-Hrs" on your invoice.


## Pricing

Pricing depends on the [disk type](/docs/guides/platform/compute-and-disk#disk-types), with type gp3 being the default.


### General purpose disks (gp3)

$0.00013 per MB/s-Hr ($0.095 per MB/s per month). gp3 disks come with a baseline throughput of 125 MB/s. You are only charged for provisioned throughput exceeding these 125 MB/s.

| Plan       | Included Disk Throughput | Over-Usage per MB/s per month | Over-Usage per MB/s-Hr |
| ---------- | ------------------------ | ----------------------------- | ---------------------- |
| Pro        | 125 MB/s                 | $0.095                        | $0.00013               |
| Team       | 125 MB/s                 | $0.095                        | $0.00013               |
| Enterprise | Custom                   | Custom                        | Custom                 |


### High performance disks (io2)

There are no charges. Throughput scales with IOPS at no additional cost.


## Billing examples


### No additional throughput configured

| Line Item                     | Units     | Costs   |
| ----------------------------- | --------- | ------- |
| Pro Plan                      | 1         | $25     |
|                               |           |         |
| Compute Hours Micro Project 1 | 744 hours | $10     |
| Disk Throughput Project 1     | 125 MB/s  | $0      |
|                               |           |         |
| **Subtotal**                  |           | **$35** |
| Compute Credits               |           | -$10    |
| **Total**                     |           | **$25** |


### Additional throughput configured

| Line Item                     | Units     | Costs       |
| ----------------------------- | --------- | ----------- |
| Pro Plan                      | 1         | $25         |
|                               |           |             |
| Compute Hours Large Project 1 | 744 hours | $110        |
| Disk Throughput Project 1     | 200 MB/s  | $7.13       |
|                               |           |             |
| **Subtotal**                  |           | **$142.13** |
| Compute Credits               |           | -$10        |
| **Total**                     |           | **$132.13** |


### Additional throughput configured with Read Replica

| Line Item                     | Units     | Costs       |
| ----------------------------- | --------- | ----------- |
| Pro Plan                      | 1         | $25         |
|                               |           |             |
| Compute Hours Large Project 1 | 744 hours | $110        |
| Disk Throughput Project 1     | 200 MB/s  | $7.13       |
|                               |           |             |
| Compute Hours Large Replica   | 744 hours | $110        |
| Disk Throughput Replica       | 200 MB/s  | $7.13       |
|                               |           |             |
| **Subtotal**                  |           | **$259.26** |
| Compute Credits               |           | -$10        |
| **Total**                     |           | **$249.26** |


# Manage Edge Function Invocations usage



## What you are charged for

You are charged for the number of times your functions get invoked, regardless of the response status code.


## How charges are calculated

Edge Function Invocations are billed using Package pricing, with each package representing 1 million invocations. If your usage falls between two packages, you are billed for the next whole package.


### Example

For simplicity, let's assume a package size of 1 million and a charge of $2 per package without a free quota.

| Invocations | Packages Billed | Costs |
| ----------- | --------------- | ----- |
| 999,999     | 1               | $2    |
| 1,000,000   | 1               | $2    |
| 1,000,001   | 2               | $4    |
| 1,500,000   | 2               | $4    |


### Usage on your invoice

Usage is shown as "Function Invocations" on your invoice.


## Pricing


## Billing examples


### Within quota

The organization's function invocations are within the quota, so no charges apply.

| Line Item            | Units                 | Costs   |
| -------------------- | --------------------- | ------- |
| Pro Plan             | 1                     | $25     |
| Compute Hours Micro  | 744 hours             | $10     |
| Function Invocations | 1,800,000 invocations | $0      |
| **Subtotal**         |                       | **$35** |
| Compute Credits      |                       | -$10    |
| **Total**            |                       | **$25** |


### Exceeding quota

The organization's function invocations exceed the quota by 1.4 million, incurring charges for this additional usage.

| Line Item            | Units                 | Costs   |
| -------------------- | --------------------- | ------- |
| Pro Plan             | 1                     | $25     |
| Compute Hours Micro  | 744 hours             | $10     |
| Function Invocations | 3,400,000 invocations | $4      |
| **Subtotal**         |                       | **$39** |
| Compute Credits      |                       | -$10    |
| **Total**            |                       | **$29** |


## View usage

You can view Edge Function Invocations usage on the [organization's usage page](https://supabase.com/dashboard/org/_/usage). The page shows the usage of all projects by default. To view the usage for a specific project, select it from the dropdown. You can also select a different time period.

In the Edge Function Invocations section, you can see how many invocations your projects have had during the selected time period.


# Manage Egress usage



## What you are charged for

You are charged for the network data transmitted out of the system to a connected client. Egress is incurred by all services - Database, Auth, Storage, Edge Functions, Realtime and Log Drains.


### Database Egress

Data sent to the client when retrieving data stored in your database.

**Example:** A user views their order history in an online shop. The client application requests the database to retrieve the user's past orders. The order data is sent back to the client, contributing to Database Egress.


### Auth Egress

Data sent from Supabase Auth to the client while managing your application's users. This includes actions like signing in, signing out, or creating new users, e.g. via the JavaScript Client SDK.

**Example:** A user signs in to an online shop. The client application requests the Supabase Auth service to authenticate and authorize the user. The session data, including authentication tokens and user profile details, is sent back to the client, contributing to Auth Egress.


### Storage Egress

Data sent from Supabase Storage to the client when retrieving assets. This includes actions like downloading files, images, or other stored content, e.g. via the JavaScript Client SDK.

**Example:** A user downloads an invoice from an online shop. The client application requests Supabase Storage to retrieve the PDF file from the storage bucket. The file is sent back to the client, contributing to Storage Egress.


### Edge Functions Egress

Data sent to the client when executing Edge Functions.

**Example:** A user completes a checkout process in an online shop. The client application triggers an Edge Function to process the payment and confirm the order. The confirmation response, along with any necessary details, is sent back to the client, contributing to Edge Functions Egress.


### Realtime Egress

Data pushed to clients via Supabase Realtime for subscribed events.

**Example:** When a user views a product page in an online shop, their client subscribes to real-time inventory updates. As stock levels change, Supabase Realtime pushes updates to all subscribed clients, contributing to Realtime Egress.


### Log Drain Egress

Data pushed to the connected log drain.

**Example:** You set up a log drain, each log sent to the log drain is considered egress. You can toggle the GZIP option to reduce egress, in case your provider supports it.


## How charges are calculated

Egress is charged by gigabyte. Charges apply only for usage exceeding your subscription plan's quota. This quota is called the Unified Egress Quota because it can be used across all services (Database, Auth, Storage etc.).


### Usage on your invoice

Usage is shown as "Egress GB" on your invoice.


## Pricing

$0.09 per GB per month. You are only charged for usage exceeding your subscription plan's quota.

| Plan       | Unified Egress Quota | Over-Usage per month |
| ---------- | -------------------- | -------------------- |
| Free       | 5 GB                 | -                    |
| Pro        | 250 GB               | $0.09 per GB         |
| Team       | 250 GB               | $0.09 per GB         |
| Enterprise | Custom               | Custom               |


## Billing examples


### Within quota

The organization's Egress usage is within the quota, so no charges for Egress apply.

| Line Item           | Units     | Costs   |
| ------------------- | --------- | ------- |
| Pro Plan            | 1         | $25     |
| Compute Hours Micro | 744 hours | $10     |
| Egress              | 200 GB    | $0      |
| **Subtotal**        |           | **$35** |
| Compute Credits     |           | -$10    |
| **Total**           |           | **$25** |


### Exceeding quota

The organization's Egress usage exceeds the quota by 50 GB, incurring charges for this additional usage.

| Line Item           | Units     | Costs     |
| ------------------- | --------- | --------- |
| Pro Plan            | 1         | $25       |
| Compute Hours Micro | 744 hours | $10       |
| Egress              | 300 GB    | $4.5      |
| **Subtotal**        |           | **$39.5** |
| Compute Credits     |           | -$10      |
| **Total**           |           | **$29.5** |


## View usage


### Usage page

You can view Egress usage on the [organization's usage page](https://supabase.com/dashboard/org/_/usage). The page shows the usage of all projects by default. To view the usage for a specific project, select it from the dropdown. You can also select a different time period.

In the Total Egress section, you can see the usage for the selected time period. Hover over a specific date to view a breakdown by service.


### Custom report

1.  On the [reports page](https://supabase.com/dashboard/project/_/reports), click **New custom report** in the left navigation menu
2.  After creating a new report, add charts for one or more Supabase services by clicking **Add block**


## Debug usage

To better understand your Egress usage, identify what’s driving the most traffic. Check the most frequent database queries, or analyze the most requested API paths to pinpoint high-bandwidth endpoints.


### Frequent database queries

On the Advisors [Query performance view](https://supabase.com/dashboard/project/_/database/query-performance?preset=most_frequent\&sort=calls\&order=desc) you can see the most frequent queries and the average number of rows returned.


### Most requested API endpoints

In the [Logs Explorer](https://supabase.com/dashboard/project/_/logs/explorer) you can access Edge Logs, and review the top paths to identify heavily queried endpoints. These logs currently do not include response byte data. That data will be available in the future too.


## Optimize usage

*   Reduce the number of fields or entries selected when querying your database
*   Reduce the number of queries or calls by optimizing client code or using caches
*   For update or insert queries, configure your ORM or queries to not return the entire row if not needed
*   When running manual backups through Supavisor, remove unneeded tables and/or reduce the frequency
*   Refer to the [Storage Optimizations guide](/docs/guides/storage/production/scaling#egress) for tips on reducing Storage Egress


# Manage IPv4 usage



## What you are charged for

You can assign a dedicated [IPv4 address](/docs/guides/platform/ipv4-address) to a database by enabling the [IPv4 add-on](https://supabase.com/dashboard/project/_/settings/addons?panel=ipv4). You are charged for all IPv4 addresses configured across your databases.


## How charges are calculated

IPv4 addresses are charged by the hour, meaning you are charged for the exact number of hours that an IPv4 address is assigned to a database. If an address is assigned for part of an hour, you are still charged for the full hour.


### Example

Your billing cycle runs from January 1 to January 31. On January 10 at 4:30 PM, you enable the IPv4 add-on for your project. At the end of the billing cycle you are billed for 512 hours.

| Time Window                                 | IPv4 add-on | Hours Billed | Description         |
| ------------------------------------------- | ----------- | ------------ | ------------------- |
| January 1, 00:00 AM - January 10, 4:00 PM   | Disabled    | 0            |                     |
| January 10, 04:00 PM - January 10, 4:30 PM  | Disabled    | 0            |                     |
| January 10, 04:30 PM - January 10, 5:00 PM  | Enabled     | 1            | full hour is billed |
| January 10, 05:00 PM - January 31, 23:59 PM | Enabled     | 511          |                     |


### Usage on your invoice

Usage is shown as "IPv4 Hours" on your invoice.


## Pricing

$0.0055 per hour ($4 per month).


## Billing examples


### One project

The project has the IPv4 add-on enabled throughout the entire billing cycle.

| Line Item                     | Hours | Costs   |
| ----------------------------- | ----- | ------- |
| Pro Plan                      | -     | $25     |
| Compute Hours Micro Project 1 | 744   | $10     |
| IPv4 Hours                    | 744   | $4      |
| **Subtotal**                  |       | **$39** |
| Compute Credits               |       | -$10    |
| **Total**                     |       | **$29** |


### Multiple projects

All projects have the IPv4 add-on enabled throughout the entire billing cycle.

| Line Item                     | Hours | Costs   |
| ----------------------------- | ----- | ------- |
| Pro Plan                      | -     | $25     |
|                               |       |         |
| Compute Hours Micro Project 1 | 744   | $10     |
| IPv4 Hours Project 1          | 744   | $4      |
|                               |       |         |
| Compute Hours Micro Project 2 | 744   | $10     |
| IPv4 Hours Project 2          | 744   | $4      |
|                               |       |         |
| Compute Hours Micro Project 3 | 744   | $10     |
| IPv4 Hours Project 3          | 744   | $4      |
|                               |       |         |
| **Subtotal**                  |       | **$67** |
| Compute Credits               |       | -$10    |
| **Total**                     |       | **$57** |


### One project with Read Replicas

The project has two Read Replicas and the IPv4 add-on enabled throughout the entire billing cycle.

| Line Item                     | Hours | Costs   |
| ----------------------------- | ----- | ------- |
| Pro Plan                      | -     | $25     |
|                               |       |         |
| Compute Hours Small Project 1 | 744   | $15     |
| IPv4 Hours Project 1          | 744   | $4      |
|                               |       |         |
| Compute Hours Small Replica 1 | 744   | $15     |
| IPv4 Hours Replica 1          | 744   | $4      |
|                               |       |         |
| Compute Hours Small Replica 2 | 744   | $15     |
| IPv4 Hours Replica 2          | 744   | $4      |
|                               |       |         |
| **Subtotal**                  |       | **$82** |
| Compute Credits               |       | -$10    |
| **Total**                     |       | **$72** |


## Optimize usage

To see whether your database actually needs a dedicated IPv4 address, refer to [When you need the IPv4 add-on](/docs/guides/platform/ipv4-address#when-you-need-the-ipv4-add-on).


# Manage Log Drain usage



## What you are charged for

You can configure log drains in the [project settings](https://supabase.com/dashboard/project/_/settings/log-drains) to send logs to one or more destinations. You are charged for each log drain that is configured (referred to as [Log Drain Hours](/docs/guides/platform/manage-your-usage/log-drains#log-drain-hours)), the log events sent (referred to as [Log Drain Events](/docs/guides/platform/manage-your-usage/log-drains#log-drain-events)), and the [Egress](/docs/guides/platform/manage-your-usage/egress) incurred by the export—across all your projects.


## Log Drain Hours


### How charges are calculated

You are charged by the hour, meaning you are charged for the exact number of hours that a log drain is configured for a project. If a log drain is configured for part of an hour, you are still charged for the full hour.


#### Example

Your billing cycle runs from January 1 to January 31. On January 10 at 4:30 PM, you configure a log drain for your project. At the end of the billing cycle you are billed for 512 hours.

| Time Window                                 | Log Drain Configured | Hours Billed | Description         |
| ------------------------------------------- | -------------------- | ------------ | ------------------- |
| January 1, 00:00 AM - January 10, 4:00 PM   | No                   | 0            |                     |
| January 10, 04:00 PM - January 10, 4:30 PM  | No                   | 0            |                     |
| January 10, 04:30 PM - January 10, 5:00 PM  | Yes                  | 1            | full hour is billed |
| January 10, 05:00 PM - January 31, 23:59 PM | Yes                  | 511          |                     |


#### Usage on your invoice

Usage is shown as "Log Drain Hours" on your invoice.


### Pricing

Log Drains are available as a project Add-On for all Team and Enterprise users. Each Log Drain costs $0.0822 per hour ($60 per month).


## Log Drain Events


### How charges are calculated

Log Drain Events are billed using Package pricing, with each package representing 1 million events. If your usage falls between two packages, you are billed for the next whole package.


#### Example

| Events    | Packages Billed | Costs |
| --------- | --------------- | ----- |
| 999,999   | 1               | $0.2  |
| 1,000,000 | 1               | $0.2  |
| 1,000,001 | 2               | $0.4  |
| 1,500,000 | 2               | $0.4  |


#### Usage on your invoice

Usage is shown as "Log Drain Events" on your invoice.


### Pricing

$0.2 per 1 million events.


## Billing example

The project has two log drains configured throughout the entire billing cycle with 800,000 and 1.6 million events each. In this example we assume that the organization is exceeding its Unified Egress Quota, so charges for Egress apply.

| Line Item                     | Units              | Costs       |
| ----------------------------- | ------------------ | ----------- |
| Team Plan                     | 1                  | $599        |
|                               |                    |             |
| Compute Hours Micro Project 1 | 744 hours          | $10         |
|                               |                    |             |
| Log Drain Hours Drain 1       | 744 hours          | $60         |
| Log Drain Events Drain 1      | 800,000 events     | $0.2        |
| Egress Drain 1                | 2 GB               | $0.18       |
|                               |                    |             |
| Log Drain Hours Drain 2       | 744 hours          | $60         |
| Log Drain Events Drain 2      | 1.6 million events | $0.4        |
| Egress Drain 2                | 4 GB               | $0.36       |
|                               |                    |             |
| **Subtotal**                  |                    | **$730.14** |
| Compute Credits               |                    | -$10        |
| **Total**                     |                    | **$720.14** |


## View usage

You can view Log Drain Events usage on the [organization's usage page](https://supabase.com/dashboard/org/_/usage). The page shows the usage of all projects by default. To view the usage for a specific project, select it from the dropdown. You can also select a different time period.


# Manage Monthly Active SSO Users usage



## What you are charged for

You are charged for the number of distinct users who log in or refresh their token during the billing cycle using a SAML 2.0 compatible identity provider. Each unique user is counted only once per billing cycle, regardless of how many times they authenticate. These users are referred to as "SSO MAUs".


### Example

Your billing cycle runs from January 1 to January 31. Although User-1 was signed in multiple times, they are counted as a single SSO MAU for this billing cycle.


## How charges are calculated

You are charged by SSO MAU.


### Usage on your invoice

Usage is shown as "Monthly Active SSO Users" on your invoice.


## Pricing

| Plan       | Quota  | Over-Usage         |
| ---------- | ------ | ------------------ |
| Pro        | 50     | $0.015 per SSO MAU |
| Team       | 50     | $0.015 per SSO MAU |
| Enterprise | Custom | Custom             |


## Billing examples


### Within quota

The organization's SSO MAU usage for the billing cycle is within the quota, so no charges apply.

| Line Item                | Units      | Costs   |
| ------------------------ | ---------- | ------- |
| Pro Plan                 | 1          | $25     |
| Compute Hours Micro      | 744 hours  | $10     |
| Monthly Active SSO Users | 37 SSO MAU | $0      |
| **Subtotal**             |            | **$35** |
| Compute Credits          |            | -$10    |
| **Total**                |            | **$25** |


### Exceeding quota

The organization's SSO MAU usage for the billing cycle exceeds the quota by 10, incurring charges for this additional usage.

| Line Item                | Units      | Costs      |
| ------------------------ | ---------- | ---------- |
| Pro Plan                 | 1          | $25        |
| Compute Hours Micro      | 744 hours  | $10        |
| Monthly Active SSO Users | 60 SSO MAU | $0.15      |
| **Subtotal**             |            | **$35.15** |
| Compute Credits          |            | -$10       |
| **Total**                |            | **$25.15** |


## View usage

You can view Monthly Active SSO Users usage on the [organization's usage page](https://supabase.com/dashboard/org/_/usage). The page shows the usage of all projects by default. To view the usage for a specific project, select it from the dropdown. You can also select a different time period.

In the Monthly Active SSO Users section, you can see the usage for the selected time period.


# Manage Monthly Active Third-Party Users usage



## What you are charged for

You are charged for the number of distinct users who log in or refresh their token during the billing cycle using a third-party authentication provider. Each unique user is counted only once per billing cycle, regardless of how many times they authenticate. These users are referred to as "Third-Party MAUs".


### Example

Your billing cycle runs from January 1 to January 31. Although User-1 was signed in multiple times, they are counted as a single SSO MAU for this billing cycle.


## How charges are calculated

You are charged by Third-Party MAU.


### Usage on your invoice

Usage is shown as "Monthly Active Third-Party Users" on your invoice.


## Pricing

| Plan       | Quota   | Over-Usage                   |
| ---------- | ------- | ---------------------------- |
| Free       | 50,000  | -                            |
| Pro        | 100,000 | $0.00325 per Third-Party MAU |
| Team       | 100,000 | $0.00325 per Third-Party MAU |
| Enterprise | Custom  | Custom                       |


## Billing examples


### Within quota

The organization's Third-Party MAU usage for the billing cycle is within the quota, so no charges apply.

| Line Item                        | Units                  | Costs   |
| -------------------------------- | ---------------------- | ------- |
| Pro Plan                         | 1                      | $25     |
| Compute Hours Micro              | 744 hours              | $10     |
| Monthly Active Third-Party Users | 37,000 Third-Party MAU | $0      |
| **Subtotal**                     |                        | **$35** |
| Compute Credits                  |                        | -$10    |
| **Total**                        |                        | **$25** |


### Exceeding quota

The organization's Third-Party MAU usage for the billing cycle exceeds the quota by 4950, incurring charges for this additional usage.

| Line Item                        | Units                   | Costs       |
| -------------------------------- | ----------------------- | ----------- |
| Pro Plan                         | 1                       | $25         |
| Compute Hours Micro              | 744 hours               | $10         |
| Monthly Active Third-Party Users | 130,000 Third-Party MAU | $97.50      |
| **Subtotal**                     |                         | **$132.50** |
| Compute Credits                  |                         | -$10        |
| **Total**                        |                         | **$122.50** |


## View usage

You can view Monthly Active Third-Party Users usage on the [organization's usage page](https://supabase.com/dashboard/org/_/usage). The page shows the usage of all projects by default. To view the usage for a specific project, select it from the dropdown. You can also select a different time period.


# Manage Monthly Active Users usage



## What you are charged for

You are charged for the number of distinct users who log in or refresh their token during the billing cycle. Each unique user is counted only once per billing cycle, regardless of how many times they authenticate. These users are referred to as "MAUs".


### Example

Your billing cycle runs from January 1 to January 31. Although User-1 was signed in multiple times, they are counted as a single MAU for this billing cycle.


## How charges are calculated

You are charged by MAU.


### Usage on your invoice

Usage is shown as "Monthly Active Users" on your invoice.


## Pricing

| Plan       | Quota   | Over-Usage       |
| ---------- | ------- | ---------------- |
| Free       | 50,000  | -                |
| Pro        | 100,000 | $0.00325 per MAU |
| Team       | 100,000 | $0.00325 per MAU |
| Enterprise | Custom  | Custom           |


## Billing examples


### Within quota

The organization's MAU usage for the billing cycle is within the quota, so no charges apply.

| Line Item            | Units      | Costs   |
| -------------------- | ---------- | ------- |
| Pro Plan             | 1          | $25     |
| Compute Hours Micro  | 744 hours  | $10     |
| Monthly Active Users | 23,000 MAU | $0      |
| **Subtotal**         |            | **$35** |
| Compute Credits      |            | -$10    |
| **Total**            |            | **$25** |


### Exceeding quota

The organization's MAU usage for the billing cycle exceeds the quota by 60,000, incurring charges for this additional usage.

| Line Item            | Units       | Costs    |
| -------------------- | ----------- | -------- |
| Pro Plan             | 1           | $25      |
| Compute Hours Micro  | 744 hours   | $10      |
| Monthly Active Users | 160,000 MAU | $195     |
| **Subtotal**         |             | **$230** |
| Compute Credits      |             | -$10     |
| **Total**            |             | **$220** |


## View usage

You can view Monthly Active Users usage on the [organization's usage page](https://supabase.com/dashboard/org/_/usage). The page shows the usage of all projects by default. To view the usage for a specific project, select it from the dropdown. You can also select a different time period.

In the Monthly Active Users section, you can see the usage for the selected time period.


# Manage Point-in-Time Recovery usage



## What you are charged for

You can configure [Point-in-Time Recovery (PITR)](/docs/guides/platform/backups#point-in-time-recovery) for a project by enabling the [PITR add-on](https://supabase.com/dashboard/project/_/settings/addons?panel=pitr). You are charged for every enabled PITR add-on across your projects.


## How charges are calculated

PITR is charged by the hour, meaning you are charged for the exact number of hours that PITR is active for a project. If PITR is active for part of an hour, you are still charged for the full hour.


### Example

Your billing cycle runs from January 1 to January 31. On January 10 at 4:30 PM, you activate PITR for your project. At the end of the billing cycle you are billed for 512 hours.

| Time Window                                 | PITR Activated | Hours Billed | Description         |
| ------------------------------------------- | -------------- | ------------ | ------------------- |
| January 1, 00:00 AM - January 10, 4:00 PM   | No             | 0            |                     |
| January 10, 04:00 PM - January 10, 4:30 PM  | No             | 0            |                     |
| January 10, 04:30 PM - January 10, 5:00 PM  | Yes            | 1            | full hour is billed |
| January 10, 05:00 PM - January 31, 23:59 PM | Yes            | 511          |                     |


### Usage on your invoice

Usage is shown as "Point-in-time recovery Hours" on your invoice.


## Pricing


## Billing examples


### One project

The project has PITR with a recovery retention period of 7 days activated throughout the entire billing cycle.

| Line Item                     | Hours | Costs    |
| ----------------------------- | ----- | -------- |
| Pro Plan                      | -     | $25      |
| Compute Hours Small Project 1 | 744   | $15      |
| PITR Hours                    | 744   | $100     |
| **Subtotal**                  |       | **$140** |
| Compute Credits               |       | -$10     |
| **Total**                     |       | **$130** |


### Multiple projects

All projects have PITR with a recovery retention period of 14 days activated throughout the entire billing cycle.

| Line Item                     | Hours | Costs    |
| ----------------------------- | ----- | -------- |
| Pro Plan                      | -     | $25      |
|                               |       |          |
| Compute Hours Small Project 1 | 744   | $15      |
| PITR Hours Project 1          | 744   | $200     |
|                               |       |          |
| Compute Hours Small Project 2 | 744   | $15      |
| PITR Hours Project 2          | 744   | $200     |
|                               |       |          |
| **Subtotal**                  |       | **$455** |
| Compute Credits               |       | -$10     |
| **Total**                     |       | **$445** |


## Optimize usage

*   Review your [backup frequency](/docs/guides/platform/backups#frequency-of-backups) needs to determine whether you require PITR or free Daily Backups are sufficient
*   Regularly check your projects and disable PITR where no longer needed
*   Consider disabling PITR for non-production databases


# Manage Read Replica usage



## What you are charged for

Each [Read Replica](/docs/guides/platform/read-replicas) is a dedicated database. You are charged for its resources: [Compute](/docs/guides/platform/compute-and-disk#compute), [Disk Size](/docs/guides/platform/database-size#disk-size), provisioned [Disk IOPS](/docs/guides/platform/compute-and-disk#provisioned-disk-throughput-and-iops), provisioned [Disk Throughput](/docs/guides/platform/compute-and-disk#provisioned-disk-throughput-and-iops), and [IPv4](/docs/guides/platform/ipv4-address).


## How charges are calculated

Read Replica charges are the total of the charges listed below.

**Compute**
Compute is charged by the hour, meaning you are charged for the exact number of hours that a Read Replica is running and, therefore, incurring Compute usage. If a Read Replica runs for part of an hour, you are still charged for the full hour.

Read Replicas run on the same Compute size as the primary database.

**Disk Size**
Refer to [Manage Disk Size usage](/docs/guides/platform/manage-your-usage/disk-size) for details on how charges are calculated. The disk size of a Read Replica is 1.25x the size of the primary disk to account for WAL archives. With a Read Replica you go beyond your subscription plan's quota for Disk Size.

**Provisioned Disk IOPS (optional)**
Read Replicas inherit any additional provisioned Disk IOPS from the primary database. Refer to [Manage Disk IOPS usage](/docs/guides/platform/manage-your-usage/disk-iops) for details on how charges are calculated.

**Provisioned Disk Throughput (optional)**
Read Replicas inherit any additional provisioned Disk Throughput from the primary database. Refer to [Manage Disk Throughput usage](/docs/guides/platform/manage-your-usage/disk-throughput) for details on how charges are calculated.

**IPv4 (optional)**
If the primary database has a configured IPv4 address, its Read Replicas are also assigned one, with charges for each. Refer to [Manage IPv4 usage](/docs/guides/platform/manage-your-usage/ipv4) for details on how charges are calculated.


### Usage on your invoice

Compute incurred by Read Replicas is shown as "Replica Compute Hours" on your invoice. Disk Size, Disk IOPS, Disk Throughput and IPv4 are not shown separately for Read Replicas and are rolled up into the project.


## Billing examples


### No additional resources configured

The project has one Read Replica and no IPv4 and no additional Disk IOPS and Disk Throughput configured.

| Line Item                     | Units     | Costs      |
| ----------------------------- | --------- | ---------- |
| Pro Plan                      | 1         | $25        |
|                               |           |            |
| Compute Hours Small Project 1 | 744 hours | $15        |
| Disk Size Project 1           | 8 GB      | $0         |
|                               |           |            |
| Compute Hours Small Replica   | 744 hours | $15        |
| Disk Size Replica             | 10 GB     | $1.25      |
|                               |           |            |
| **Subtotal**                  |           | **$56.25** |
| Compute Credits               |           | -$10       |
| **Total**                     |           | **$46.25** |


### Additional resources configured

The project has two Read Replicas and IPv4 and additional Disk IOPS and Disk Throughput configured.

| Line Item                     | Units     | Costs       |
| ----------------------------- | --------- | ----------- |
| Pro Plan                      | 1         | $25         |
|                               |           |             |
| Compute Hours Large Project 1 | 744 hours | $110        |
| Disk Size Project 1           | 8 GB      | $0          |
| Disk IOPS Project 1           | 3600      | $14.40      |
| Disk Throughput Project 1     | 200 MB/s  | $7.13       |
| IPv4 Hours Project 1          | 744 hours | $4          |
|                               |           |             |
| Compute Hours Large Replica 1 | 744 hours | $110        |
| Disk Size Replica 1           | 10 GB     | $1.25       |
| Disk IOPS Replica 1           | 3600      | $14.40      |
| Disk Throughput Replica 1     | 200 MB/s  | $7.13       |
| IPv4 Hours Replica 1          | 744 hours | $4          |
|                               |           |             |
| Compute Hours Large Replica 2 | 744 hours | $110        |
| Disk Size Replica 2           | 10 GB     | $1.25       |
| Disk IOPS Replica 2           | 3600      | $14.40      |
| Disk Throughput Replica 2     | 200 MB/s  | $7.13       |
| IPv4 Hours Replica 2          | 744 hours | $4          |
|                               |           |             |
| **Subtotal**                  |           | **$434.09** |
| Compute Credits               |           | -$10        |
| **Total**                     |           | **$424.09** |


## FAQ


### Do Compute Credits apply to Read Replica Compute?

No, Compute Credits do not apply to Read Replica Compute.


# Manage Realtime Messages usage



## What you are charged for

You are charged for the number of messages going through Supabase Realtime throughout the billing cycle. Includes database changes, Broadcast and Presence.

**Database changes**
Each database change counts as one message per client that listens to the event. For example, if a database change occurs and 5 clients listen to that database event, it counts as 5 messages.

**Broadcast**
Each broadcast message counts as one message sent plus one message per subscribed client that receives it. For example, if you broadcast a message and 4 clients listen to it, it counts as 5 messages—1 sent and 4 received.


## How charges are calculated

Realtime Messages are billed using Package pricing, with each package representing 1 million messages. If your usage falls between two packages, you are billed for the next whole package.


### Example

For simplicity, let's assume a package size of 1,000,000 and a charge of $2.50 per package without quota.

| Messages  | Packages Billed | Costs |
| --------- | --------------- | ----- |
| 999,999   | 1               | $2.50 |
| 1,000,000 | 1               | $2.50 |
| 1,000,001 | 2               | $5.00 |
| 1,500,000 | 2               | $5.00 |


### Usage on your invoice

Usage is shown as "Realtime Messages" on your invoice.


## Pricing


## Billing examples


### Within quota

The organization's Realtime messages are within the quota, so no charges apply.

| Line Item           | Units                | Costs   |
| ------------------- | -------------------- | ------- |
| Pro Plan            | 1                    | $25     |
| Compute Hours Micro | 744 hours            | $10     |
| Realtime Messages   | 1.8 million messages | $0      |
| **Subtotal**        |                      | **$35** |
| Compute Credits     |                      | -$10    |
| **Total**           |                      | **$25** |


### Exceeding quota

The organization's Realtime messages exceed the quota by 3.5 million, incurring charges for this additional usage.

| Line Item           | Units                | Costs   |
| ------------------- | -------------------- | ------- |
| Pro Plan            | 1                    | $25     |
| Compute Hours Micro | 744 hours            | $10     |
| Realtime Messages   | 8.5 million messages | $10     |
| **Subtotal**        |                      | **$45** |
| Compute Credits     |                      | -$10    |
| **Total**           |                      | **$35** |


## View usage

You can view Realtime Messages usage on the [organization's usage page](https://supabase.com/dashboard/org/_/usage). The page shows the usage of all projects by default. To view the usage for a specific project, select it from the dropdown. You can also select a different time period.

In the Realtime Messages section, you can see the usage for the selected time period.


# Manage Realtime Peak Connections usage



## What you are charged for

Realtime Peak Connections are measured by tracking the highest number of concurrent connections for each project during the billing cycle. Regardless of fluctuations, only the peak count per project is used for billing, and the totals from all projects are summed. Only successful connections are counted, connection attempts are not included.


### Example

For simplicity, this example assumes a billing cycle of only three days.

| Project   | Peak Connections Day 1 | Peak Connections Day 2 | Peak Connections Day 3 |
| --------- | ---------------------- | ---------------------- | ---------------------- |
| Project A | 80                     | 100                    | 90                     |
| Project B | 120                    | 110                    | 150                    |

**Total billed connections:** 100 (Project A) + 150 (Project B) = **250 connections**


## How charges are calculated

Realtime Peak Connections are billed using Package pricing, with each package representing 1,000 peak connections. If your usage falls between two packages, you are billed for the next whole package.


### Example

For simplicity, let's assume a package size of 1,000 and a charge of $10 per package with no quota.

| Peak Connections | Packages Billed | Costs |
| ---------------- | --------------- | ----- |
| 999              | 1               | $10   |
| 1,000            | 1               | $10   |
| 1,001            | 2               | $20   |
| 1,500            | 2               | $20   |


### Usage on your invoice

Usage is shown as "Realtime Peak Connections" on your invoice.


## Pricing


## Billing examples


### Within quota

The organization's connections are within the quota, so no charges apply.

| Line Item                 | Units           | Costs   |
| ------------------------- | --------------- | ------- |
| Pro Plan                  | 1               | $25     |
| Compute Hours Micro       | 744 hours       | $10     |
| Realtime Peak Connections | 350 connections | $0      |
| **Subtotal**              |                 | **$35** |
| Compute Credits           |                 | -$10    |
| **Total**                 |                 | **$25** |


### Exceeding quota

The organization's connections exceed the quota by 1,200, incurring charges for this additional usage.

| Line Item                 | Units             | Costs   |
| ------------------------- | ----------------- | ------- |
| Pro Plan                  | 1                 | $25     |
| Compute Hours Micro       | 744 hours         | $10     |
| Realtime Peak Connections | 1,700 connections | $20     |
| **Subtotal**              |                   | **$45** |
| Compute Credits           |                   | -$10    |
| **Total**                 |                   | **$35** |


## View usage

You can view Realtime Peak Connections usage on the [organization's usage page](https://supabase.com/dashboard/org/_/usage). The page shows the usage of all projects by default. To view the usage for a specific project, select it from the dropdown. You can also select a different time period.

In the Realtime Peak Connections section, you can see the usage for the selected time period.


# Manage Storage Image Transformations usage



## What you are charged for

You are charged for the number of distinct images transformed during the billing period, regardless of how many transformations each image undergoes. We refer to these images as "origin" images.


### Example

With these four transformations applied to `image-1.jpg` and `image-2.jpg`, the origin images count is 2.

```javascript
supabase.storage.from('bucket').createSignedUrl('image-1.jpg', 60000, {
  transform: {
    width: 200,
    height: 200,
  },
})
```

```javascript
supabase.storage.from('bucket').createSignedUrl('image-2.jpg', 60000, {
  transform: {
    width: 400,
    height: 300,
  },
})
```

```javascript
supabase.storage.from('bucket').createSignedUrl('image-2.jpg', 60000, {
  transform: {
    width: 600,
    height: 250,
  },
})
```

```javascript
supabase.storage.from('bucket').download('image-2.jpg', {
  transform: {
    width: 800,
    height: 300,
  },
})
```


## How charges are calculated

Storage Image Transformations are billed using Package pricing, with each package representing 1000 origin images. If your usage falls between two packages, you are billed for the next whole package.


### Example

For simplicity, let's assume a package size of 1,000 and a charge of $5 per package with no quota.

| Origin Images | Packages Billed | Costs |
| ------------- | --------------- | ----- |
| 999           | 1               | $5    |
| 1,000         | 1               | $5    |
| 1,001         | 2               | $10   |
| 1,500         | 2               | $10   |


### Usage on your invoice

Usage is shown as "Storage Image Transformations" on your invoice.


## Pricing


## Billing examples


### Within quota

The organization's number of origin images for the billing cycle is within the quota, so no charges apply.

| Line Item             | Units            | Costs   |
| --------------------- | ---------------- | ------- |
| Pro Plan              | 1                | $25     |
| Compute Hours Micro   | 744 hours        | $10     |
| Image Transformations | 74 origin images | $0      |
| **Subtotal**          |                  | **$35** |
| Compute Credits       |                  | -$10    |
| **Total**             |                  | **$25** |


### Exceeding quota

The organization's number of origin images for the billing cycle exceeds the quota by 750, incurring charges for this additional usage.

| Line Item             | Units             | Costs   |
| --------------------- | ----------------- | ------- |
| Pro Plan              | 1                 | $25     |
| Compute Hours Micro   | 744 hours         | $10     |
| Image Transformations | 850 origin images | $5      |
| **Subtotal**          |                   | **$40** |
| Compute Credits       |                   | -$10    |
| **Total**             |                   | **$30** |


## View usage

You can view Storage Image Transformations usage on the [organization's usage page](https://supabase.com/dashboard/org/_/usage). The page shows the usage of all projects by default. To view the usage for a specific project, select it from the dropdown. You can also select a different time period.

In the Storage Image Transformations section, you can see how many origin images were transformed during the selected time period.


## Optimize usage

*   Pre-generate common variants – instead of transforming images on the fly, generate and store commonly used sizes in advance
*   Optimize original image sizes – upload images in an optimized format and resolution to reduce the need for excessive transformations
*   Leverage [Smart CDN](/docs/guides/storage/cdn/smart-cdn) caching or any other caching solution to serve transformed images efficiently and avoid unnecessary repeated transformations
*   Control how long assets are stored in the browser using the `Cache-Control` header


# Manage Storage size usage



## What you are charged for

You are charged for the total size of all assets in your buckets.


## How charges are calculated

Storage size is charged by Gigabyte-Hours (GB-Hrs). 1 GB-Hr represents the use of 1 GB of storage for 1 hour.
For example, storing 10 GB of data for 5 hours results in 50 GB-Hrs (10 GB × 5 hours).


### Usage on your invoice

Usage is shown as "Storage Size GB-Hrs" on your invoice.


## Pricing


## Billing examples


### Within quota

The organization's Storage size usage is within the quota, so no charges for Storage size apply.

| Line Item           | Units     | Costs   |
| ------------------- | --------- | ------- |
| Pro Plan            | 1         | $25     |
| Compute Hours Micro | 744 hours | $10     |
| Storage Size        | 85 GB     | $0      |
| **Subtotal**        |           | **$35** |
| Compute Credits     |           | -$10    |
| **Total**           |           | **$25** |


### Exceeding quota

The organization's Storage size usage exceeds the quota by 257 GB, incurring charges for this additional usage.

| Line Item           | Units     | Costs     |
| ------------------- | --------- | --------- |
| Pro Plan            | 1         | $25       |
| Compute Hours Micro | 744 hours | $10       |
| Storage Size        | 357 GB    | $5.4      |
| **Subtotal**        |           | **$40.4** |
| Compute Credits     |           | -$10      |
| **Total**           |           | **$30.4** |


## View usage


### Usage page

You can view Storage size usage on the [organization's usage page](https://supabase.com/dashboard/org/_/usage). The page shows the usage of all projects by default. To view the usage for a specific project, select it from the dropdown. You can also select a different time period.

In the Storage size section, you can see how much storage your projects have used during the selected time period.


### SQL Editor

Since we designed Storage to work as an integrated part of your Postgres database on Supabase, you can query information about your Storage objects in the `storage` schema.

List files larger than 5 MB:

```sql
select
    name,
    bucket_id as bucket,
    case
        when (metadata->>'size')::int >= 1073741824 then
            ((metadata->>'size')::int / 1073741824.0)::numeric(10, 2) || ' GB'
        when (metadata->>'size')::int >= 1048576 then
            ((metadata->>'size')::int / 1048576.0)::numeric(10, 2) || ' MB'
        when (metadata->>'size')::int >= 1024 then
            ((metadata->>'size')::int / 1024.0)::numeric(10, 2) || ' KB'
        else
            (metadata->>'size')::int || ' bytes'
        end as size
from
    storage.objects
where
    (metadata->>'size')::int > 1048576 * 5
order by (metadata->>'size')::int desc
```

List buckets with their total size:

```sql
select
    bucket_id,
    (sum((metadata->>'size')::int) / 1048576.0)::numeric(10, 2) as total_size_megabyte
from
    storage.objects
group by
    bucket_id
order by
    total_size_megabyte desc;
```


## Optimize usage

*   [Limit the upload size](/docs/guides/storage/production/scaling#limit-the-upload-size) for your buckets
*   [Delete assets](/docs/guides/storage/management/delete-objects) that are no longer in use


# Migrating to Supabase



Learn how to migrate to Supabase from another database service.


## Migration guides


# Migrate from Amazon RDS to Supabase

Migrate your Amazon RDS MySQL or MS SQL database to Supabase.

This guide aims to exhibit the process of transferring your Amazon RDS database from any of these engines Postgres, MySQL or MS SQL to Supabase's Postgres database. Although Amazon RDS is a favored managed database service provided by AWS, it may not suffice for all use cases. Supabase, on the other hand, provides an excellent free and open source option that encompasses all the necessary backend features to develop a product: a Postgres database, authentication, instant APIs, edge functions, real-time subscriptions, and storage.

Supabase's core is Postgres, enabling the use of row-level security and providing access to over 40 Postgres extensions. By migrating from Amazon RDS to Supabase, you can leverage Postgres to its fullest potential and acquire all the features you need to complete your project.


## Retrieve your Amazon RDS database credentials \[#retrieve-rds-credentials]

1.  Log in to your [Amazon RDS account](https://aws.amazon.com/rds/).
2.  Select the region where your RDS database is located.
3.  Navigate to the **Databases** tab.
4.  Select the database that you want to migrate.
5.  In the **Connectivity & Security** tab, note down the Endpoint and the port number.
6.  In the **Configuration** tab, note down the Database name and the Username.
7.  If you do not have the password, create a new one and note it down.

![Copying RDS credentials from AWS Management Console](/docs/img/guides/resources/migrating-to-supabase/amazon-rds/amazon-rds_credentials.png)


## Retrieve your Supabase host \[#retrieve-supabase-host]

1.  If you're new to Supabase, [create a project](https://database.new). Make a note of your password, you will need this later. If you forget it, you can [reset it here](https://supabase.com/dashboard/project/_/settings/database).
2.  Go to the [Database settings](https://supabase.com/dashboard/project/_/settings/database) for your project in the Supabase Dashboard.
3.  Under **Connection Info**, note your Host (`$SUPABASE_HOST`).

![Finding Supabase host address](/docs/img/guides/resources/migrating-to-supabase/amazon-rds/database-settings-host.png)


## Migrate the database

The fastest way to migrate your database is with the Supabase migration tool on
[Google Colab](https://colab.research.google.com/github/mansueli/Supa-Migrate/blob/main/Amazon_RDS_to_Supabase.ipynb).

Alternatively, you can use [pgloader](https://github.com/dimitri/pgloader), a flexible and powerful data migration tool that supports a wide range of source database engines, including MySQL and MS SQL, and migrates the data to a Postgres database. For databases using the Postgres engine, we recommend using the [`pg_dump`](https://www.postgresql.org/docs/current/app-pgdump.html) and [psql](https://www.postgresql.org/docs/current/app-psql.html) command line tools, which are included in a full Postgres installation.


## Enterprise

[Contact us](https://forms.supabase.com/enterprise) if you need more help migrating your project.


# Migrate from Auth0 to Supabase Auth

Learn how to migrate your users from Auth0

You can migrate your users from Auth0 to Supabase Auth.

Changing authentication providers for a production app is an important operation. It can affect most aspects of your application. Prepare in advance by reading this guide, and develop a plan for handling the key migration steps and possible problems.

With advance planning, a smooth and safe Auth migration is possible.


## Before you begin

Before beginning, consider the answers to the following questions. They will help you need decide if you need to migrate, and which strategy to use:

*   How do Auth provider costs scale as your user base grows?
*   Does the new Auth provider provide all needed features? (for example, OAuth, password logins, Security Assertion Markup Language (SAML), Multi-Factor Authentication (MFA))
*   Is downtime acceptable during the migration?
*   What is your timeline to migrate before terminating the old Auth provider?


## Migration strategies

Depending on your evaluation, you may choose to go with one of the following strategies:

1.  Rolling migration
2.  One-off migration

| Strategy | Advantages                                                                                     | Disadvantages                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| -------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Rolling  |                             |  |
| One-off  |  |                                                                                                                                                                                                                                                                                                                                                      |


## Migration steps

Auth provider migrations require 2 main steps:

1.  Export your user data from the old provider (Auth0)
2.  Import the data into your new provider (Supabase Auth)


### Step 1: Export your user data

Auth0 provides two methods for exporting user data:

1.  Use the [Auth0 data export feature](https://auth0.com/docs/troubleshoot/customer-support/manage-subscriptions/export-data)
2.  Use the [Auth0 management API](https://auth0.com/docs/api/management/v2/users/get-users). This endpoint has a rate limit, so you may need to export your users in several batches.

To export password hashes and MFA factors, contact Auth0 support.


### Step 2: Import your users into Supabase Auth

The steps for importing your users depends on the login methods that you support.

See the following sections for how to import users with:

*   [Password-based login](#password-based-methods)
*   [Passwordless login](#passwordless-methods)
*   [OAuth](#oauth)


#### Password-based methods

For users who sign in with passwords, we recommend a hybrid approach to reduce downtime:

1.  For new users, use Supabase Auth for sign up.
2.  Migrate existing users in a one-off migration.


##### Sign up new users

Sign up new users using Supabase Auth's [signin methods](/docs/guides/auth/passwords#signing-up-with-an-email-and-password).


##### Migrate existing users to Supabase Auth

Migrate existing users to Supabase Auth. This requires two main steps: first, check which users need to be migrated, then create their accounts using the Supabase admin endpoints.

1.  Get your Auth 0 user export and password hash export lists.

2.  Filter for users who use password login.
    *   Under the `identities` field in the user object, these users will have `auth0` as a provider. In the same identity object, you can find their Auth0 `user_id`.
    *   Check that the user has a corresponding password hash by comparing their Auth0 `user_id` to the `oid` field in the password hash export.

3.  Use Supabase Auth's [admin create user](/docs/reference/javascript/auth-admin-createuser) method to recreate the user in Supabase Auth. If the user has a confirmed email address or phone number, set `email_confirm` or `phone_confirm` to `true`.

    ```ts
    import { createClient } from '@supabase/supabase-js'
    const supabase = createClient('your_project_url', 'your_supabase_api_key')

    // ---cut---
    const { data, error } = await supabase.auth.admin.createUser({
      email: 'valid.email@supabase.io',
      password_hash: '$2y$10$a9pghn27d7m0ltXvlX8LiOowy7XfFw0hW0G80OjKYQ1jaoejaA7NC',
      email_confirm: true,
    })
    ```

    If you have a plaintext password instead of a hash, you can provide that instead. Supabase Auth will handle hashing the password for you. (Passwords are **always** stored hashed.)

    ```ts
    import { createClient } from '@supabase/supabase-js'
    const supabase = createClient('your_project_url', 'your_supabase_api_key')

    // ---cut---
    const { data, error } = await supabase.auth.admin.createUser({
      email: 'valid.email@supabase.io',
      password: 'supersecurepassword123!',
    })
    ```

4.  To sign in your migrated users, use the Supabase Auth [sign in methods](/docs/reference/javascript/auth-signinwithpassword).

    To check for edge cases where users aren't successfully migrated, use a fallback strategy. This ensures that users can continue to sign in seamlessly:

    1.  Try to sign in the user with Supabase Auth.
    2.  If the signin fails, try to sign in with Auth0.
    3.  If Auth0 signin succeeds, call the admin create user method again to create the user in Supabase Auth.


#### Passwordless methods

For passwordless signin via email or phone, check for users with verified email addresses or phone numbers. Create these users in Supabase Auth with `email_confirm` or `phone_confirm` set to `true`:

```ts
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('your_project_url', 'your_supabase_api_key')

// ---cut---
const { data, error } = await supabase.auth.admin.createUser({
  email: 'valid.email@supabase.io',
  email_confirm: true,
})
```

Check your Supabase Auth [email configuration](/docs/guides/auth/auth-smtp) and configure your [email template](/dashboard/project/_/auth/templates) for use with magic links. See the [Email templates guide](/docs/guides/auth/auth-email-templates) to learn more.

Once you have imported your users, you can sign them in using the [`signInWithOtp`](/docs/reference/javascript/auth-signinwithotp) method.


#### OAuth

Configure your OAuth providers in Supabase by following the [Social login guides](/docs/guides/auth/social-login).

For both new and existing users, sign in the user using the [`signInWithOAuth`](https://supabase.com/docs/reference/javascript/auth-signinwithoauth) method. This works without pre-migrating existing users, since the user always needs to sign in through the OAuth provider before being redirected to your service.

After the user has completed the OAuth flow successfully, you can check if the user is a new or existing user in Auth0 by mapping their social provider id to Auth0. Auth0 stores the social provider ID in the user ID, which has the format `provider_name|provider_id` (for example, `github|123456`). See the [Auth0 identity docs](https://auth0.com/docs/manage-users/user-accounts/identify-users) to learn more.


## Mapping between Auth0 and Supabase Auth

Each Auth provider has its own schema for tracking users and user information.

In Supabase Auth, your users are stored in your project's database under the `auth` schema. Every user has an identity (unless the user is an anonymous user), which represents the signin method they can use with Supabase. This is represented by the `auth.users` and `auth.identities` table.

See the [Users](/docs/guides/auth/users) and [Identities](/docs/guides/auth/identities) sections to learn more.


### Mapping user metadata and custom claims

Supabase Auth provides 2 fields which you can use to map user-specific metadata from Auth0:

*   `auth.users.raw_user_meta_data` : For storing non-sensitive user metadata that the user can update (e.g full name, age, favorite color).
*   `auth.users.raw_app_meta_data` : For storing non-sensitive user metadata that the user should not be able to update (e.g pricing plan, access control roles).

Both columns are accessible from the admin user methods. To create a user with custom metadata, you can use the following method:

```ts
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('your_project_url', 'your_supabase_api_key')

// ---cut---
const { data, error } = await supabase.auth.admin.createUser({
  email: 'valid.email@supabase.io',
  user_metadata: {
    full_name: 'Foo Bar',
  },
  app_metadata: {
    role: 'admin',
  },
})
```

These fields are stored as columns in the `auth.users` table using the `jsonb` type. Both fields can be updated by using the admin [`updateUserById` method](/docs/reference/javascript/auth-admin-updateuserbyid). If you want to allow the user to update their own `raw_user_meta_data` , you can use the [`updateUser` method](/docs/reference/javascript/auth-updateuser).

If you have a lot of user-specific metadata to store, it is recommended to create your own table in a private schema that uses the user id as a foreign key:

```sql
create table private.user_metadata (
	id int generated always as identity,
	user_id uuid references auth.users(id) on delete cascade,
	user_metadata jsonb
);
```


## Frequently Asked Questions (FAQ)


## Useful references

*   [Migrating 125k users from Auth0 to Supabase](https://kevcodez.medium.com/migrating-125-000-users-from-auth0-to-supabase-81c0568de307)
*   [Loper to Supabase migration](https://eigen.sh/posts/auth-migration)


# Migrate from Firebase Auth to Supabase

Migrate Firebase auth users to Supabase Auth.

Supabase provides several [tools](https://github.com/supabase-community/firebase-to-supabase/tree/main/auth) to help migrate auth users from a Firebase project to a Supabase project. There are two parts to the migration process:

*   `firestoreusers2json` ([TypeScript](https://github.com/supabase-community/firebase-to-supabase/blob/main/auth/firestoreusers2json.ts), [JavaScript](https://github.com/supabase-community/firebase-to-supabase/blob/main/auth/firestoreusers2json.js)) exports users from an existing Firebase project to a `.json` file on your local system.
*   `import_users` ([TypeScript](https://github.com/supabase-community/firebase-to-supabase/blob/main/auth/import_users.ts), [JavaScript](https://github.com/supabase-community/firebase-to-supabase/blob/main/auth/import_users.js)) imports users from a saved `.json` file into your Supabase project (inserting those users into the `auth.users` table of your `Postgres` database instance).


## Set up the migration tool \[#set-up-migration-tool]

1.  Clone the [`firebase-to-supabase`](https://github.com/supabase-community/firebase-to-supabase) repository:

    ```bash
    git clone https://github.com/supabase-community/firebase-to-supabase.git
    ```

2.  In the `/auth` directory, create a file named `supabase-service.json` with the following contents:

    ```json
    {
      "host": "database.server.com",
      "password": "secretpassword",
      "user": "postgres",
      "database": "postgres",
      "port": 5432
    }
    ```

3.  Go to the [Database settings](https://supabase.com/dashboard/project/_/settings/database) for your project in the Supabase Dashboard.

4.  Under `Connection parameters`, enable `Use connection pooling` and set the mode to `Session`. Replace the `Host` and `User` fields with the values shown.

5.  Enter the password you used when you created your Supabase project in the `password` entry in the `supabase-service.json` file.


## Generate a Firebase private key \[#generate-firebase-private-key]

1.  Log in to your [Firebase Console](https://console.firebase.google.com/project) and open your project.
2.  Click the gear icon next to **Project Overview** in the sidebar and select **Project Settings**.
3.  Click **Service Accounts** and select **Firebase Admin SDK**.
4.  Click **Generate new private key**.
5.  Rename the downloaded file to `firebase-service.json`.


## Save your Firebase password hash parameters \[#save-firebase-hash-parameters]

1.  Log in to your [Firebase Console](https://console.firebase.google.com/project) and open your project.
2.  Select **Authentication** (Build section) in the sidebar.
3.  Select **Users** in the top menu.
4.  At the top right of the users list, open the menu (3 dots) and click **Password hash parameters**.
5.  Copy and save the parameters for `base64_signer_key`, `base64_salt_separator`, `rounds`, and `mem_cost`.

```text Sample
hash_config {
  algorithm: SCRYPT,
  base64_signer_key: XXXX/XXX+XXXXXXXXXXXXXXXXX+XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX==,
  base64_salt_separator: Aa==,
  rounds: 8,
  mem_cost: 14,
}
```


## Command line options


### Dump Firestore users to a JSON file \[#dump-firestore-users]

`node firestoreusers2json.js [<filename.json>] [<batch_size>]`

*   `filename.json`: (optional) output filename (defaults to `./users.json`)
*   `batchSize`: (optional) number of users to fetch in each batch (defaults to 100)


### Import JSON users file to Supabase Auth (Postgres: `auth.users`) \[#import-json-users-file]

`node import_users.js <path_to_json_file> [<batch_size>]`

*   `path_to_json_file`: full local path and filename of JSON input file (of users)
*   `batch_size`: (optional) number of users to process in a batch (defaults to 100)


## Notes

For more advanced migrations, including the use of a middleware server component for verifying a user's existing Firebase password and updating that password in your Supabase project the first time a user logs in, see the [`firebase-to-supabase` repo](https://github.com/supabase-community/firebase-to-supabase/tree/main/auth).


## Resources

*   [Supabase vs Firebase](https://supabase.com/alternatives/supabase-vs-firebase)
*   [Firestore Data Migration](/docs/guides/migrations/firestore-data)
*   [Firestore Storage Migration](/docs/guides/migrations/firebase-storage)


## Enterprise

[Contact us](https://forms.supabase.com/enterprise) if you need more help migrating your project.


# Migrated from Firebase Storage to Supabase

Migrate Firebase Storage files to Supabase Storage.

Supabase provides several [tools](https://github.com/supabase-community/firebase-to-supabase/tree/main/storage) to convert storage files from Firebase Storage to Supabase Storage. Conversion is a two-step process:

1.  Files are downloaded from a Firebase storage bucket to a local filesystem.
2.  Files are uploaded from the local filesystem to a Supabase storage bucket.


## Set up the migration tool \[#set-up-migration-tool]

1.  Clone the [`firebase-to-supabase`](https://github.com/supabase-community/firebase-to-supabase) repository:

    ```bash
    git clone https://github.com/supabase-community/firebase-to-supabase.git
    ```

2.  In the `/storage` directory, rename [supabase-keys-sample.js](https://github.com/supabase-community/firebase-to-supabase/blob/main/storage/supabase-keys-sample.js) to `supabase-keys.js`.

3.  Go to your Supabase project's [API settings](https://supabase.com/dashboard/project/_/settings/api) in the Dashboard.

4.  Copy the **Project URL** and update the `SUPABASE_URL` value in `supabase-keys.js`.

5.  Under **Project API keys**, copy the **service\_role** key and update the `SUPABASE_KEY` value in `supabase-keys.js`.


## Generate a Firebase private key \[#generate-firebase-private-key]

1.  Log in to your [Firebase Console](https://console.firebase.google.com/project) and open your project.
2.  Click the gear icon next to **Project Overview** in the sidebar and select **Project Settings**.
3.  Click **Service Accounts** and select **Firebase Admin SDK**.
4.  Click **Generate new private key**.
5.  Rename the downloaded file to `firebase-service.json`.


## Command line options


### Download Firestore Storage bucket to a local filesystem folder \[#download-firestore-storage-bucket]

`node download.js <prefix> [<folder>] [<batchSize>] [<limit>] [<token>]`

*   `<prefix>`: The prefix of the files to download. To process the root bucket, use an empty prefix: "".
*   `<folder>`: (optional) Name of subfolder for downloaded files. The selected folder is created as a subfolder of the current folder (e.g., `./downloads/`). The default is `downloads`.
*   `<batchSize>`: (optional) The default is 100.
*   `<limit>`: (optional) Stop after processing this many files. For no limit, use `0`.
*   `<token>`: (optional) Begin processing at this `pageToken`.

To process in batches using multiple command-line executions, you must use the same parameters with a new `<token>` on subsequent calls. Use the token displayed on the last call to continue the process at a given point.


### Upload files to Supabase Storage bucket \[#upload-to-supabase-storage-bucket]

`node upload.js <prefix> <folder> <bucket>`

*   `<prefix>`: The prefix of the files to download. To process all files, use an empty prefix: "".
*   `<folder>`: Name of subfolder of files to upload. The selected folder is read as a subfolder of the current folder (e.g., `./downloads/`). The default is `downloads`.
*   `<bucket>`: Name of the bucket to upload to.


## Resources

*   [Supabase vs Firebase](https://supabase.com/alternatives/supabase-vs-firebase)
*   [Firestore Data Migration](/docs/guides/migrations/firestore-data)
*   [Firebase Auth Migration](/docs/guides/migrations/firebase-auth)


## Enterprise

[Contact us](https://forms.supabase.com/enterprise) if you need more help migrating your project.


# Migrated from Firebase Firestore to Supabase

Migrate your Firebase Firestore database to a Supabase Postgres database.

Supabase provides several [tools](https://github.com/supabase-community/firebase-to-supabase/tree/main/firestore) to convert data from a Firebase Firestore database to a Supabase Postgres database. The process copies the entire contents of a single Firestore `collection` to a single Postgres `table`.

The Firestore `collection` is "flattened" and converted to a table with basic columns of one of the following types: `text`, `numeric`, `boolean`, or `jsonb`. If your structure is more complex, you can write a program to split the newly-created `json` file into multiple, related tables before you import your `json` file(s) to Supabase.


## Set up the migration tool \[#set-up-migration-tool]

1.  Clone the [`firebase-to-supabase`](https://github.com/supabase-community/firebase-to-supabase) repository:

    ```bash
    git clone https://github.com/supabase-community/firebase-to-supabase.git
    ```

2.  In the `/firestore` directory, create a file named `supabase-service.json` with the following contents:

    ```json
    {
      "host": "database.server.com",
      "password": "secretpassword",
      "user": "postgres",
      "database": "postgres",
      "port": 5432
    }
    ```

3.  Go to the [Database settings](https://supabase.com/dashboard/project/_/settings/database) for your project in the Supabase Dashboard.

4.  Under `Connection parameters`, enable `Use connection pooling` and set the mode to `Session`. Replace the `Host` and `User` fields with the values shown.

5.  Enter the password you used when you created your Supabase project in the `password` entry in the `supabase-service.json` file.


## Generate a Firebase private key \[#generate-firebase-private-key]

1.  Log in to your [Firebase Console](https://console.firebase.google.com/project) and open your project.
2.  Click the gear icon next to **Project Overview** in the sidebar and select **Project Settings**.
3.  Click **Service Accounts** and select **Firebase Admin SDK**.
4.  Click **Generate new private key**.
5.  Rename the downloaded file to `firebase-service.json`.


## Command line options


### List all Firestore collections

`node collections.js`


### Dump Firestore collection to JSON file

`node firestore2json.js <collectionName> [<batchSize>] [<limit>]`

*   `batchSize` (optional) defaults to 1000
*   output filename is `<collectionName>.json`
*   `limit` (optional) defaults to 0 (no limit)


#### Customize the JSON file with hooks

You can customize the way your JSON file is written using a [custom hook](#custom-hooks). A common use for this is to "flatten" the JSON file, or to split nested data into separate, related database tables. For example, you could take a Firestore document that looks like this:

```json Firestore
[{ "user": "mark", "score": 100, "items": ["hammer", "nail", "glue"] }]
```

And split it into two files (one table for users and one table for items):

```json Users
[{ "user": "mark", "score": 100 }]
```

```json Items
[
  { "user": "mark", "item": "hammer" },
  { "user": "mark", "item": "nail" },
  { "user": "mark", "item": "glue" }
]
```


### Import JSON file to Supabase (Postgres) \[#import-to-supabase]

`node json2supabase.js <path_to_json_file> [<primary_key_strategy>] [<primary_key_name>]`

*   `<path_to_json_file>` The full path of the file you created in the previous step (`Dump Firestore collection to JSON file `), such as `./my_collection.json`
*   `[<primary_key_strategy>]` (optional) Is one of:
    *   `none` (default) No primary key is added to the table.
    *   `smallserial` Creates a key using `(id SMALLSERIAL PRIMARY KEY)` (autoincrementing 2-byte integer).
    *   `serial` Creates a key using `(id SERIAL PRIMARY KEY)` (autoincrementing 4-byte integer).
    *   `bigserial` Creates a key using `(id BIGSERIAL PRIMARY KEY)` (autoincrementing 8-byte integer).
    *   `uuid` Creates a key using `(id UUID PRIMARY KEY DEFAULT gen_random_uuid())` (randomly generated UUID).
    *   `firestore_id` Creates a key using `(id TEXT PRIMARY KEY)` (uses existing `firestore_id` random text as key).
*   `[<primary_key_name>]` (optional) Name of primary key. Defaults to "id".


## Custom hooks

Hooks are used to customize the process of exporting a collection of Firestore documents to JSON. They can be used for:

*   Customizing or modifying keys
*   Calculating data
*   Flattening nested documents into related SQL tables


### Write a custom hook


#### Create a `.js` file for your collection

If your Firestore collection is called `users`, create a file called `users.js` in the current folder.


#### Construct your `.js` file

The basic format of a hook file looks like this:

```js
module.exports = (collectionName, doc, recordCounters, writeRecord) => {
  // modify the doc here
  return doc
}
```


##### Parameters

*   `collectionName`: The name of the collection you are processing.
*   `doc`: The current document (JSON object) being processed.
*   `recordCounters`: An internal object that keeps track of how many records have been processed in each collection.
*   `writeRecord`: This function automatically handles the process of writing data to other JSON files (useful for "flatting" your document into separate JSON files to be written to separate database tables). `writeRecord` takes the following parameters:
    *   `name`: Name of the JSON file to write to.
    *   `doc`: The document to write to the file.
    *   `recordCounters`: The same `recordCounters` object that was passed to this hook (just passes it on).


### Examples


#### Add a new (unique) numeric key to a collection

```js
module.exports = (collectionName, doc, recordCounters, writeRecord) => {
  doc.unique_key = recordCounter[collectionName] + 1
  return doc
}
```


#### Add a timestamp of when this record was dumped from Firestore

```js
module.exports = (collectionName, doc, recordCounters, writeRecord) => {
  doc.dump_time = new Date().toISOString()
  return doc
}
```


#### Flatten JSON into separate files

Flatten the `users` collection into separate files:

```json
[
  {
    "uid": "abc123",
    "name": "mark",
    "score": 100,
    "weapons": ["toothpick", "needle", "rock"]
  },
  {
    "uid": "xyz789",
    "name": "chuck",
    "score": 9999999,
    "weapons": ["hand", "foot", "head"]
  }
]
```

The `users.js` hook file:

```js
module.exports = (collectionName, doc, recordCounters, writeRecord) => {
  for (let i = 0; i < doc.weapons.length; i++) {
    const weapon = {
      uid: doc.uid,
      weapon: doc.weapons[i],
    }
    writeRecord('weapons', weapon, recordCounters)
  }
  delete doc.weapons // moved to separate file
  return doc
}
```

The result is two separate JSON files:

```json users.json
[
  { "uid": "abc123", "name": "mark", "score": 100 },
  { "uid": "xyz789", "name": "chuck", "score": 9999999 }
]
```

```json weapons.json
[
  { "uid": "abc123", "weapon": "toothpick" },
  { "uid": "abc123", "weapon": "needle" },
  { "uid": "abc123", "weapon": "rock" },
  { "uid": "xyz789", "weapon": "hand" },
  { "uid": "xyz789", "weapon": "foot" },
  { "uid": "xyz789", "weapon": "head" }
]
```


## Resources

*   [Supabase vs Firebase](https://supabase.com/alternatives/supabase-vs-firebase)
*   [Firestore Storage Migration](/docs/guides/migrations/firebase-storage)
*   [Firebase Auth Migration](/docs/guides/migrations/firebase-auth)


## Enterprise

[Contact us](https://forms.supabase.com/enterprise) if you need more help migrating your project.


# Migrate from Heroku to Supabase

Migrate your Heroku Postgres database to Supabase.

Supabase is one of the best [free alternatives to Heroku Postgres](https://supabase.com/alternatives/supabase-vs-heroku-postgres). This guide shows how to migrate your Heroku Postgres database to Supabase. This migration requires the [pg\_dump](https://www.postgresql.org/docs/current/app-pgdump.html) and [psql](https://www.postgresql.org/docs/current/app-psql.html) CLI tools, which are installed automatically as part of the complete Postgres installation package.

Alternatively, use the [Heroku to Supabase migration tool](https://migrate.supabase.com/) to migrate in just a few clicks.


## Quick demo


## Retrieve your Heroku database credentials \[#retrieve-heroku-credentials]

1.  Log in to your [Heroku account](https://heroku.com) and select the project you want to migrate.
2.  Click **Resources** in the menu and select your **Heroku Postgres** database.
3.  Click **Settings** in the menu.
4.  Click **View Credentials** and save the following information:
    *   Host (`$HEROKU_HOST`)
    *   Database (`$HEROKU_DATABASE`)
    *   User (`$HEROKU_USER`)
    *   Password (`$HEROKU_PASSWORD`)


## Retrieve your Supabase connection string \[#retrieve-supabase-connection-string]

1.  If you're new to Supabase, [create a project](https://supabase.com/dashboard).
2.  Go to the [Database settings](https://supabase.com/dashboard/project/_/settings/database) for your project in the Supabase Dashboard.
3.  Under **Connection string**, make sure `Use connection pooling` is enabled. Copy the URI and replace the password placeholder with your database password.


## Export your Heroku database to a file \[#export-heroku-database]

Use `pg_dump` with your Heroku credentials to export your Heroku database to a file (e.g., `heroku_dump.sql`).

```bash
pg_dump --clean --if-exists --quote-all-identifiers \
 -h $HEROKU_HOST -U $HEROKU_USER -d $HEROKU_DATABASE \
 --no-owner --no-privileges > heroku_dump.sql
```


## Import the database to your Supabase project \[#import-database-to-supabase]

Use `psql` to import the Heroku database file to your Supabase project.

```bash
psql -d "$YOUR_CONNECTION_STRING" -f heroku_dump.sql
```


## Additional options

*   To only migrate a single database schema, add the `--schema=PATTERN` parameter to your `pg_dump` command.
*   To exclude a schema: `--exclude-schema=PATTERN`.
*   To only migrate a single table: `--table=PATTERN`.
*   To exclude a table: `--exclude-table=PATTERN`.

Run `pg_dump --help` for a full list of options.


## Enterprise

[Contact us](https://forms.supabase.com/enterprise) if you need more help migrating your project.


# Migrate from MSSQL to Supabase

Migrate your Microsoft SQL Server database to Supabase.

This guide aims to demonstrate the process of transferring your Microsoft SQL Server database to Supabase's Postgres database. Supabase is a powerful and open-source platform offering a wide range of backend features, including a Postgres database, authentication, instant APIs, edge functions, real-time subscriptions, and storage. Migrating your MSSQL database to Supabase's Postgres enables you to leverage Postgres's capabilities and access all the features you need for your project.


## Retrieve your MSSQL database credentials

Before you begin the migration, you need to collect essential information about your MSSQL database. Follow these steps:

1.  Log in to your MSSQL database provider.
2.  Locate and note the following database details:
    *   Hostname or IP address
    *   Database name
    *   Username
    *   Password


## Retrieve your Supabase host \[#retrieve-supabase-host]

1.  If you're new to Supabase, [create a project](https://supabase.com/dashboard).
    Make a note of your password, you will need this later. If you forget it, you can [reset it here](https://supabase.com/dashboard/project/_/settings/database).

2.  Go to the [Database settings](https://supabase.com/dashboard/project/_/settings/database) for your project in the Supabase Dashboard.

3.  Under **Connection Info**, note your Host (`$SUPABASE_HOST`).

![Finding Supabase host address](/docs/img/guides/resources/migrating-to-supabase/mssql/database-settings-host.png)


## Migrate the database

The fastest way to migrate your database is with the Supabase migration tool on
[Google Colab](https://colab.research.google.com/github/mansueli/Supa-Migrate/blob/main/Amazon_RDS_to_Supabase.ipynb).

Alternatively, you can use [pgloader](https://github.com/dimitri/pgloader), a flexible and powerful data migration tool that supports a wide range of source database engines, including MySQL and MS SQL, and migrates the data to a Postgres database. For databases using the Postgres engine, we recommend using the [`pg_dump`](https://www.postgresql.org/docs/current/app-pgdump.html) and [psql](https://www.postgresql.org/docs/current/app-psql.html) command line tools, which are included in a full Postgres installation.


## Enterprise

[Contact us](https://forms.supabase.com/enterprise) if you need more help migrating your project.


# Migrate from MySQL to Supabase

Migrate your MySQL database to Supabase Postgres database.

This guide aims to exhibit the process of transferring your MySQL database to Supabase's Postgres database. Supabase is a robust and open-source platform offering a wide range of backend features, including a Postgres database, authentication, instant APIs, edge functions, real-time subscriptions, and storage. Migrating your MySQL database to Supabase's Postgres enables you to leverage PostgreSQL's capabilities and access all the features you need for your project.


## Retrieve your MySQL database credentials

Before you begin the migration, you need to collect essential information about your MySQL database. Follow these steps:

1.  Log in to your MySQL database provider.

2.  Locate and note the following database details:
    *   Hostname or IP address
    *   Database name
    *   Username
    *   Password


## Retrieve your Supabase host \[#retrieve-supabase-host]

1.  If you're new to Supabase, [create a project](https://supabase.com/dashboard).
    Make a note of your password, you will need this later. If you forget it, you can [reset it here](https://supabase.com/dashboard/project/_/settings/database).

2.  Go to the [Database settings](https://supabase.com/dashboard/project/_/settings/database) for your project in the Supabase Dashboard.

3.  Under **Connection Info**, note your Host (`$SUPABASE_HOST`).

![Finding Supabase host address](/docs/img/guides/resources/migrating-to-supabase/mysql/database-settings-host.png)


## Migrate the database

The fastest way to migrate your database is with the Supabase migration tool on
[Google Colab](https://colab.research.google.com/github/mansueli/Supa-Migrate/blob/main/Amazon_RDS_to_Supabase.ipynb).

Alternatively, you can use [pgloader](https://github.com/dimitri/pgloader), a flexible and powerful data migration tool that supports a wide range of source database engines, including MySQL and MS SQL, and migrates the data to a Postgres database. For databases using the Postgres engine, we recommend using the [`pg_dump`](https://www.postgresql.org/docs/current/app-pgdump.html) and [psql](https://www.postgresql.org/docs/current/app-psql.html) command line tools, which are included in a full Postgres installation.


## Enterprise

[Contact us](https://forms.supabase.com/enterprise) if you need more help migrating your project.


# Migrate from Neon to Supabase

Migrate your existing Neon database to Supabase.

This guide demonstrates how to migrate your Neon database to Supabase to get the most out of Postgres while gaining access to all the features you need to build a project.


## Retrieve your Neon database credentials \[#retrieve-credentials]

1.  Log in to your Neon Console <https://console.neon.tech/login>.
2.  Select **Projects** on the left.
3.  Click on your project in the list.
4.  From your Project Dashboard find your **Connection string** and click **Copy snippet** to copy it to the clipboard (do not check "pooled connection").

Example:

```bash
postgresql://neondb_owner:xxxxxxxxxxxxxxx-random-word-yyyyyyyy.us-west-2.aws.neon.tech/neondb?sslmode=require
```


## Set your `OLD_DB_URL` environment variable

Set the **OLD\_DB\_URL** environment variable at the command line using your Neon database credentials from the clipboard.

Example:

```bash
export OLD_DB_URL="postgresql://neondb_owner:xxxxxxxxxxxxxxx-random-word-yyyyyyyy.us-west-2.aws.neon.tech/neondb?sslmode=require"
```


## Retrieve your Supabase connection string \[#retrieve-supabase-connection-string]

1.  If you're new to Supabase, [create a project](https://supabase.com/dashboard).
    Make a note of your password, you will need this later. If you forget it, you can [reset it here](https://supabase.com/dashboard/project/_/settings/database).

2.  Go to the [Database settings](https://supabase.com/dashboard/project/_/settings/database) for your project in the Supabase Dashboard.

3.  Under **Connection string**, select **URI**, make sure **Display connection pooler** is checked, and **Mode: Session** is set.

4.  Click the **Copy** button to the right of your connection string to copy it to the clipboard.


## Set your `NEW_DB_URL` environment variable

Set the **NEW\_DB\_URL** environment variable at the command line using your Supabase connection string. You will need to replace `[YOUR-PASSWORD]` with your actual database password.

Example:

```bash
export NEW_DB_URL="postgresql://postgres.xxxxxxxxxxxxxxxxxxxx:[YOUR-PASSWORD]@aws-0-us-west-1.pooler.supabase.com:5432/postgres"
```


## Migrate the database

You will need the [pg\_dump](https://www.postgresql.org/docs/current/app-pgdump.html) and [psql](https://www.postgresql.org/docs/current/app-psql.html) command line tools, which are included in a full [Postgres installation](https://www.postgresql.org/download).

1.  Export your database to a file in console

    Use `pg_dump` with your Postgres credentials to export your database to a file (e.g., `dump.sql`).

```bash
pg_dump "$OLD_DB_URL" \
  --clean \
  --if-exists \
  --quote-all-identifiers \
  --no-owner \
  --no-privileges \
  > dump.sql
```

2.  Import the database to your Supabase project

    Use `psql` to import the Postgres database file to your Supabase project.

    ```bash
    psql -d "$NEW_DB_URL" -f dump.sql
    ```

Additional options

*   To only migrate a single database schema, add the `--schema=PATTERN` parameter to your `pg_dump` command.
*   To exclude a schema: `--exclude-schema=PATTERN`.
*   To only migrate a single table: `--table=PATTERN`.
*   To exclude a table: `--exclude-table=PATTERN`.

Run `pg_dump --help` for a full list of options.


## Enterprise

[Contact us](https://forms.supabase.com/enterprise) if you need more help migrating your project.


# Migrate from Postgres to Supabase

Migrate your existing Postgres database to Supabase.

This is a guide for migrating your Postgres database to [Supabase](https://supabase.com).
Supabase is a robust and open-source platform. Supabase provide all the backend features developers need to build a product: a Postgres database, authentication, instant APIs, edge functions, realtime subscriptions, and storage. Postgres is the core of Supabase—for example, you can use row-level security and there are more than 40 Postgres extensions available.

This guide demonstrates how to migrate your Postgres database to Supabase to get the most out of Postgres while gaining access to all the features you need to build a project.


## Retrieve your Postgres database credentials \[#retrieve-credentials]

1.  Log in to your provider to get the connection details for your Postgres database.
2.  Click on **PSQL Command** and edit it adding the content after `PSQL_COMMAND=`.

Example:

```bash
%env PSQL_COMMAND=PGPASSWORD=RgaMDfTS_password_FTPa7 psql -h dpg-a_server_in.oregon-postgres.provider.com -U my_db_pxl0_user my_db_pxl0
```


## Retrieve your Supabase connection string \[#retrieve-supabase-connection-string]

1.  If you're new to Supabase, [create a project](https://supabase.com/dashboard).
    Make a note of your password, you will need this later. If you forget it, you can [reset it here](https://supabase.com/dashboard/project/_/settings/database).

2.  Go to the [Database settings](https://supabase.com/dashboard/project/_/settings/database) for your project in the Supabase Dashboard.

3.  Under **Connection string**, make sure `Use connection pooling` is enabled. Copy the URI and replace the password placeholder with your database password.

![Finding Supabase host address](/docs/img/guides/resources/migrating-to-supabase/postgres/database-settings-host.png)


## Migrate the database

The fastest way to migrate your database is with the Supabase migration tool on [Google Colab](https://colab.research.google.com/github/mansueli/Supa-Migrate/blob/main/Migrate_Postgres_Supabase.ipynb). Alternatively, you can use the [pg\_dump](https://www.postgresql.org/docs/current/app-pgdump.html) and [psql](https://www.postgresql.org/docs/current/app-psql.html) command line tools, which are included in a full Postgres installation.


## Enterprise

[Contact us](https://forms.supabase.com/enterprise) if you need more help migrating your project.


# Migrate from Render to Supabase

Migrate your Render Postgres database to Supabase.

Render is a popular Web Hosting service in the online services category that also has a managed Postgres service. Render has a great developer experience, allowing users to deploy straight from GitHub or GitLab. This is the core of their product and they do it really well. However, when it comes to Postgres databases, it may not be the best option.

Supabase is one of the best free alternative to Render Postgres. Supabase provide all the backend features developers need to build a product: a Postgres database, authentication, instant APIs, edge functions, realtime subscriptions, and storage. Postgres is the core of Supabase—for example, you can use row-level security and there are more than 40 Postgres extensions available.

This guide demonstrates how to migrate from Render to Supabase to get the most out of Postgres while gaining access to all the features you need to build a project.


## Retrieve your Render database credentials \[#retrieve-render-credentials]

1.  Log in to your [Render account](https://render.com) and select the project you want to migrate.
2.  Click **Dashboard** in the menu and click in your **Postgres** database.
3.  Scroll down in the **Info** tab.
4.  Click on **PSQL Command** and edit it adding the content after `PSQL_COMMAND=`.

![Copying PSQL command from Render dashboard](/docs/img/guides/resources/migrating-to-supabase/render/render_dashboard.png)
Example:

```bash
%env PSQL_COMMAND=PGPASSWORD=RgaMDfTS_password_FTPa7 psql -h dpg-a_server_in.oregon-postgres.render.com -U my_db_pxl0_user my_db_pxl0
```


## Retrieve your Supabase connection string \[#retrieve-supabase-connection-string]

1.  If you're new to Supabase, [create a project](https://supabase.com/dashboard).
    Make a note of your password, you will need this later. If you forget it, you can [reset it here](https://supabase.com/dashboard/project/_/settings/database).

2.  Go to the [Database settings](https://supabase.com/dashboard/project/_/settings/database) for your project in the Supabase Dashboard.

3.  Under **Connection string**, make sure `Use connection pooling` is enabled. Copy the URI and replace the password placeholder with your database password.


## Migrate the database

The fastest way to migrate your database is with the Supabase migration tool on [Google Colab](https://colab.research.google.com/github/mansueli/Supa-Migrate/blob/main/Migrate_Postgres_Supabase.ipynb). Alternatively, you can use the [pg\_dump](https://www.postgresql.org/docs/current/app-pgdump.html) and [psql](https://www.postgresql.org/docs/current/app-psql.html) command line tools, which are included in a full Postgres installation.


## Enterprise

[Contact us](https://forms.supabase.com/enterprise) if you need more help migrating your project.


# Migrate from Vercel Postgres to Supabase

Migrate your existing Vercel Postgres database to Supabase.

This guide demonstrates how to migrate your Vercel Postgres database to Supabase to get the most out of Postgres while gaining access to all the features you need to build a project.


## Retrieve your Vercel Postgres database credentials \[#retrieve-credentials]

1.  Log in to your Vercel Dashboard <https://vercel.com/login>.
2.  Click on the **Storage** tab.
3.  Click on your Postgres Database.
4.  Under the **Quickstart** section, select **psql** then click **Show Secret** to reveal your database password.
5.  Copy the string after `psql ` to the clipboard.

Example:

```bash
psql "postgres://default:xxxxxxxxxxxx@yy-yyyyy-yyyyyy-yyyyyyy.us-west-2.aws.neon.tech:5432/verceldb?sslmode=require"
```

Copy this part to your clipboard:

```bash
"postgres://default:xxxxxxxxxxxx@yy-yyyyy-yyyyyy-yyyyyyy.us-west-2.aws.neon.tech:5432/verceldb?sslmode=require"
```


## Set your `OLD_DB_URL` environment variable

Set the **OLD\_DB\_URL** environment variable at the command line using your Vercel Postgres Database credentials.

Example:

```bash
export OLD_DB_URL="postgres://default:xxxxxxxxxxxx@yy-yyyyy-yyyyyy-yyyyyyy.us-west-2.aws.neon.tech:5432/verceldb?sslmode=require"
```


## Retrieve your Supabase connection string \[#retrieve-supabase-connection-string]

1.  If you're new to Supabase, [create a project](https://supabase.com/dashboard).
    Make a note of your password, you will need this later. If you forget it, you can [reset it here](https://supabase.com/dashboard/project/_/settings/database).

2.  Go to the [Database settings](https://supabase.com/dashboard/project/_/settings/database) for your project in the Supabase Dashboard.

3.  Under **Connection string**, select **URI**, make sure **Display connection pooler** is checked, and **Mode: Session** is set.

4.  Click the **Copy** button to the right of your connection string to copy it to the clipboard.


## Set your `NEW_DB_URL` environment variable

Set the **NEW\_DB\_URL** environment variable at the command line using your Supabase connection string. You will need to replace `[YOUR-PASSWORD]` with your actual database password.

Example:

```bash
export NEW_DB_URL="postgresql://postgres.xxxxxxxxxxxxxxxxxxxx:[YOUR-PASSWORD]@aws-0-us-west-1.pooler.supabase.com:5432/postgres"
```


## Migrate the database

You will need the [pg\_dump](https://www.postgresql.org/docs/current/app-pgdump.html) and [psql](https://www.postgresql.org/docs/current/app-psql.html) command line tools, which are included in a full [Postgres installation](https://www.postgresql.org/download).

1.  Export your database to a file in console

    Use `pg_dump` with your Postgres credentials to export your database to a file (e.g., `dump.sql`).

```bash
pg_dump "$OLD_DB_URL" \
  --clean \
  --if-exists \
  --quote-all-identifiers \
  --no-owner \
  --no-privileges \
  > dump.sql
```

2.  Import the database to your Supabase project

    Use `psql` to import the Postgres database file to your Supabase project.

    ```bash
    psql -d "$NEW_DB_URL" -f dump.sql
    ```

Additional options

*   To only migrate a single database schema, add the `--schema=PATTERN` parameter to your `pg_dump` command.
*   To exclude a schema: `--exclude-schema=PATTERN`.
*   To only migrate a single table: `--table=PATTERN`.
*   To exclude a table: `--exclude-table=PATTERN`.

Run `pg_dump --help` for a full list of options.


## Enterprise

[Contact us](https://forms.supabase.com/enterprise) if you need more help migrating your project.


# Migrating within Supabase

Learn how to migrate from one Supabase project to another

If you are on a Paid Plan and have physical backups enabled, you should instead use the [Restore
to another project feature](/docs/guides/platform/backups#restore-to-a-new-project)


## Database migration guides

If you need to migrate from one Supabase project to another, choose the appropriate guide below:


### Backup file from the dashboard (\*.backup)

Follow the [Restore dashboard backup guide](/docs/guides/platform/migrating-within-supabase/dashboard-restore)


### SQL backup files (\*.sql)

Follow the [Backup and Restore using the CLI guide](/docs/guides/platform/migrating-within-supabase/backup-restore)


## Transfer project to a different organization

Project migration is primarily for changing regions or upgrading to new major versions of the platform in some scenarios. If you need to move your project to a different organization without touching the infrastructure, see [project transfers](/docs/guides/platform/project-transfer).


# Backup and Restore using the CLI

Learn how to backup and restore projects using the Supabase CLI

## Backup database using the CLI


## Before you begin


## Restore backup using CLI


## Important project restoration notes


### Troubleshooting notes

*   Setting the `session_replication_role` to `replica` disables all triggers so that columns are not double encrypted.
*   If you have created any [custom roles](/dashboard/project/_/database/roles) with `login` attribute, you have to manually set their passwords in the new project.
*   If you run into any permission errors related to `supabase_admin` during restore, edit the `schema.sql` file and comment out any lines containing `ALTER ... OWNER TO "supabase_admin"`.


### Preserving migration history

If you were using Supabase CLI for managing migrations on your old database and would like to preserve the migration history in your newly restored project, you need to insert the migration records separately using the following commands.

```bash
supabase db dump --db-url "$OLD_DB_URL" -f history_schema.sql --schema supabase_migrations
supabase db dump --db-url "$OLD_DB_URL" -f history_data.sql --use-copy --data-only --schema supabase_migrations
psql \
  --single-transaction \
  --variable ON_ERROR_STOP=1 \
  --file history_schema.sql \
  --file history_data.sql \
  --dbname "$NEW_DB_URL"
```


### Schema changes to `auth` and `storage`

If you have modified the `auth` and `storage` schemas in your old project, such as adding triggers or Row Level Security(RLS) policies, you have to restore them separately. The Supabase CLI can help you diff the changes to these schemas using the following commands.

```bash
supabase link --project-ref "$OLD_PROJECT_REF"
supabase db diff --linked --schema auth,storage > changes.sql
```


### Migrate storage objects

The new project has the old project's Storage buckets, but the Storage objects need to be migrated manually. Use this script to move storage objects from one project to another.

```js
// npm install @supabase/supabase-js@1
const { createClient } = require('@supabase/supabase-js')

const OLD_PROJECT_URL = 'https://xxx.supabase.co'
const OLD_PROJECT_SERVICE_KEY = 'old-project-service-key-xxx'

const NEW_PROJECT_URL = 'https://yyy.supabase.co'
const NEW_PROJECT_SERVICE_KEY = 'new-project-service-key-yyy'

;(async () => {
  const oldSupabaseRestClient = createClient(OLD_PROJECT_URL, OLD_PROJECT_SERVICE_KEY, {
    db: {
      schema: 'storage',
    },
  })
  const oldSupabaseClient = createClient(OLD_PROJECT_URL, OLD_PROJECT_SERVICE_KEY)
  const newSupabaseClient = createClient(NEW_PROJECT_URL, NEW_PROJECT_SERVICE_KEY)

  // make sure you update max_rows in postgrest settings if you have a lot of objects
  // or paginate here
  const { data: oldObjects, error } = await oldSupabaseRestClient.from('objects').select()
  if (error) {
    console.log('error getting objects from old bucket')
    throw error
  }

  for (const objectData of oldObjects) {
    console.log(`moving ${objectData.id}`)
    try {
      const { data, error: downloadObjectError } = await oldSupabaseClient.storage
        .from(objectData.bucket_id)
        .download(objectData.name)
      if (downloadObjectError) {
        throw downloadObjectError
      }

      const { _, error: uploadObjectError } = await newSupabaseClient.storage
        .from(objectData.bucket_id)
        .upload(objectData.name, data, {
          upsert: true,
          contentType: objectData.metadata.mimetype,
          cacheControl: objectData.metadata.cacheControl,
        })
      if (uploadObjectError) {
        throw uploadObjectError
      }
    } catch (err) {
      console.log('error moving ', objectData)
      console.log(err)
    }
  }
})()
```


# Restore Dashboard backup

Learn how to restore your dashboard backup to a new Supabase project

## Before you begin


## Things to keep in mind

Here are some things that are not stored directly in your database and will require you to re-create or setup on the new project:

*   Edge Functions
*   Auth Settings and API keys
*   Realtime settings
*   Database extensions and settings
*   Read Replicas

Here is a non-exhaustive list of items that are commonly asked about and will be migrated with your backup restoration:

*   Database triggers
*   Database functions


## Restore backup


## Migrate storage objects to new project's S3 storage

After restoring the backup, the buckets and files metadata will show up in the dashboard of the new project.
However, the storage files stored in the S3 buckets would not be present.

Use the following Google Colab script provided below to migrate your downloaded storage objects to your new project's S3 buckets.

[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/PLyn/supabase-storage-migrate/blob/main/Supabase_Storage_migration.ipynb)

This method requires uploading to Google Colab and then to the S3 buckets. This could add significant upload time if there are large storage objects.


## Common errors with the backup restore process

"**object already exists**"
"**constraint x for relation y already exists**"
"**Many other variations of errors**"

These errors are expected when restoring to a new Supabase project. The backup from the dashboard is a full dump which contains the CREATE commands for all schemas. This is by design as the full dump allows you to rebuild the entire database from scratch even outside of Supabase.

One side effect of this method is that a new Supabase project has these commands already applied to schemas like storage and auth. The errors from this are not an issue because it skips to the next command to run. Another side effect of this is that all triggers will run during the restoration process which is not ideal but generally is not a problem.

There are circumstances where this method can fail and if it does, you should reach out to Supabase support for help.

"**psql: error: connection to server at "aws-0-us-east-1.pooler.supabase.com" (44.216.29.125), port 5432 failed: received invalid response to GSSAPI negotiation:**"

You are possibly using psql and Postgres version 15 or lower. Completely remove the Postgres installation and install the latest version as per the instructions above to resolve this issue.

"**psql: error: connection to server at "aws-0-us-east-1.pooler.supabase.com" (44.216.29.125), port 5432 failed: error received from server in SCRAM exchange: Wrong password**"

If the database password was reset, it may take a few minutes for it to reflect. Try again after a few minutes if you did a password reset.


# Multi-factor Authentication

Enable multi-factor authentication (MFA) to keep your account secure.

Multi-factor authentication (MFA) adds an additional layer of security to your user account, by requiring a second factor to verify your user identity. Supabase allows users to enable MFA on their account and set it as a requirement for subsequent logins.


## Supported authentication factors

Currently, Supabase supports adding a unique time-based one-time password (TOTP) to your user account as an additional security factor. You can manage your TOTP factor using apps such as 1Password, Authy, Google Authenticator or Apple's Keychain.


## Enable MFA

You can enable MFA for your user account under your [Supabase account settings](/dashboard/account/security). Enabling MFA will result in all other user sessions to be automatically logged out and forced to sign-in again with MFA.


## Login with MFA

Once you've enabled MFA for your Supabase user account, you will be prompted to enter your second factor challenge code as seen in your preferred TOTP app.


## Disable MFA

You can disable MFA for your user account under your [Supabase account settings](/dashboard/account/security). On subsequent login attempts, you will not be prompted to enter a MFA code.


# Network Restrictions



Each Supabase project comes with configurable restrictions on the IP ranges that are allowed to connect to Postgres and its pooler ("your database"). These restrictions are enforced before traffic reaches your database. If a connection is not restricted by IP, it still needs to authenticate successfully with valid database credentials.

If direct connections to your database [resolve to a IPv6 address](https://supabase.com/dashboard/project/_/settings/database), you need to add both IPv4 and IPv6 CIDRs to the list of allowed CIDRs. Network Restrictions will be applied to all database connection routes, whether pooled or direct. You will need to add both the IPv4 and IPv6 networks you want to allow. There are two exceptions: If you have been granted an extension on the IPv6 migration OR if you have purchased the [IPv4 add-on](https://supabase.com/dashboard/project/_/settings/addons), you need only add IPv4 CIDRs.


## To get started via the Dashboard:

Network restrictions can be configured in the [Database Settings](https://supabase.com/dashboard/project/_/settings/database) page. Ensure that you have [Owner or Admin permissions](/docs/guides/platform/access-control#manage-team-members) for the project that you are enabling network restrictions.


## To get started via the CLI:

1.  [Install](/docs/guides/cli) the Supabase CLI 1.22.0+.
2.  [Log in](/docs/guides/cli/local-development#log-in-to-the-supabase-cli) to your Supabase account using the CLI.
3.  If your project was created before 23rd December 2022, it will need to be [upgraded to the latest Supabase version](/docs/guides/platform/migrating-and-upgrading-projects) before Network Restrictions can be used.
4.  Ensure that you have [Owner or Admin permissions](/docs/guides/platform/access-control#manage-team-members) for the project that you are enabling network restrictions.


### Check restrictions

You can use the `get` subcommand of the CLI to retrieve the restrictions currently in effect.

If restrictions have been applied, the output of the `get` command will reflect the IP ranges allowed to connect:

```bash
> supabase network-restrictions --project-ref {ref} get --experimental
DB Allowed IPv4 CIDRs: &[183.12.1.1/24]
DB Allowed IPv6 CIDRs: &[2001:db8:3333:4444:5555:6666:7777:8888/64]
Restrictions applied successfully: true
```

If restrictions have never been applied to your project, the list of allowed CIDRs will be empty, but they will also not have been applied ("Restrictions applied successfully: false"). As a result, all IPs are allowed to connect to your database:

```bash
> supabase network-restrictions --project-ref {ref} get --experimental
DB Allowed IPv4 CIDRs: []
DB Allowed IPv6 CIDRs: []
Restrictions applied successfully: false
```


### Update restrictions

The `update` subcommand is used to apply network restrictions to your project:

```bash
> supabase network-restrictions --project-ref {ref} update --db-allow-cidr 183.12.1.1/24 --db-allow-cidr 2001:db8:3333:4444:5555:6666:7777:8888/64 --experimental
DB Allowed IPv4 CIDRs: &[183.12.1.1/24]
DB Allowed IPv6 CIDRs: &[2001:db8:3333:4444:5555:6666:7777:8888/64]
Restrictions applied successfully: true
```

The restrictions specified (in the form of CIDRs) replaces any restrictions that might have been applied in the past.
To add to the existing restrictions, you must include the existing restrictions within the list of CIDRs provided to the `update` command.


### Remove restrictions

To remove all restrictions on your project, you can use the `update` subcommand with the CIDR `0.0.0.0/0`:

```bash
> supabase network-restrictions --project-ref {ref} update --db-allow-cidr 0.0.0.0/0 --db-allow-cidr ::/0 --experimental
DB Allowed IPv4 CIDRs: &[0.0.0.0/0]
DB Allowed IPv6 CIDRs: &[::/0]
Restrictions applied successfully: true
```


## Limitations

*   The current iteration of Network Restrictions applies to connections to Postgres and the database pooler; it doesn't currently apply to APIs offered over HTTPS (e.g., PostgREST, Storage, and Auth). This includes using Supabase client libraries like [supabase-js](https://supabase.com/docs/reference/javascript).
*   If network restrictions are enabled, direct access to your database from Edge Functions will always be blocked. Using the Supabase client library [supabase-js](https://supabase.com/docs/reference/javascript) is recommended to connect to a database with network restrictions from Edge Functions.


# Performance Tuning



The Supabase platform automatically optimizes your Postgres database to take advantage of the compute resources of the plan your project is on. However, these optimizations are based on assumptions about the type of workflow the project is being utilized for, and it is likely that better results can be obtained by tuning the database for your particular workflow.


## Examining query performance

Unoptimized queries are a major cause of poor database performance. To analyze the performance of your queries, see the [Debugging and monitoring guide](/docs/guides/database/inspect).


## Optimizing the number of connections

The default connection limits for Postgres and Supavisor is based on your compute size. See the default connection numbers in the [Compute Add-ons](/docs/guides/platform/compute-add-ons) section.

If the number of connections is insufficient, you will receive the following error upon connecting to the DB:

```shell
$ psql -U postgres -h ...
FATAL: remaining connection slots are reserved for non-replication superuser connections
```

In such a scenario, you can consider:

*   [upgrading to a larger compute add-on](https://supabase.com/dashboard/project/_/settings/compute-and-disk)
*   configuring your clients to use fewer connections
*   manually configuring the database for a higher number of connections


### Configuring clients to use fewer connections

You can use the [pg\_stat\_activity](https://www.postgresql.org/docs/current/monitoring-stats.html#MONITORING-PG-STAT-ACTIVITY-VIEW) view to debug which clients are holding open connections on your DB. `pg_stat_activity` only exposes information on direct connections to the database. Information on the number of connections to Supavisor is available [via the metrics endpoint](../platform/metrics).

Depending on the clients involved, you might be able to configure them to work with fewer connections (e.g. by imposing a limit on the maximum number of connections they're allowed to use), or shift specific workloads to connect via [Supavisor](/docs/guides/database/connecting-to-postgres#connection-pooler) instead. Transient workflows, which can quickly scale up and down in response to traffic (e.g. serverless functions), can especially benefit from using a connection pooler rather than connecting to the DB directly.


### Allowing higher number of connections

You can configure Postgres connection limit among other parameters by using [Custom Postgres Config](/docs/guides/platform/custom-postgres-config#custom-postgres-config).


### Enterprise

[Contact us](https://forms.supabase.com/enterprise) if you need help tuning your database for your specific workflow.


# Permissions



The Supabase platform offers additional services (e.g. Storage) on top of the Postgres database that comes with each project. These services default to storing their operational data within your database, to ensure that you retain complete control over it.

However, these services assume a base level of access to their data, in order to e.g. be able to run migrations over it. Breaking these assumptions runs the risk of rendering these services inoperational for your project:

*   all entities under the `storage` schema are owned by `supabase_storage_admin`
*   all entities under the `auth` schema are owned by `supabase_auth_admin`

It is possible for violations of these assumptions to not cause an immediate outage, but take effect at a later time when a newer migration becomes available.


# Project Transfers



You can freely transfer projects between different organizations. Head to your [projects' general settings](https://supabase.com/dashboard/project/_/settings/general) to initiate a project transfer.

Source organization - the organization the project currently belongs to
Target organization - the organization you want to move the project to


## Pre-Requirements

*   You need to be the owner of the source organization.
*   You need to be at least a member of the target organization you want to move the project to.
*   Projects with support tier add-ons cannot be transferred at this point. [Open a support ticket](https://supabase.com/dashboard/support/new?category=billing\&subject=Transfer%20project).


## Usage-billing and project add-ons

For usage metrics such as disk size, egress or image transformations and project add-ons such as [Compute Add-On](/docs/guides/platform/compute-add-ons), [Point-In-Time-Recovery](/docs/guides/platform/backups#point-in-time-recovery), [IPv4](/docs/guides/platform/ipv4-address), [Log Drains](/docs/guides/platform/log-drains), [Advanced MFA](/docs/guides/auth/auth-mfa/phone) or a [Custom Domain](/docs/guides/platform/custom-domains), the source organization will still be charged for the usage up until the transfer. The charges will be added to the invoice when the billing cycle resets.

The target organization will be charged at the end of the billing cycle for usage after the project transfer.


## Things to watch out for

*   Transferring a project might come with a short 1-2 minute downtime if you're moving a project from a paid to a Free Plan.
*   You could lose access to certain project features depending on the plan of the target organization, i.e. moving a project from a Pro Plan to a Free Plan.
*   When moving your project to a Free Plan, we also ensure you’re not exceeding your two free project limit. In these cases, it is best to upgrade your target organization to Pro Plan first.
*   You could have less rights on the project depending on your role in the target organization, i.e. you were an Owner in the previous organization and only have a Read-Only role in the target organization.


## Transfer to a different region

Note that project transfers are only transferring your projects across an organization and cannot be used to transfer between different regions. To move your project to a different region, see [migrating your project](/docs/guides/platform/migrating-and-upgrading-projects#migrate-your-project).


# Read Replicas

Deploy read-only databases across multiple regions, for lower latency and better resource management.

Read Replicas are additional databases that are kept in sync with your Primary database. You can read your data from a Read Replica, which helps with:

*   **Load balancing:** Read Replicas reduce load on the Primary database. For example, you can use a Read Replica for complex analytical queries and reserve the Primary for user-facing create, update, and delete operations.
*   **Improved latency:** For projects with a global user base, additional databases can be deployed closer to users to reduce latency.
*   **Redundancy:** Read Replicas provide data redundancy.


## About Read Replicas

The database you start with when launching a Supabase project is your Primary database. Read Replicas are kept in sync with the Primary through a process called "replication." Replication is asynchronous to ensure that transactions on the Primary aren't blocked. There is a delay between an update on the Primary and the time that a Read Replica receives the change. This delay is called "replication lag."

You can only read data from a Read Replica. This is in contrast to a Primary database, where you can both read and write:

|              | select | insert | update | delete |
| ------------ | ------ | ------ | ------ | ------ |
| Primary      | ✅     | ✅     | ✅     | ✅     |
| Read Replica | ✅     | -      | -      | -      |


## Prerequisites

Projects must meet these requirements to use Read Replicas:

1.  Running on AWS.
2.  Running on at least a [Small compute add-on](/docs/guides/platform/compute-add-ons).
    *   Read Replicas are started on the same compute instance as the Primary to keep up with changes.
3.  Running on Postgres 15+.
    *   For projects running on older versions of Postgres, you will need to [upgrade to the latest platform version](/docs/guides/platform/migrating-and-upgrading-projects#pgupgrade).
4.  Using [physical backups](/docs/guides/platform/backups#point-in-time-recovery)
    *   Physical backups are automatically enabled if using [PITR](/docs/guides/platform/backups#point-in-time-recovery)
    *   If you're not using PITR, you'll be able to switch to physical backups as part of the Read Replica setup process. Note that physical backups can't be downloaded from the dashboard in the way logical backups can.


## Getting started

To add a Read Replica, go to the [Infrastructure Settings page](/dashboard/project/_/settings/infrastructure) in your dashboard.

Projects on an XL compute add-on or larger can create up to five Read Replicas. Projects on compute add-ons smaller than XL can create up to two Read Replicas. All Read Replicas inherit the compute size of their Primary database.


### Deploying a Read Replica

A Read Replica is deployed by using a physical backup as a starting point, and a combination of WAL file archives and direct replication from the Primary database to catch up. Both components may take significant time to complete. The duration of restoring from a physical backup is roughly dependent and directly related to the database size of your project. The time taken to catch up to the primary using WAL archives and direct replication is dependent on the level of activity on the Primary database; a more active database will produce a larger number of WAL files that will need to be processed.

Along with the progress of the deployment, the dashboard displays rough estimates for each component.


### What does it mean when "Init failed" is observed?

The status `Init failed` indicates that the Read Replica has failed to deploy. Some possible scenarios as to why a Read Replica may have failed to be deployed:

*   Underlying instance failed to come up.
*   Network issue leading to inability to connect to the Primary database.
*   Possible incompatible database settings between the Primary and Read Replica databases.
*   Platform issues.

It is safe to drop this failed Read Replica, and in the event of a transient issue, attempt to spin up another one. If however spinning up Read Replicas for your project consistently fails, do check out our [status page](https://status.supabase.com) for any ongoing incidents, or open a support ticket [here](/dashboard/support/new). To aid the investigation, do not bring down the recently failed Read Replica.


## Features

Read Replicas offer the following features:


### Dedicated endpoints

Each Read Replica has its own dedicated database and API endpoints.

*   Find the database endpoint on the [Database Settings page](/dashboard/project/_/settings/database) under **Connection Info**
*   Find the API endpoint on the [API Settings page](/dashboard/project/_/settings/api) under **Project URL**

Read Replicas only support `GET` requests from the [REST API](/docs/guides/api). If you are calling a read-only Postgres function through the REST API, make sure to set the `get: true` [option](/docs/reference/javascript/rpc?queryGroups=example\&example=call-a-read-only-postgres-function).

Requests to other Supabase products, such as Auth, Storage, and Realtime, aren't able to use a Read Replica or its API endpoint. Support for more products will be added in the future.

If you're using an [IPv4 add-on](/docs/guides/platform/ipv4-address#read-replicas), the database endpoints for your Read Replicas will also use an IPv4 add-on.


### Dedicated connection pool

A connection pool through Supavisor is also available for each Read Replica. Find the connection string on the [Database Settings page](/dashboard/project/_/settings/database) under **Connection String**.


### API load balancer

A load balancer is deployed to automatically balance requests between your Primary database and Read Replicas. Find its endpoint on the [API Settings page](/dashboard/project/_/settings/api).

The load balancer enables geo-routing for Data API requests so that `GET` requests will automatically be routed to the Read Replica that is closest to your user ensuring the lowest latency. Non-`GET` requests can also be sent through this endpoint, and will be routed to the Primary database.

You can also interact with Supabase services (Auth, Edge Functions, Realtime, and Storage) through this load balancer so there's no need to worry about which endpoint to use and in which situations. However, geo-routing for these services are not yet available but is coming soon.

To call a read-only Postgres function on Read Replicas through the REST API, use the `get: true` [option](/docs/reference/javascript/rpc?queryGroups=example\&example=call-a-read-only-postgres-function).

If you remove all Read Replicas from your project, the load balancer and its endpoint are removed as well. Make sure to redirect requests back to your Primary database before removal.


### Querying through the SQL editor

In the SQL editor, you can choose if you want to run the query on a particular Read Replica.


### Logging

When a Read Replica is deployed, it emits logs from the following services:

*   [API](/dashboard/project/_/logs/edge-logs)
*   [Postgres](/dashboard/project/_/logs/postgres-logs)
*   [PostgREST](/dashboard/project/_/logs/postgrest-logs)
*   [Supavisor](/dashboard/project/_/logs/pooler-logs)

Views on [Log Explorer](/docs/guides/platform/logs) are automatically filtered by databases, with the logs of the Primary database displayed by default. Viewing logs from other databases can be toggled with the `Source` button found on the upper-right part section of the Logs Explorer page.

For API logs, logs can originate from the API Load Balancer as well. The upstream database or the one that eventually handles the request can be found under the `Redirect Identifier` field. This is equivalent to `metadata.load_balancer_redirect_identifier` when querying the underlying logs.


### Metrics

Observability and metrics for Read Replicas are available on the Supabase Dashboard. Resource utilization for a specific Read Replica can be viewed on the [Database Reports page](/dashboard/project/_/reports/database) by toggling for `Source`. Likewise, metrics on API requests going through either a Read Replica or Load Balancer API endpoint are also available on the dashboard through the [API Reports page](/dashboard/project/_/reports/api-overview)

We recommend ingesting your [project's metrics](/docs/guides/platform/metrics#accessing-the-metrics-endpoint) into your own environment. If you have an existing ingestion pipeline set up for your project, you can [update it](https://github.com/supabase/supabase-grafana?tab=readme-ov-file#read-replica-support) to additionally ingest metrics from your Read Replicas.


### Centralized configuration management

All settings configured through the dashboard will be propagated across all databases of a project. This ensures that no Read Replica get out of sync with the Primary database or with other Read Replicas.


## Operations blocked by Read Replicas


### Project upgrades and data restorations

The following procedures require all Read Replicas for a project to be brought down before they can be performed:

1.  [Project upgrades](/docs/guides/platform/migrating-and-upgrading-projects#pgupgrade)
2.  [Data restorations](/docs/guides/platform/backups#pitr-restoration-process)

These operations need to be completed before Read Replicas can be re-deployed.


## About replication

We use a hybrid approach to replicate data from a Primary to its Read Replicas, combining the native methods of streaming replication and file-based log shipping.


### Streaming replication

Postgres generates a Write Ahead Log (WAL) as database changes occur. With streaming replication, these changes stream from the Primary to the Read Replica server. The WAL alone is sufficient to reconstruct the database to its current state.

This replication method is fast, since changes are streamed directly from the Primary to the Read Replica. On the other hand, it faces challenges when the Read Replica can't keep up with the WAL changes from its Primary. This can happen when the Read Replica is too small, running on degraded hardware, or has a heavier workload running.

To address this, Postgres does provide tunable configuration, like `wal_keep_size`, to adjust the WAL retained by the Primary. If the Read Replica fails to “catch up” before the WAL surpasses the `wal_keep_size` setting, the replication is terminated. Tuning is a bit of an art - the amount of WAL required is variable for every situation.


### File-based log shipping

In this replication method, the Primary continuously buffers WAL changes to a local file and then sends the file to the Read Replica. If multiple Read Replicas are present, files could also be sent to an intermediary location accessible by all. The Read Replica then reads the WAL files and applies those changes. There is higher replication lag than streaming replication since the Primary buffers the changes locally first. It also means there is a small chance that WAL changes do not reach Read Replicas if the Primary goes down before the file is transferred. In these cases, if the Primary fails a Replica using streaming replication would (in most cases) be more up-to-date than a Replica using file-based log shipping.


### File-based log shipping 🤝 streaming replication

We bring these two methods together to achieve quick, stable, and reliable replication. Each method addresses the limitations of the other. Streaming replication minimizes replication lag, while file-based log shipping provides a fallback. For file-based log shipping, we use our existing Point In Time Recovery (PITR) infrastructure. We regularly archive files from the Primary using [WAL-G](https://github.com/wal-g/wal-g), an open source archival and restoration tool, and ship the WAL files to S3.

We combine it with streaming replication to reduce replication lag. Once WAL-G files have been synced from S3, Read Replicas connect to the Primary and stream the WAL directly.


### Monitoring replication lag

Replication lag for a specific Read Replica can be monitored through the dashboard. On the [Database Reports page](/dashboard/project/_/reports/database) Read Replicas will have an additional chart under `Replica Information` displaying historical replication lag in seconds. Realtime replication lag in seconds can be observed on the [Infrastructure Settings page](/dashboard/project/_/settings/infrastructure). This is the value on top of the Read Replica. Do note that there is no single threshold to indicate when replication lag should be addressed. It would be fully dependent on the requirements of your project.

If you are already ingesting your [project's metrics](/docs/guides/platform/metrics#accessing-the-metrics-endpoint) into your own environment, you can also keep track of replication lag and set alarms accordingly with the metric: `physical_replication_lag_physical_replica_lag_seconds`.

Some common sources of high replication lag include:

1.  Exclusive locks on tables on the Primary.
    Operations such as `drop table`, `reindex` (amongst others) take an Access Exclusive lock on the table. This can result in increasing replication lag for the duration of the lock.
2.  Resource Constraints on the database
    Heavy utilization on the primary or the replica, if run on an under-resourced project, can result in high replication lag. This includes the characteristics of the disk being utilized (IOPS, Throughput).
3.  Long-running transactions on the Primary.
    Transactions that run for a long-time on the primary can also result in high replication lag. You can use the `pg_stat_activity` view to identify and terminate such transactions if needed. `pg_stat_activity` is a live view, and does not offer historical data on transactions that might have been active for a long time in the past.

High replication lag can result in stale data being returned for queries being executed against the affected read replicas.

You can [consult](https://cloud.google.com/sql/docs/postgres/replication/replication-lag) [additional](https://repost.aws/knowledge-center/rds-postgresql-replication-lag) [resources](https://severalnines.com/blog/what-look-if-your-postgresql-replication-lagging/) on the subject as well.


## Misc


### Restart or compute add-on change behaviour

When a project that utilizes Read Replicas is restarted, or the compute add-on size is changed, the Primary database gets restarted first. During this period, the Read Replicas remain available.

Once the Primary database has completed restarting (or resizing, in case of a compute add-on change) and become available for usage, all the Read Replicas are restarted (and resized, if needed) concurrently.


## Pricing

For a detailed breakdown of how charges are calculated, refer to [Manage Read Replica usage](/docs/guides/platform/manage-your-usage/read-replicas).


# Available regions

Spin up Supabase projects in our global regions

The following regions are available for your Supabase projects.


## AWS


# Postgres SSL Enforcement



Your Supabase project supports connecting to the Postgres DB without SSL enabled to maximize client compatibility. For increased security, you can prevent clients from connecting if they're not using SSL.

Disabling SSL enforcement only applies to connections to Postgres and Supavisor ("Connection Pooler"); all HTTP APIs offered by Supabase (e.g., PostgREST, Storage, Auth) automatically enforce SSL on all incoming connections.


## Manage SSL enforcement via the dashboard

SSL enforcement can be configured via the "Enforce SSL on incoming connections" setting under the SSL Configuration section in [Database Settings page](https://supabase.com/dashboard/project/_/settings/database) of the dashboard.


## Manage SSL enforcement via the CLI

To get started:

1.  [Install](/docs/guides/cli) the Supabase CLI 1.37.0+.
2.  [Log in](/docs/guides/getting-started/local-development#log-in-to-the-supabase-cli) to your Supabase account using the CLI.
3.  Ensure that you have [Owner or Admin permissions](/docs/guides/platform/access-control#manage-team-members) for the project that you are enabling SSL enforcement.


### Check enforcement status

You can use the `get` subcommand of the CLI to check whether SSL is currently being enforced:

```bash
supabase ssl-enforcement --project-ref {ref} get --experimental
```

Response if SSL is being enforced:

```bash
SSL is being enforced.
```

Response if SSL is not being enforced:

```bash
SSL is *NOT* being enforced.
```


### Update enforcement

The `update` subcommand is used to change the SSL enforcement status for your project:

```bash
supabase ssl-enforcement --project-ref {ref} update --enable-db-ssl-enforcement --experimental
```

Similarly, to disable SSL enforcement:

```bash
supabase ssl-enforcement --project-ref {ref} update --disable-db-ssl-enforcement --experimental
```


### A note about Postgres SSL modes

Postgres supports [multiple SSL modes](https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-PROTECTION) on the client side. These modes provide different levels of protection. Depending on your needs, it is important to verify that the SSL mode in use is performing the required level of enforcement and verification of SSL connections.

The strongest mode offered by Postgres is `verify-full` and this is the mode you most likely want to use when SSL enforcement is enabled. To use `verify-full` you will need to download the Supabase CA certificate for your database. The certificate is available through the dashboard under the SSL Configuration section in the [Database Settings page](/dashboard/project/_/settings/database).

Once the CA certificate has been downloaded, add it to the certificate authority list used by Postgres.

```bash
cat {location of downloaded prod-ca-2021.crt} >> ~/.postgres/root.crt
```

With the CA certificate added to the trusted certificate authorities list, use `psql` or your client library to connect to Supabase:

```bash
psql "postgresql://aws-0-eu-central-1.pooler.supabase.com:6543/postgres?sslmode=verify-full" -U postgres.<user>
```


# Enable SSO for Your Organization



Supabase offers single sign-on (SSO) as a login option to provide additional account security for your team. This allows company administrators to enforce the use of an identity provider when logging into Supabase. SSO improves the onboarding and offboarding experience of the company as the employee only needs a single set of credentials to access third-party applications or tools which can also be revoked by an administrator.


## Setup and limitations

Supabase supports practically all identity providers that support the SAML 2.0 SSO protocol. We've prepared these guides for commonly used identity providers to help you get started. If you use a different provider, our support stands ready to support you.

*   [Google Workspaces (formerly G Suite)](/docs/guides/platform/sso/gsuite)
*   [Azure Active Directory](/docs/guides/platform/sso/azure)
*   [Okta](/docs/guides/platform/sso/okta)

Accounts signing in with SSO have certain limitations.
The following sections outline the limitations when SSO is enabled or disabled for your team.


### Enable SSO for your team \[#enable-sso]

*   Organization invites are restricted to company members belonging to the same identity provider.
*   Every user has an organization created by default. They can create as many projects as they want.
*   An SSO user will not be able to update or reset their password since the company administrator manages their access via the identity provider.
*   If an SSO user with the following email of `alice@foocorp.com` attempts to sign in with a GitHub account that uses the same email, a separate Supabase account is created and will not be linked to the SSO user's account.
*   An SSO user will not be able to see all organizations/projects created under the same identity provider. They will need to be invited to the Supabase organization first. Refer to [access control](/docs/guides/platform/access-control) for more information.


### Disable SSO for your team \[#disable-sso]

*   You can prevent a user's account from further access to Supabase by removing or disabling their account in your identity provider.
*   You should also remove or downgrade their permissions from any organizations inside Supabase.


# Set Up SSO with Azure AD



Supabase supports single sign-on (SSO) using Microsoft Azure AD.


## Step 1: Add and register an Enterprise application \[#add-and-register-enterprise-application]

Open up the [Azure Active Directory](https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/Overview) dashboard for your Azure account.

Click the *Add* button then *Enterprise application*.

![Azure AD console: Default Directory Overview](/docs/img/sso-azure-step-01.png)


## Step 2: Choose to create your own application \[#create-application]

You'll be using the custom enterprise application setup for Supabase.

![Azure AD console: Browse Azure AD Gallery, select: Create your own application](/docs/img/sso-azure-step-02.png)


## Step 3: Fill in application details \[#add-application-details]

In the modal titled *Create your own application*, enter a display name for Supabase. This is the name your Azure AD users see when signing in to Supabase from Azure. `Supabase` works in most cases.

Make sure to choose the third option: *Integrate any other application you
don't find in the gallery (Non-gallery)*.

![Azure AD console: Create your own application modal](/docs/img/sso-azure-step-03.png)


## Step 4: Set up single sign-on \[#set-up-single-sign-on]

Before you get to assigning users and groups, which would allow accounts in Azure AD to access Supabase, you need to configure the SAML details that allows Supabase to accept sign in requests from Azure AD.

![Azure AD console: Supabase custom enterprise application, selected Set up single sign-on](/docs/img/sso-azure-step-04.png)


## Step 5: Select SAML single sign-on method \[#saml-sso]

Supabase only supports the SAML 2.0 protocol for Single Sign-On, which is an industry standard.

![Azure AD console: Supabase application, Single sign-on configuration screen, selected SAML](/docs/img/sso-azure-step-05.png)


## Step 6: Upload SAML-based sign-on metadata file \[#upload-saml-metadata]

First you need to download Supabase's SAML metadata file. Click the button below to initiate a download of the file.

Alternatively, visit this page to initiate a download: `https://alt.supabase.io/auth/v1/sso/saml/metadata?download=true`

Click on the *Upload metadata file* option in the toolbar and select the file you just downloaded.

![Azure AD console: Supabase application, SAML-based Sign-on screen, selected Upload metadata file button](/docs/img/sso-azure-step-06-1.png)

All of the correct information should automatically populate the *Basic SAML Configuration* screen as shown.

![Azure AD console: Supabase application, SAML-based Sign-on screen, Basic SAML Configuration shown](/docs/img/sso-azure-step-06-2.png)

**Make sure you input these additional settings.**

| Setting     | Value                                        |
| ----------- | -------------------------------------------- |
| Sign on URL | `https://supabase.com/dashboard/sign-in-sso` |
| Relay State | `https://supabase.com/dashboard`             |

Finally, click the *Save* button to save the configuration.


## Step 7: Obtain metadata URL and send to Supabase \[#send-metadata-url]

Supabase needs to finalize enabling single sign-on with your Azure AD application. To do this, copy and send the link under **App Federation Metadata URL** in \*section 3 **SAML Certificates\*** to your support contact and await further instructions. If you're not clear who to send this link to or need further assistance, reach out to [Supabase Support](https://supabase.help).

**Do not test the login until you have heard back from the support contact.**

![Azure AD console: Supabase application, SAML Certificates card shown, App Federation Metadata Url highlighted](/docs/img/sso-azure-step-07.png)


## Step 8: Wait for confirmation \[#confirmation]

Wait for confirmation or further instructions from your support contact at Supabase before proceeding to the next step. It usually takes us 1 business day to configure SSO for you.


## Step 9: Test single sign-on \[#testing]

*Testing sign-on before your Azure AD has been registered with Supabase will not work. Make sure you've received confirmation from your support contact at Supabase as laid out in the [confirmation](#confirmation) step.*

Once you’ve received confirmation from your support contact at Supabase that SSO setup has been completed for your enterprise, you can ask some of your users to sign in via their Azure AD account.

You ask them to enter their email address on the [Sign in with SSO](https://supabase.com/dashboard/sign-in-sso) page.

If sign in is not working correctly, reach out to your support contact at Supabase for further guidance.


# Set Up SSO with Google Workspace



Supabase supports single sign-on (SSO) using Google Workspace (formerly known as G Suite).


## Step 1: Open the Google Workspace web and mobile apps console \[#google-workspace-console]

![Google Workspace: Web and mobile apps admin console](/docs/img/sso-gsuite-step-01.png)


## Step 2: Choose to add custom SAML app \[#add-custom-saml-app]

From the *Add app* button in the toolbar choose *Add custom SAML app*.

![Google Workspace: Web and mobile apps admin console, Add custom SAML app selected](/docs/img/sso-gsuite-step-02.png)


## Step 3: Fill out app details \[#add-app-details]

The information you enter here is for visibility into your Google Workspace. You can choose any values you like. `Supabase` as a name works well for most use cases. Optionally enter a description.

![Google Workspace: Web and mobile apps admin console, Add custom SAML, App details screen](/docs/img/sso-gsuite-step-03.png)


## Step 4: Download IdP metadata \[#download-idp-metadata]

This is a very important step. Click on *DOWNLOAD METADATA* and save the file that was downloaded.

![Google Workspace: Web and mobile apps admin console, Add custom SAML, Google Identity Provider details screen](/docs/img/sso-gsuite-step-04.png)

It's very important to send this file to your support contact at Supabase to complete the SSO setup process. If you're not sure where to send this file, you can always reach out to [Supabase Support](https://supabase.help).

**Important: Make sure the certificate as shown on screen has at least 1 year before it expires. Mark down this date in your calendar so you will be reminded that you need to update the certificate without any downtime for your users.**


## Step 5: Add service provider details \[#add-service-provider-details]

Fill out these service provider details on the next screen.

| Detail         | Value                                               |
| -------------- | --------------------------------------------------- |
| ACS URL        | `https://alt.supabase.io/auth/v1/sso/saml/acs`      |
| Entity ID      | `https://alt.supabase.io/auth/v1/sso/saml/metadata` |
| Start URL      | `https://supabase.com/dashboard`                    |
| Name ID format | PERSISTENT                                          |
| Name ID        | *Basic Information > Primary email*                 |

![Google Workspace: Web and mobile apps admin console, Add custom SAML, Service provider details screen](/docs/img/sso-gsuite-step-05.png)


## Step 6: Configure attribute mapping \[#configure-attribute-mapping]

Attribute mappings allow Supabase to get information about your Google Workspace users on each login.

**A *Primary email* to `email` mapping is required.** Other mappings shown below are optional and configurable depending on your Google Workspace setup. If in doubt, replicate the same config as shown.

Share any changes, if any, from this screen with your Supabase support contact.

![Google Workspace: Web and mobile apps admin console, Add custom SAML, Attribute mapping](/docs/img/sso-gsuite-step-06.png)


## Step 7: Wait for confirmation \[#confirmation]

Once you’ve configured the Google Workspace app as shown above, make sure you send the [metadata file you downloaded](#download-idp-metadata) and information regarding the [attribute mapping](#configure-attribute-mappings) (if any changes are applicable) to your support contact at Supabase.

This information needs to be entered into Supabase before SSO is activated end-to-end.

Wait for confirmation that this information has successfully been added to Supabase. It usually takes us 1 business day to configure this information for you.


## Step 8: Configure user access \[#configure-user-access]

You can configure which Google Workspace user accounts will get access to Supabase. This is important if you wish to limit access to your software engineering teams.

You can configure this access by clicking on the *User access* card (or down-arrow). Follow the instructions on screen.

Changes from this step sometimes take a while to propagate across Google’s systems. Wait at least 15 minutes before proceeding to the next step.

![Google Workspace: Web and mobile apps admin console, Supabase app screen](/docs/img/sso-gsuite-step-08.png)


## Step 9: Test single sign-on \[#testing]

Once you’ve turned on access to Supabase for users in your organization, ask one of those users to help you out in testing the setup.

It often helps to ask them to log out of their Google account and log back in.

Ask them to enter their email address in the [Sign in with SSO](https://supabase.com/dashboard/sign-in-sso) page.

If sign in is not working correctly, reach out to your support contact at Supabase.


# Set Up SSO with Okta



Supabase supports single sign-on (SSO) using Okta.


## Step 1: Choose to create an app integration in the applications dashboard \[#create-app-integration]

Navigate to the Applications dashboard of the Okta admin console. Click *Create App Integration*.

![Okta dashboard: Create App Integration button](/docs/img/sso-okta-step-01.png)


## Step 2: Choose SAML 2.0 in the app integration dialog \[#create-saml-app]

Supabase supports the SAML 2.0 SSO protocol. Choose it from the *Create a new app integration* dialog.

![Okta dashboard: Create new app integration dialog](/docs/img/sso-okta-step-02.png)


## Step 3: Fill out general settings \[#add-general-settings]

The information you enter here is for visibility into your Okta applications menu. You can choose any values you like. `Supabase` as a name works well for most use cases.

![Okta dashboard: Create SAML Integration wizard](/docs/img/sso-okta-step-03.png)


## Step 4: Fill out SAML settings \[#add-saml-settings]

These settings let Supabase use SAML 2.0 properly with your Okta application. Make sure you enter this information exactly as shown on in this table and screenshot.

| Setting                                        | Value                                               |
| ---------------------------------------------- | --------------------------------------------------- |
| Single sign-on URL                             | `https://alt.supabase.io/auth/v1/sso/saml/acs`      |
| Use this for Recipient URL and Destination URL | ✔️                                                  |
| Audience URI (SP Entity ID)                    | `https://alt.supabase.io/auth/v1/sso/saml/metadata` |
| Default `RelayState`                           | `https://supabase.com/dashboard`                    |
| Name ID format                                 | `EmailAddress`                                      |
| Application username                           | Email                                               |
| Update application username on                 | Create and update                                   |

![Okta dashboard: Create SAML Integration wizard, Configure SAML step](/docs/img/sso-okta-step-04.png)


## Step 5: Fill out attribute statements \[#add-attribute-statements]

Attribute Statements allow Supabase to get information about your Okta users on each login.

**A `email` to `user.email` statement is required.** Other mappings shown below are optional and configurable depending on your Okta setup. If in doubt, replicate the same config as shown.

Share any changes, if any, from this screen with your Supabase support contact.

![Okta dashboard: Attribute Statements configuration screen](/docs/img/sso-okta-step-05.png)


## Step 6: Obtain IdP metadata URL \[#idp-metadata-url]

Supabase needs to finalize enabling single sign-on with your Okta application.

To do this scroll down to the *SAML Signing Certificates* section on the *Sign On* tab of the *Supabase* application. Pick the the *SHA-2* row with an *Active* status. Click on the *Actions* dropdown button and then on the *View IdP Metadata*.

This will open up the SAML 2.0 Metadata XML file in a new tab in your browser. Copy this URL and send it to your support contact and await further instructions. If you're not clear who to send this link to or need further assistance, contact [Supabase Support](https://supabase.help).

The link usually has this structure: `https://<okta-org>.okta.com/apps/<app-id>/sso/saml/metadata`

![Okta dashboard: SAML Signing Certificates, Actions button highlighted](/docs/img/sso-okta-step-06.png)


## Step 7: Wait for confirmation \[#confirmation]

Once you’ve configured the Okta app as shown above, make sure you send the [metadata URL](#idp-metadata-url) and information regarding the [attribute statements](#add-attribute-statements) (if any changes are applicable) to your support contact at Supabase.

Wait for confirmation that this information has successfully been added to Supabase. It usually takes us 1 business day to configure this information for you.


## Step 8: Test single sign-on \[#testing]

Once you’ve received confirmation from your support contact at Supabase that SSO setup has been completed for your enterprise, you can ask some of your users to sign in via their Okta account.

You ask them to enter their email address on the [Sign in with SSO](https://supabase.com/dashboard/sign-in-sso) page.

If sign in is not working correctly, reach out to your support contact at Supabase for further guidance.


# Upgrading



Supabase ships fast and we endeavor to add all new features to existing projects wherever possible. In some cases, access to new features require upgrading or migrating your Supabase project.

You can upgrade your project using `pg_upgrade` or by pausing and restoring your project.


## `pg_upgrade`

pg\_upgrade performs an in-place upgrade on your database. For projects larger than 1GB, pg\_upgrade is generally faster than a pause+restore cycle, and the speed advantage grows with the size of the database.

1.  Plan for an appropriate downtime window, and ensure you have reviewed the [caveats](#caveats) section of this document before executing the upgrade.
2.  Use the "Upgrade project" button on the [Infrastructure](https://supabase.com/dashboard/project/_/settings/infrastructure) section of your dashboard.

Additionally, if a pg\_upgrade upgrade should fail, your original DB would be brought back up online and be able to service requests.

As a rough rule of thumb, pg\_upgrade operates at ~100MBps (when executing an upgrade on your data). Using the size of your database, you can use this metric to derive an approximate sense of the downtime window necessary for the upgrade. During this window, you should plan for your DB and associated services to be unavailable.


## Pause and restore

When you pause and restore a project, the restored database includes the latest features. This method *does* include downtime, so be aware that your project will be inaccessible for a short period of time.

1.  On the [General Settings](https://supabase.com/dashboard/project/_/settings/general) page in the Dashboard, click **Pause project**. You will be redirected to the home screen as your project is pausing. This process can take several minutes.
2.  After your project is paused, click **Restore project**. The restoration can take several minutes depending on how much data your database has. You will receive an email once the restoration is complete.

Note that a pause + restore upgrade involves tearing down your project's resources before bringing them back up again. If the restore process should fail, manual intervention from Supabase support will be required to bring your project back online.


### Caveats

Regardless of the upgrade method, a few caveats apply:


#### Logical replication

If you are using logical replication, the replication slots will not be preserved by the upgrade process. You will need to manually recreate them after the upgrade with the method `pg_create_logical_replication_slot`. Refer to the Postgres docs on [Replication Management Functions](https://www.postgresql.org/docs/current/functions-admin.html#FUNCTIONS-REPLICATION) for more details about the method.


#### Breaking changes

Newer versions of services can break functionality or change the performance characteristics you rely on. If your project is eligible for an upgrade, you will be able to find your current service versions from within [the Supabase dashboard](https://supabase.com/dashboard/project/_/settings/infrastructure).

Breaking changes are generally only present in major version upgrades of Postgres and PostgREST. You can find their respective release notes at:

*   [Postgres](https://www.postgresql.org/docs/release/)
*   [PostgREST](https://github.com/PostgREST/postgrest/releases)

If you are upgrading from a significantly older version, you will need to consider the release notes for any intermediary releases as well.


#### Time limits

Starting from 2024-06-24, when a project is paused, users then have a 90-day window to restore the project on the platform from within Supabase Studio.

The 90-day window allows Supabase to introduce platform changes that may not be backwards compatible with older backups. Unlike active projects, static backups can't be updated to accommodate such changes.

During the 90-day restore window a paused project can be restored to the platform with a single button click from [Studio's dashboard page](https://supabase.com/dashboard/projects).

After the 90-day restore window, you can download your project's backup file, and Storage objects from the project dashboard. See [restoring a backup locally](/docs/guides/local-development/restoring-downloaded-backup) for instructions on how to load that backup locally to recover your data.

If you upgrade to a paid plan while your project is paused, any expired one-click restore options are reenabled. Since the backup was taken outside the backwards compatibility window, it may fail to restore. If you have a problem restoring your backup after upgrading, contact [Support](/support).


#### Disk sizing

When upgrading, the Supabase platform will "right-size" your disk based on the current size of the database. For example, if your database is 100GB in size, and you have a 200GB disk, the upgrade will reduce the disk size to 120GB (1.2x the size of your database).


#### Objects dependent on Postgres extensions

pg\_upgrade does not support upgrading of databases containing reg\* data types referencing system OIDs.
If you have created any objects that depend on the following extensions, you will need to recreate them after the upgrade.


#### `pg_cron` records

[pg\_cron](https://github.com/citusdata/pg_cron#viewing-job-run-details) does not automatically clean up historical records. This can lead to extremely large `cron.job_run_details` tables if the records are not regularly pruned; you should clean unnecessary records from this table prior to an upgrade.

During the `pg_upgrade` process, the `pg_cron` extension gets dropped and recreated. Prior to this process, the `cron.job_run_details` table is duplicated to avoid losing historical logs. The instantaneous disk pressure created by duplicating an extremely large details table can cause at best unnecessary performance degradation, or at worst, upgrade process failures.


#### Extensions

pg\_upgrade does not currently support upgrading of databases using extensions older than the following versions:

*   TimescaleDB 2.16.1
*   plv8 3.1.10

To upgrade to a newer version of Postgres, you will need to drop the extensions before the upgrade, and recreate them after the upgrade.


#### Authentication method changes - deprecating md5 in favor of scram-sha-256

The md5 hashing method has [known weaknesses](https://en.wikipedia.org/wiki/MD5#Security) that make it unsuitable for cryptography.
As such, we are deprecating md5 in favor of [scram-sha-256](https://www.postgresql.org/docs/current/auth-password.html), which is the default and most secure authentication method used in the latest Postgres versions.

We automatically migrate Supabase-managed roles' passwords to scram-sha-256 during the upgrade process, but you will need to manually migrate the passwords of any custom roles you have created, else you won't be able to connect using them after the upgrade.

To identify roles using the md5 hashing method and migrate their passwords, you can use the following SQL statements after the upgrade:

```sql
-- List roles using md5 hashing method
SELECT
  rolname
FROM pg_authid
WHERE rolcanlogin = true
  AND rolpassword LIKE 'md5%';

-- Migrate a role's password to scram-sha-256
ALTER ROLE <role_name> WITH PASSWORD '<password>';
```


#### Database size reduction

As part of the upgrade process, maintenance operations such as [vacuuming](https://www.postgresql.org/docs/current/routine-vacuuming.html#ROUTINE-VACUUMING) are also executed. This can result in a reduction in the reported database size.


#### Post-upgrade validation

Supabase performs extensive pre- and post-upgrade validations to ensure that the database has been correctly upgraded. However, you should plan for your own application-level validations, as there might be changes you might not have anticipated, and this should be budgeted for when planning your downtime window.


# Your monthly invoice



## Billing cycle

When you sign up for a paid plan you get charged once a month at the beginning of the billing cycle. A billing cycle starts with the creation of a Supabase organization. If you create an organization on the sixth of January your billing cycle resets on the sixth of each month. If the anchored day is not present in the current month, then the last day of the month is used.


## Your invoice explained

When your billing cycle resets an invoice gets issued. That invoice contains line items from both the current and the previous billing cycle. Fixed fees for the current billing cycle, usage based fees for the previous billing cycle.


### Fixed fees

Fixed fees are independent of usage and paid in-advance. Whether you have one or several projects, hundreds or millions of active users, the fee is always the same, and doesn't vary. Examples are the subscription fee, the fee for HIPAA and for priority support.


### Usage based fees

Fees vary depending on usage and are paid in arrears. The more usage you have, the higher the fee. Examples are fees for monthly active users and storage size.


### Discounted line items

Paid plans come with a usage quota for certain line items. You only pay for usage that goes beyond the quota. The quota for Storage for example is 100 GB. If you use 105 GB, you pay for 5 GB. If you use 95 GB, you pay nothing. This quota is declared as a discount on your invoice.


#### Compute Credits

Paid plans come with $10 in Compute Credits per month. This suffices for a single project using a Nano or Micro compute instance. Every additional project adds compute fees to your monthly invoice though.


### Example invoice

The following invoice was issued on January 6, 2025 with the previous billing cycle from December 6, 2024 - January 5, 2025, and the current billing cycle from January 6 - February 5, 2025.

1.  The final amount due
2.  Fixed subscription fee for the current billing cycle
3.  Usage based fee for Compute for the previous billing cycle. There were two projects (`wsmmedyqtlrvbcesxdew`, `wwxdpovgtfcmcnxwsaad`) running 744 hours (24 hours \* 31 days). These projects incurred $10 in Compute fees each. With $10 in Compute Credits deducted, the final Compute fees are $10.
4.  Usage based fee for Custom Domain for the previous billing cycle. There is no free usage quota for Custom Domain. You get charged for the 744 hours (24 hours \* 31 days) a Custom Domain was active. The final Custom Domain fees are $10.19.
5.  Usage based fee for Egress for the previous billing cycle. There is a free usage quota of 250 GB for Egress. You get charged for usage beyond 250 GB only, meaning for 2,119.47 GB. The final Egress fees are $190.75.
6.  Usage based fee for Monthly Active Users for the previous billing cycle. There is a free usage quota of 100,000 users. With 141 users there is no charge for this line item.


### Why is my invoice more than $25?

The amount due of your invoice being higher than the $25 subscription fee for the Pro Plan can have several reasons.

*   **Running several projects:** You had more than one project running in the previous billing cycle. Supabase provides a dedicated server and database for every project. That means that every project you launch incurs compute costs. While the $10 Compute Credits cover a single project using a Nano or Micro compute instance, every additional project adds at least $10 compute costs to your invoice.
*   **Usage beyond quota:** You exceeded the included usage quota for one or more line items in the previous billing cycle while having the Spend Cap disabled.
*   **Usage that is not covered by the Spend Cap:** You had usage in the previous billing cycle that is not covered by the [Spend Cap](/docs/guides/platform/cost-control#spend-cap). For example using an IPv4 address or a custom domain.


## How to settle your invoices

Monthly invoices are auto-collected by charging the payment method marked as "active" for an organization.


### Payment failure

If your payment fails, Supabase retries the charge several times. We send you a Payment Failure email with the reason for the failure. Follow the steps outlined in this email. You can manually trigger a charge at any time via

*   the link in the Payment Failure email
*   the "Pay Now" button on the [organization's invoices page](https://supabase.com/dashboard/org/_/billing#invoices)


## Where to find your invoices

Your invoice is sent to you via email. You can also find your invoices on the [organization's invoices page](https://supabase.com/dashboard/org/_/billing#invoices).


# Supabase Queues

Durable Message Queues with Guaranteed Delivery in Postgres

Supabase Queues is a Postgres-native durable Message Queue system with guaranteed delivery built on the [pgmq database extension](https://github.com/tembo-io/pgmq). It offers developers a seamless way to persist and process Messages in the background while improving the resiliency and scalability of their applications and services.

Queues couples the reliability of Postgres with the simplicity Supabase's platform and developer experience, enabling developers to manage Background Tasks with zero configuration.


## Features

*   **Postgres Native**

    Built on top of the `pgmq` database extension, create and manage Queues with any Postgres tooling.
*   **Guaranteed Message Delivery**

    Messages added to Queues are guaranteed to be delivered to your consumers.
*   **Exactly Once Message Delivery**
    A Message is delivered exactly once to a consumer within a customizable visibility window.
*   **Message Durability and Archival**

    Messages are stored in Postgres and you can choose to archive them for analytical or auditing purposes.
*   **Granular Authorization**

    Control client-side consumer access to Queues with API permissions and Row Level Security (RLS) policies.
*   **Queue Management and Monitoring**

    Create, manage, and monitor Queues and Messages in the Supabase Dashboard.


## Resources

*   [Quickstart](/docs/guides/queues/quickstart)
*   [API Reference](/docs/guides/queues/api)
*   [`pgmq` GitHub Repository](https://github.com/tembo-io/pgmq)


# API



When you create a Queue in Supabase, you can choose to create helper database functions in the `pgmq_public` schema. This schema exposes operations to manage Queue Messages to consumers client-side, but does not expose functions for creating or dropping Queues.

Database functions in `pgmq_public` can be exposed via Supabase Data API so consumers client-side can call them. Visit the [Quickstart](/docs/guides/queues/quickstart) for an example.


### `pgmq_public.pop(queue_name)`

Retrieves the next available message and deletes it from the specified Queue.

*   `queue_name` (`text`): Queue name

***


### `pgmq_public.send(queue_name, message, sleep_seconds)`

Adds a Message to the specified Queue, optionally delaying its visibility to all consumers by a number of seconds.

*   `queue_name` (`text`): Queue name
*   `message` (`jsonb`): Message payload to send
*   `sleep_seconds` (`integer`, optional): Delay message visibility by specified seconds. Defaults to 0

***


### `pgmq_public.send_batch(queue_name, messages, sleep_seconds)`

Adds a batch of Messages to the specified Queue, optionally delaying their availability to all consumers by a number of seconds.

*   `queue_name` (`text`): Queue name
*   `messages` (`jsonb[]`): Array of message payloads to send
*   `sleep_seconds` (`integer`, optional): Delay messages visibility by specified seconds. Defaults to 0

***


### `pgmq_public.archive(queue_name, message_id)`

Archives a Message by moving it from the Queue table to the Queue's archive table.

*   `queue_name` (`text`): Queue name
*   `message_id` (`bigint`): ID of the Message to archive

***


### `pgmq_public.delete(queue_name, message_id)`

Permanently deletes a Message from the specified Queue.

*   `queue_name` (`text`): Queue name
*   `message_id` (`bigint`): ID of the Message to delete

***


### `pgmq_public.read(queue_name, sleep_seconds, n)`

Reads up to "n" Messages from the specified Queue with an optional "sleep\_seconds" (visibility timeout).

*   `queue_name` (`text`): Queue name
*   `sleep_seconds` (`integer`): Visibility timeout in seconds
*   `n` (`integer`): Maximum number of Messages to read


# PGMQ Extension



pgmq is a lightweight message queue built on Postgres.


## Features

*   Lightweight - No background worker or external dependencies, just Postgres functions packaged in an extension
*   "exactly once" delivery of messages to a consumer within a visibility timeout
*   API parity with AWS SQS and RSMQ
*   Messages stay in the queue until explicitly removed
*   Messages can be archived, instead of deleted, for long-term retention and replayability


## Enable the extension

```sql
create extension pgmq;
```


## Usage \[#get-usage]


### Queue management


#### `create`

Create a new queue.

```sql
pgmq.create(queue_name text)
returns void
```

**Parameters:**

| Parameter  | Type | Description           |
| :--------- | :--- | :-------------------- |
| queue\_name | text | The name of the queue |

Example:

```sql
select from pgmq.create('my_queue');
 create
--------
```


#### `create_unlogged`

Creates an unlogged table. This is useful when write throughput is more important than durability.
See Postgres documentation for [unlogged tables](https://www.postgresql.org/docs/current/sql-createtable.html#SQL-CREATETABLE-UNLOGGED) for more information.

```sql
pgmq.create_unlogged(queue_name text)
returns void
```

**Parameters:**

| Parameter  | Type | Description           |
| :--------- | :--- | :-------------------- |
| queue\_name | text | The name of the queue |

Example:

```sql
select pgmq.create_unlogged('my_unlogged');
 create_unlogged
-----------------
```

***


#### `detach_archive`

Drop the queue's archive table as a member of the PGMQ extension. Useful for preventing the queue's archive table from being drop when `drop extension pgmq` is executed.
This does not prevent the further archives() from appending to the archive table.

```sql
pgmq.detach_archive(queue_name text)
```

**Parameters:**

| Parameter  | Type | Description           |
| :--------- | :--- | :-------------------- |
| queue\_name | text | The name of the queue |

Example:

```sql
select * from pgmq.detach_archive('my_queue');
 detach_archive
----------------
```

***


#### `drop_queue`

Deletes a queue and its archive table.

```sql
pgmq.drop_queue(queue_name text)
returns boolean
```

**Parameters:**

| Parameter  | Type | Description           |
| :--------- | :--- | :-------------------- |
| queue\_name | text | The name of the queue |

Example:

```sql
select * from pgmq.drop_queue('my_unlogged');
 drop_queue
------------
 t
```


### Sending messages


#### `send`

Send a single message to a queue.

```sql
pgmq.send(
    queue_name text,
    msg jsonb,
    delay integer default 0
)
returns setof bigint
```

**Parameters:**

| Parameter    | Type      | Description                                                        |
| :----------- | :-------- | :----------------------------------------------------------------- |
| `queue_name` | `text`    | The name of the queue                                              |
| `msg`        | `jsonb`   | The message to send to the queue                                   |
| `delay`      | `integer` | Time in seconds before the message becomes visible. Defaults to 0. |

Example:

```sql
select * from pgmq.send('my_queue', '{"hello": "world"}');
 send
------
    4
```

***


#### `send_batch`

Send 1 or more messages to a queue.

```sql
pgmq.send_batch(
    queue_name text,
    msgs jsonb[],
    delay integer default 0
)
returns setof bigint
```

**Parameters:**

| Parameter    | Type      | Description                                                         |
| :----------- | :-------- | :------------------------------------------------------------------ |
| `queue_name` | `text`    | The name of the queue                                               |
| `msgs`       | `jsonb[]` | Array of messages to send to the queue                              |
| `delay`      | `integer` | Time in seconds before the messages becomes visible. Defaults to 0. |

```sql
select * from pgmq.send_batch(
    'my_queue',
    array[
      '{"hello": "world_0"}'::jsonb,
      '{"hello": "world_1"}'::jsonb
    ]
);
 send_batch
------------
          1
          2
```

***


### Reading messages


#### `read`

Read 1 or more messages from a queue. The VT specifies the delay in seconds between reading and the message becoming invisible to other consumers.

```sql
pgmq.read(
    queue_name text,
    vt integer,
    qty integer
)

returns setof pgmq.message_record
```

**Parameters:**

| Parameter    | Type      | Description                                                     |
| :----------- | :-------- | :-------------------------------------------------------------- |
| `queue_name` | `text`    | The name of the queue                                           |
| `vt`         | `integer` | Time in seconds that the message become invisible after reading |
| `qty`        | `integer` | The number of messages to read from the queue. Defaults to 1    |

Example:

```sql
select * from pgmq.read('my_queue', 10, 2);
 msg_id | read_ct |          enqueued_at          |              vt               |       message
--------+---------+-------------------------------+-------------------------------+----------------------
      1 |       1 | 2023-10-28 19:14:47.356595-05 | 2023-10-28 19:17:08.608922-05 | {"hello": "world_0"}
      2 |       1 | 2023-10-28 19:14:47.356595-05 | 2023-10-28 19:17:08.608974-05 | {"hello": "world_1"}
(2 rows)
```

***


#### `read_with_poll`

Same as read(). Also provides convenient long-poll functionality.
When there are no messages in the queue, the function call will wait for `max_poll_seconds` in duration before returning.
If messages reach the queue during that duration, they will be read and returned immediately.

```sql
 pgmq.read_with_poll(
    queue_name text,
    vt integer,
    qty integer,
    max_poll_seconds integer default 5,
    poll_interval_ms integer default 100
)
returns setof pgmq.message_record
```

**Parameters:**

| Parameter          | Type      | Description                                                                 |
| :----------------- | :-------- | :-------------------------------------------------------------------------- |
| `queue_name`       | `text`    | The name of the queue                                                       |
| `vt`               | `integer` | Time in seconds that the message become invisible after reading.            |
| `qty`              | `integer` | The number of messages to read from the queue. Defaults to 1.               |
| `max_poll_seconds` | `integer` | Time in seconds to wait for new messages to reach the queue. Defaults to 5. |
| `poll_interval_ms` | `integer` | Milliseconds between the internal poll operations. Defaults to 100.         |

Example:

```sql
select * from pgmq.read_with_poll('my_queue', 1, 1, 5, 100);
 msg_id | read_ct |          enqueued_at          |              vt               |      message
--------+---------+-------------------------------+-------------------------------+--------------------
      1 |       1 | 2023-10-28 19:09:09.177756-05 | 2023-10-28 19:27:00.337929-05 | {"hello": "world"}
```

***


#### `pop`

Reads a single message from a queue and deletes it upon read.

Note: utilization of pop() results in at-most-once delivery semantics if the consuming application does not guarantee processing of the message.

```sql
pgmq.pop(queue_name text)
returns setof pgmq.message_record
```

**Parameters:**

| Parameter  | Type | Description           |
| :--------- | :--- | :-------------------- |
| queue\_name | text | The name of the queue |

Example:

```sql
pgmq=# select * from pgmq.pop('my_queue');
 msg_id | read_ct |          enqueued_at          |              vt               |      message
--------+---------+-------------------------------+-------------------------------+--------------------
      1 |       2 | 2023-10-28 19:09:09.177756-05 | 2023-10-28 19:27:00.337929-05 | {"hello": "world"}
```

***


### Deleting/Archiving messages


#### `delete` (single)

Deletes a single message from a queue.

```sql
pgmq.delete (queue_name text, msg_id: bigint)
returns boolean
```

**Parameters:**

| Parameter    | Type     | Description                         |
| :----------- | :------- | :---------------------------------- |
| `queue_name` | `text`   | The name of the queue               |
| `msg_id`     | `bigint` | Message ID of the message to delete |

Example:

```sql
select pgmq.delete('my_queue', 5);
 delete
--------
 t
```

***


#### `delete` (batch)

Delete one or many messages from a queue.

```sql
pgmq.delete (queue_name text, msg_ids: bigint[])
returns setof bigint
```

**Parameters:**

| Parameter    | Type       | Description                    |
| :----------- | :--------- | :----------------------------- |
| `queue_name` | `text`     | The name of the queue          |
| `msg_ids`    | `bigint[]` | Array of message IDs to delete |

Examples:

Delete two messages that exist.

```sql
select * from pgmq.delete('my_queue', array[2, 3]);
 delete
--------
      2
      3
```

Delete two messages, one that exists and one that does not. Message `999` does not exist.

```sql
select * from pgmq.delete('my_queue', array[6, 999]);
 delete
--------
      6
```

***


#### `purge_queue`

Permanently deletes all messages in a queue. Returns the number of messages that were deleted.

```text
purge_queue(queue_name text)
returns bigint
```

**Parameters:**

| Parameter  | Type | Description           |
| :--------- | :--- | :-------------------- |
| queue\_name | text | The name of the queue |

Example:

Purge the queue when it contains 8 messages;

```sql
select * from pgmq.purge_queue('my_queue');
 purge_queue
-------------
           8
```

***


#### `archive` (single)

Removes a single requested message from the specified queue and inserts it into the queue's archive.

```sql
pgmq.archive(queue_name text, msg_id bigint)
returns boolean
```

**Parameters:**

| Parameter    | Type     | Description                          |
| :----------- | :------- | :----------------------------------- |
| `queue_name` | `text`   | The name of the queue                |
| `msg_id`     | `bigint` | Message ID of the message to archive |

Returns
Boolean value indicating success or failure of the operation.

Example; remove message with ID 1 from queue `my_queue` and archive it:

```sql
select * from pgmq.archive('my_queue', 1);
 archive
---------
       t
```

***


#### `archive` (batch)

Deletes a batch of requested messages from the specified queue and inserts them into the queue's archive.
Returns an array of message ids that were successfully archived.

```text
pgmq.archive(queue_name text, msg_ids bigint[])
RETURNS SETOF bigint
```

**Parameters:**

| Parameter    | Type       | Description                     |
| :----------- | :--------- | :------------------------------ |
| `queue_name` | `text`     | The name of the queue           |
| `msg_ids`    | `bigint[]` | Array of message IDs to archive |

Examples:

Delete messages with ID 1 and 2 from queue `my_queue` and move to the archive.

```sql
select * from pgmq.archive('my_queue', array[1, 2]);
 archive
---------
       1
       2
```

Delete messages 4, which exists and 999, which does not exist.

```sql
select * from pgmq.archive('my_queue', array[4, 999]);
 archive
---------
       4
```

***


### Utilities


#### `set_vt`

Sets the visibility timeout of a message to a specified time duration in the future. Returns the record of the message that was updated.

```sql
pgmq.set_vt(
    queue_name text,
    msg_id bigint,
    vt_offset integer
)
returns pgmq.message_record
```

**Parameters:**

| Parameter    | Type      | Description                                                           |
| :----------- | :-------- | :-------------------------------------------------------------------- |
| `queue_name` | `text`    | The name of the queue                                                 |
| `msg_id`     | `bigint`  | ID of the message to set visibility time                              |
| `vt_offset`  | `integer` | Duration from now, in seconds, that the message's VT should be set to |

Example:

Set the visibility timeout of message 1 to 30 seconds from now.

```sql
select * from pgmq.set_vt('my_queue', 11, 30);
 msg_id | read_ct |          enqueued_at          |              vt               |       message
--------+---------+-------------------------------+-------------------------------+----------------------
     1 |       0 | 2023-10-28 19:42:21.778741-05 | 2023-10-28 19:59:34.286462-05 | {"hello": "world_0"}
```

***


#### `list_queues`

List all the queues that currently exist.

```sql
list_queues()
RETURNS TABLE(
    queue_name text,
    created_at timestamp with time zone,
    is_partitioned boolean,
    is_unlogged boolean
)
```

Example:

```sql
select * from pgmq.list_queues();
      queue_name      |          created_at           | is_partitioned | is_unlogged
----------------------+-------------------------------+----------------+-------------
 my_queue             | 2023-10-28 14:13:17.092576-05 | f              | f
 my_partitioned_queue | 2023-10-28 19:47:37.098692-05 | t              | f
 my_unlogged          | 2023-10-28 20:02:30.976109-05 | f              | t
```

***


#### `metrics`

Get metrics for a specific queue.

```sql
pgmq.metrics(queue_name: text)
returns table(
    queue_name text,
    queue_length bigint,
    newest_msg_age_sec integer,
    oldest_msg_age_sec integer,
    total_messages bigint,
    scrape_time timestamp with time zone
)
```

**Parameters:**

| Parameter  | Type | Description           |
| :--------- | :--- | :-------------------- |
| queue\_name | text | The name of the queue |

**Returns:**

| Attribute            | Type                       | Description                                                               |
| :------------------- | :------------------------- | :------------------------------------------------------------------------ | -------------------------------------------------- |
| `queue_name`         | `text`                     | The name of the queue                                                     |
| `queue_length`       | `bigint`                   | Number of messages currently in the queue                                 |
| `newest_msg_age_sec` | `integer                   | null`                                                                     | Age of the newest message in the queue, in seconds |
| `oldest_msg_age_sec` | `integer                   | null`                                                                     | Age of the oldest message in the queue, in seconds |
| `total_messages`     | `bigint`                   | Total number of messages that have passed through the queue over all time |
| `scrape_time`        | `timestamp with time zone` | The current timestamp                                                     |

Example:

```sql
select * from pgmq.metrics('my_queue');
 queue_name | queue_length | newest_msg_age_sec | oldest_msg_age_sec | total_messages |          scrape_time
------------+--------------+--------------------+--------------------+----------------+-------------------------------
 my_queue   |           16 |               2445 |               2447 |             35 | 2023-10-28 20:23:08.406259-05
```

***


#### `metrics_all`

Get metrics for all existing queues.

```text
pgmq.metrics_all()
RETURNS TABLE(
    queue_name text,
    queue_length bigint,
    newest_msg_age_sec integer,
    oldest_msg_age_sec integer,
    total_messages bigint,
    scrape_time timestamp with time zone
)
```

**Returns:**

| Attribute            | Type                       | Description                                                               |
| :------------------- | :------------------------- | :------------------------------------------------------------------------ | -------------------------------------------------- |
| `queue_name`         | `text`                     | The name of the queue                                                     |
| `queue_length`       | `bigint`                   | Number of messages currently in the queue                                 |
| `newest_msg_age_sec` | `integer                   | null`                                                                     | Age of the newest message in the queue, in seconds |
| `oldest_msg_age_sec` | `integer                   | null`                                                                     | Age of the oldest message in the queue, in seconds |
| `total_messages`     | `bigint`                   | Total number of messages that have passed through the queue over all time |
| `scrape_time`        | `timestamp with time zone` | The current timestamp                                                     |

```sql
select * from pgmq.metrics_all();
      queue_name      | queue_length | newest_msg_age_sec | oldest_msg_age_sec | total_messages |          scrape_time
----------------------+--------------+--------------------+--------------------+----------------+-------------------------------
 my_queue             |           16 |               2563 |               2565 |             35 | 2023-10-28 20:25:07.016413-05
 my_partitioned_queue |            1 |                 11 |                 11 |              1 | 2023-10-28 20:25:07.016413-05
 my_unlogged          |            1 |                  3 |                  3 |              1 | 2023-10-28 20:25:07.016413-05
```


### Types


#### `message_record`

The complete representation of a message in a queue.

| Attribute Name | Type                       | Description                                                            |
| :------------- | :------------------------- | :--------------------------------------------------------------------- |
| `msg_id`       | `bigint`                   | Unique ID of the message                                               |
| `read_ct`      | `bigint`                   | Number of times the message has been read. Increments on read().       |
| `enqueued_at`  | `timestamp with time zone` | time that the message was inserted into the queue                      |
| `vt`           | `timestamp with time zone` | Timestamp when the message will become available for consumers to read |
| `message`      | `jsonb`                    | The message payload                                                    |

Example:

```sql
 msg_id | read_ct |          enqueued_at          |              vt               |      message
--------+---------+-------------------------------+-------------------------------+--------------------
      1 |       1 | 2023-10-28 19:06:19.941509-05 | 2023-10-28 19:06:27.419392-05 | {"hello": "world"}
```


## Resources

*   Official Docs: [pgmq/api](https://tembo.io/pgmq/#creating-a-queue)


# 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](/docs/guides/queues/api) 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.

*   **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.

On the [Queues page](/dashboard/project/_/integrations/queues/queues):

*   Click **Add a new queue** button

<!---->

*   Name your queue

<!---->

*   Select your [Queue Type](#queue-types)


### What happens when you create a queue?

Every new Queue creates two tables in the `pgmq` schema. These tables are `pgmq.q_<queue_name>` to store and process active messages and `pgmq.a_<queue_name>` to store any archived messages.

A "Basic Queue" will create `pgmq.q_<queue_name>` and `pgmq.a_<queue_name>` tables as logged tables.

However, an "Unlogged Queue" will create `pgmq.q_<queue_name>` as an unlogged table for better performance while sacrificing durability. The `pgmq.a_<queue_name>` table will still be 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.

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.


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


### 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:

| **Operations**      | **Permissions Required** |
| ------------------- | ------------------------ |
| `send` `send_batch` | `Select` `Insert`        |
| `read` `pop`        | `Select` `Update`        |
| `archive` `delete`  | `Select` `Delete`        |

To manage your queue permissions, click on the Queue Settings button.

Then enable the required roles permissions.


### Enqueueing and dequeueing messages

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

Here's a TypeScript example using the official Supabase client library:

```tsx
import { createClient } from '@supabase/supabase-js'

const supabaseUrl = 'supabaseURL'
const supabaseKey = 'supabaseKey'

const supabase = createClient(supabaseUrl, supabaseKey)

const QueuesTest: React.FC = () => {
  //Add a Message
  const sendToQueue = async () => {
    const result = await supabase.schema('pgmq_public').rpc('send', {
      queue_name: 'foo',
      message: { hello: 'world' },
      sleep_seconds: 30,
    })
    console.log(result)
  }

  //Dequeue Message
  const popFromQueue = async () => {
    const result = await supabase.schema('pgmq_public').rpc('pop', { queue_name: 'foo' })
    console.log(result)
  }

  return (
    <div className="p-6">
      <h2 className="text-2xl font-bold mb-4">Queue Test Component</h2>
      <button
        onClick={sendToQueue}
        className="bg-blue-500 text-white px-4 py-2 rounded hover:bg-blue-600 mr-4"
      >
        Add Message
      </button>
      <button
        onClick={popFromQueue}
        className="bg-blue-500 text-white px-4 py-2 rounded hover:bg-blue-600"
      >
        Pop Message
      </button>
    </div>
  )
}

export default QueuesTest
```


# Realtime

Send and receive messages to connected clients.

Supabase provides a globally distributed [Realtime](https://github.com/supabase/realtime) service with the following features:

*   [Broadcast](/docs/guides/realtime/broadcast): Send low-latency messages using the client libraries, REST, or your Database.
*   [Presence](/docs/guides/realtime/presence): Track and synchronize shared state between users.
*   [Postgres Changes](/docs/guides/realtime/postgres-changes): Listen to Database changes and send them to authorized users.


## Examples


## Resources

Find the source code and documentation in the Supabase GitHub repository.


# Realtime Architecture



Realtime is a globally distributed Elixir cluster. Clients can connect to any node in the cluster via WebSockets and send messages to any other client connected to the cluster.

Realtime is written in [Elixir](https://elixir-lang.org/), which compiles to [Erlang](https://www.erlang.org/), and utilizes many tools the [Phoenix Framework](https://www.phoenixframework.org/) provides out of the box.

![Global Architecture](/docs/img/guides/realtime/realtime-arch.png)


## Elixir & Phoenix

Phoenix is fast and able to handle millions of concurrent connections.

Phoenix can handle many concurrent connections because Elixir provides lightweight processes (not OS processes) to work with.

Client-facing WebSocket servers need to handle many concurrent connections. Elixir & Phoenix let the Supabase Realtime cluster do this easily.


## Channels

Channels are implemented using [Phoenix Channels](https://hexdocs.pm/phoenix/channels.html) which uses [Phoenix.PubSub](https://hexdocs.pm/phoenix_pubsub/Phoenix.PubSub.html) with the default `Phoenix.PubSub.PG2` adapter.

The PG2 adapter utilizes Erlang [process groups](https://www.erlang.org/docs/18/man/pg2.html) to implement the PubSub model where a publisher can send messages to many subscribers.


## Global cluster

Presence is an in-memory key-value store backed by a CRDT. When a user is connected to the cluster the state of that user is sent to all connected Realtime nodes.

Broadcast lets you send a message from any connected client to a Channel. Any other client connected to that same Channel will receive that message.

This works globally. A client connected to a Realtime node in the United States can send a message to another client connected to a node in Singapore. Connect two clients to the same Realtime Channel and they'll all receive the same messages.

Broadcast is useful for getting messages to users in the same location very quickly. If a group of clients are connected to a node in Singapore, the message only needs to go to that Realtime node in Singapore and back down. If users are close to a Realtime node they'll get Broadcast messages in the time it takes to ping the cluster.

Thanks to the Realtime cluster, you (an amazing Supabase user) don't have to think about which regions your clients are connected to.

If you're using Broadcast, Presence, or streaming database changes, messages will always get to your users via the shortest path possible.


## Connecting to a database

Realtime allows you to listen to changes from your Postgres database. When a new client connects to Realtime and initializes the `postgres_changes` Realtime Extension the cluster will connect to your Postgres database and start streaming changes from a replication slot.

Realtime knows the region your database is in, and connects to it from the closest region possible.

Every Realtime region has at least two nodes so if one node goes offline the other node should reconnect and start streaming changes again.


## Broadcast from Postgres

Realtime Broadcast sends messages when changes happen in your database. Behind the scenes, Realtime creates a publication on the `realtime.messages` table. It then reads the Write-Ahead Log (WAL) file for this table, and sends a message whenever an insert happens. Messages are sent as JSON packages over WebSockets.

The `realtime.messages` table is partitioned by day. This allows old messages to be deleted performantly, by dropping old partitions. Partitions are retained for 3 days before being deleted.

Broadcast uses [Realtime Authorization](/docs/guides/realtime/authorization) by default to protect your data.


## Streaming the Write-Ahead Log

A Postgres logical replication slot is acquired when connecting to your database.

Realtime delivers changes by polling the replication slot and appending channel subscription IDs to each wal record.

Subscription IDs are Erlang processes representing underlying sockets on the cluster. These IDs are globally unique and messages to processes are routed automatically by the Erlang virtual machine.

After receiving results from the polling query, with subscription IDs appended, Realtime delivers records to those clients.


# Realtime Authorization



You can control client access to Realtime [Broadcast](/docs/guides/realtime/broadcast) and [Presence](/docs/guides/realtime/presence) by adding Row Level Security policies to the `realtime.messages` table. Each RLS policy can map to a specific action a client can take:

*   Control which clients can broadcast to a Channel
*   Control which clients can receive broadcasts from a Channel
*   Control which clients can publish their presence to a Channel
*   Control which clients can receive messages about the presence of other clients


## How it works

Realtime uses the `messages` table in your database's `realtime` schema to generate access policies for your clients when they connect to a Channel topic.

By creating RLS polices on the `realtime.messages` table you can control the access users have to a Channel topic, and features within a Channel topic.

The validation is done when the user connects. When their WebSocket connection is established and a Channel topic is joined, their permissions are calculated based on:

*   The RLS policies on the `realtime.messages` table
*   The user information sent as part of their [Auth JWT](/docs/guides/auth/jwts)
*   The request headers
*   The Channel topic the user is trying to connect to

When Realtime generates a policy for a client it performs a query on the `realtime.messages` table and then rolls it back. Realtime does not store any messages in your `realtime.messages` table.

Using Realtime Authorization involves two steps:

*   In your database, create RLS policies on the `realtime.messages`
*   In your client, instantiate the Realtime Channel with the `config` option `private: true`


## Helper functions

You can use the following helper functions when writing RLS policies:


### `realtime.topic`

Returns the Channel topic the user is attempting to connect to.

```sql
create policy "authenticated can read all messages on topic"
on "realtime"."messages"
for select
to authenticated
using (
  (select realtime.topic()) = 'room-1'
);
```


## Examples

The following examples use this schema:

```sql
create table public.rooms (
    id bigint generated by default as identity primary key,
    topic text not null unique
);

alter table public.rooms enable row level security;

create table public.profiles (
  id uuid not null references auth.users on delete cascade,
  email text NOT NULL,

  primary key (id)
);

alter table public.profiles enable row level security;

create table public.rooms_users (
  user_id uuid references auth.users (id),
  room_topic text references public.rooms (topic),
  created_at timestamptz default current_timestamp
);

alter table public.rooms_users enable row level security;
```


### Broadcast

The `extension` field on the `realtime.messages` table records the message type. For Broadcast messages, the value of `realtime.messages.extension` is `broadcast`. You can check for this in your RLS policies.


#### Allow a user to join (and read) a Broadcast topic

To join a Broadcast Channel, a user must have at least one read or write permission on the Channel topic.

Here, we allow reads (`select`s) for users who are linked to the requested topic within the relationship table `public.room_users`:

```sql
create policy "authenticated can receive broadcast"
on "realtime"."messages"
for select
to authenticated
using (
exists (
    select
      user_id
    from
      rooms_users
    where
      user_id = (select auth.uid())
      and topic = (select realtime.topic())
      and realtime.messages.extension in ('broadcast')
  )
);
```

Then, to join a topic with RLS enabled, instantiate the Channel with the `private` option set to `true`.


#### Allow a user to send a Broadcast message

To authorize sending Broadcast messages, create a policy for `insert` where the value of `realtime.messages.extension` is `broadcast`.

Here, we allow writes (sends) for users who are linked to the requested topic within the relationship table `public.room_users`:

```sql
create policy "authenticated can send broadcast on topic"
on "realtime"."messages"
for insert
to authenticated
with check (
  exists (
    select
      user_id
    from
      rooms_users
    where
      user_id = (select auth.uid())
      and topic = (select realtime.topic())
      and realtime.messages.extension in ('broadcast')
  )
);
```


### Presence

The `extension` field on the `realtime.messages` table records the message type. For Presence messages, the value of `realtime.messages.extension` is `presence`. You can check for this in your RLS policies.


#### Allow users to listen to Presence messages on a Channel

Create a policy for `select` on `realtime.messages` where `realtime.messages.extension` is `presence`.

```sql
create policy "authenticated can listen to presence in topic"
on "realtime"."messages"
for select
to authenticated
using (
  exists (
    select
      user_id
    from
      rooms_users
    where
      user_id = (select auth.uid())
      and topic = (select realtime.topic())
      and realtime.messages.extension in ('presence')
  )
);
```


#### Allow users to send Presence messages on a channel

To update the Presence status for a user create a policy for `insert` on `realtime.messages` where the value of `realtime.messages.extension` is `presence`.

```sql
create policy "authenticated can track presence on topic"
on "realtime"."messages"
for insert
to authenticated
with check (
  exists (
    select
      user_id
    from
      rooms_users
    where
      user_id = (select auth.uid())
      and name = (select realtime.topic())
      and realtime.messages.extension in ('presence')
  )
);
```


### Presence and Broadcast

Authorize both Presence and Broadcast by including both extensions in the `where` filter.


#### Broadcast and Presence read

Authorize Presence and Broadcast read in one RLS policy.

```sql
create policy "authenticated can listen to broadcast and presence on topic"
on "realtime"."messages"
for select
to authenticated
using (
  exists (
    select
      user_id
    from
      rooms_users
    where
      user_id = (select auth.uid())
      and topic = (select realtime.topic())
      and realtime.messages.extension in ('broadcast', 'presence')
  )
);
```


#### Broadcast and Presence write

Authorize Presence and Broadcast write in one RLS policy.

```sql
create policy "authenticated can send broadcast and presence on topic"
on "realtime"."messages"
for insert
to authenticated
with check (
  exists (
    select
      user_id
    from
      rooms_users
    where
      user_id = (select auth.uid())
      and name = (select realtime.topic())
      and realtime.messages.extension in ('broadcast', 'presence')
  )
);
```


## Interaction with Postgres Changes

Realtime Postgres Changes are separate from Channel authorization. The `private` Channel option does not apply to Postgres Changes.

When using Postgres Changes with RLS, database records are sent only to clients who are allowed to read them based on your RLS policies.


## Updating RLS policies

Client access polices are cached for the duration of the connection. Your database is not queried for every Channel message.

Realtime updates the access policy cache for a client based on your RLS polices when:

*   A client connects to Realtime and subscribes to a Channel
*   A new JWT is sent to Realtime from a client via the [`access_token` message](/docs/guides/realtime/protocol#access-token)

If a new JWT is never received on the Channel, the client will be disconnected when the JWT expires.

Make sure to keep the JWT expiration window short.


# Benchmarks

Scalability Benchmarks for Supabase Realtime.

This guide explores the scalability of Realtime's features: Broadcast, Presence, and Postgres Changes.


## Methodology

*   The benchmarks are conducted using k6, an open-source load testing tool, against a Realtime Cluster deployed on AWS.
*   The cluster configurations use 2-6 nodes, tested in both single-region and multi-region setups, all connected to a single Supabase project.
*   The load generators (k6 servers) are deployed on AWS to minimize network latency impact on the results.
*   Tests are executed with a full load from the start without warm-up runs.

The metrics collected include: message throughput, latency percentiles, CPU and memory utilization, and connection success rates. Note that performance in production environments may vary based on factors such as network conditions, hardware specifications, and specific usage patterns.


## Workloads

The proposed workloads are designed to demonstrate Supabase Realtime's throughput and scalability. These benchmarks focus on core functionality and common usage patterns. The benchmarking results include the following workloads:

1.  **Broadcast Performance**
2.  **Payload Size Impact on Broadcast**
3.  **Large-Scale Broadcasting**
4.  **Authentication and New Connection Rate**
5.  **Database Events**


## Results


### Broadcast: Using WebSockets

This workload evaluates the system's capacity to handle multiple concurrent WebSocket connections and sending Broadcast messages via the WebSocket. Each virtual user (VU) in the test:

*   Establishes and maintains a WebSocket connection
*   Joins two distinct channels:
    *   An echo channel (1 user per channel) for direct message reflection
    *   A broadcast channel (6 users per channel) for group communication
*   Generates traffic by sending 2 messages per second to each joined channel for 10 minutes

![Broadcast Performance](/docs/img/guides/realtime/broadcast-performance.png)

| Metric              | Value                   |
| ------------------- | ----------------------- |
| Concurrent Users    | 32\_000                  |
| Total Channel Joins | 64\_000                  |
| Message Throughput  | 224\_000 msgs/sec        |
| Median Latency      | 6 ms                    |
| Latency (p95)       | 28 ms                   |
| Latency (p99)       | 213 ms                  |
| Data Received       | 6.4 MB/s (7.9 GB total) |
| Data Sent           | 23 KB/s (28 MB total)   |
| New Connection Rate | 320 conn/sec            |
| Channel Join Rate   | 640 joins/sec           |


### Broadcast: Using the database

This workload evaluates the system's capacity to send Broadcast messages from the database using the `realtime.broadcast_changes` function. Each virtual user (VU) in the test:

*   Establishes and maintains a WebSocket connection
*   Joins a distinct channel:
    *   A single channel (100 users per channel) for group communication
*   Database has a trigger set to run `realtime.broadcast_changes` on every insert
*   Database triggers 10\_000 inserts per second

![Broadcast from Database Performance](/docs/img/guides/realtime/broadcast-from-database-performance.png)

| Metric              | Value                  |
| ------------------- | ---------------------- |
| Concurrent Users    | 80\_000                 |
| Total Channel Joins | 160\_000                |
| Message Throughput  | 10\_000 msgs/sec        |
| Median Latency      | 46 ms                  |
| Latency (p95)       | 132 ms                 |
| Latency (p99)       | 159 ms                 |
| Data Received       | 1.7 MB/s (42 GB total) |
| Data Sent           | 0.4 MB/s (4 GB total)  |
| New Connection Rate | 2000 conn/sec          |
| Channel Join Rate   | 4000 joins/sec         |


### Broadcast: Impact of payload size

This workload tests the system's performance with different message payload sizes to understand how data volume affects throughput and latency. Each virtual user (VU) follows the same connection pattern as the broadcast test, but with varying message sizes:

*   Establishes and maintains a WebSocket connection
*   Joins two distinct channels:
    *   An echo channel (1 user per channel) for direct message reflection
    *   A broadcast channel (6 users per channel) for group communication
*   Sends messages with payloads of 1KB, 10KB, and 50KB
*   Generates traffic by sending 2 messages per second to each joined channel for 5 minutes


#### 1KB payload

![1KB Payload Broadcast Performance](/docs/img/guides/realtime/payload-size-1kb.png)


#### 10KB payload

![10KB Payload Broadcast Performance](/docs/img/guides/realtime/payload-size-10kb.png)


#### 50KB payload

![50KB Payload Broadcast Performance](/docs/img/guides/realtime/payload-size-50kb-small.png)

| Metric             | 1KB Payload         | 10KB Payload      | 50KB Payload       | 50KB Payload (Reduced Load) |
| ------------------ | ------------------- | ----------------- | ------------------ | --------------------------- |
| Concurrent Users   | 4\_000               | 4\_000             | 4\_000              | 2\_000                       |
| Message Throughput | 28\_000 msgs/sec     | 28\_000 msgs/sec   | 28\_000 msgs/sec    | 14\_000 msgs/sec             |
| Median Latency     | 13 ms               | 16 ms             | 27 ms              | 19 ms                       |
| Latency (p95)      | 36 ms               | 42 ms             | 81 ms              | 39 ms                       |
| Latency (p99)      | 85 ms               | 93 ms             | 146 ms             | 82 ms                       |
| Data Received      | 31.2 MB/s (10.4 GB) | 268 MB/s (72 GB)  | 1284 MB/s (348 GB) | 644 MB/s (176 GB)           |
| Data Sent          | 9.2 MB/s (3.1 GB)   | 76 MB/s (20.8 GB) | 384 MB/s (104 GB)  | 192 MB/s (52 GB)            |

> Note: The final column shows results with reduced load (2,000 users) for the 50KB payload test, demonstrating how the system performs with larger payloads under different concurrency levels.


### Broadcast: Scalability scenarios

This workload demonstrates Realtime's capability to handle high-scale scenarios with a large number of concurrent users and broadcast channels. The test simulates a scenario where each user participates in group communications with periodic message broadcasts. Each virtual user (VU):

*   Establishes and maintains a WebSocket connection (30-120 minutes)
*   Joins 2 broadcast channels
*   Sends 1 message per minute to each joined channel
*   Each message is broadcast to 100 other users

![Large Broadcast Performance](/docs/img/guides/realtime/broadcast-large.png)

| Metric              | Value              |
| ------------------- | ------------------ |
| Concurrent Users    | 250\_000            |
| Total Channel Joins | 500\_000            |
| Users per Channel   | 100                |
| Message Throughput  | >800\_000 msgs/sec  |
| Median Latency      | 58 ms              |
| Latency (p95)       | 279 ms             |
| Latency (p99)       | 508 ms             |
| Data Received       | 68 MB/s (600 GB)   |
| Data Sent           | 0.64 MB/s (5.7 GB) |


### Realtime Auth

This workload demonstrates Realtime's capability to handle large amounts of new connections per second and channel joins per second with Authentication Row Level Security (RLS) enabled for these channels. The test simulates a scenario where large volumes of users connect to realtime and participate in auth protected communications. Each virtual user (VU):

*   Establishes and maintains a WebSocket connection (2.5 minutes)
*   Joins 2 broadcast channels
*   Sends 1 message per minute to each joined channel
*   Each message is broadcast to 100 other users

![Broadcast Auth Performance](/docs/img/guides/realtime/broadcast-auth.png)

| Metric              | Value             |
| ------------------- | ----------------- |
| Concurrent Users    | 50\_000            |
| Total Channel Joins | 100\_000           |
| Users per Channel   | 100               |
| Message Throughput  | >150\_000 msgs/sec |
| New Connection Rate | 500 conn/sec      |
| Channel Join Rate   | 1000 joins/sec    |
| Median Latency      | 19 ms             |
| Latency (p95)       | 49 ms             |
| Latency (p99)       | 96 ms             |


### Postgres Changes

Realtime systems usually require forethought because of their scaling dynamics. For the `Postgres Changes` feature, every change event must be checked to see if the subscribed user has access. For instance, if you have 100 users subscribed to a table where you make a single insert, it will then trigger 100 "reads": one for each user.

There can be a database bottleneck which limits message throughput. If your database cannot authorize the changes rapidly enough, the changes will be delayed until you receive a timeout.

Database changes are processed on a single thread to maintain the change order. That means compute upgrades don't have a large effect on the performance of Postgres change subscriptions. You can estimate the expected maximum throughput for your database below.

If you are using Postgres Changes at scale, you should consider using a separate "public" table without RLS and filters. Alternatively, you can use Realtime server-side only and then re-stream the changes to your clients using a Realtime Broadcast.

Enter your database settings to estimate the maximum throughput for your instance:

Don't forget to run your own benchmarks to make sure that the performance is acceptable for your use case.

Supabase continues to make improvements to Realtime's Postgres Changes. If you are uncertain about your use case performance, reach out using the [Support Form](https://supabase.com/dashboard/support/new). The support team can advise on the best solution for each use-case.


# Broadcast

Send low-latency messages using the client libs, REST, or your Database.

You can use Realtime Broadcast to send low-latency messages between users. Messages can be sent using the client libraries, REST APIs, or directly from your database.


## Subscribe to messages

You can use the Supabase client libraries to receive Broadcast messages.


### Initialize the client

Go to your Supabase project's [API Settings](https://supabase.com/dashboard/project/_/settings/api) and grab the `URL` and `anon` public API key.


### Receiving Broadcast messages

You can provide a callback for the `broadcast` channel to receive message. This example will receive any `broadcast` messages that are sent to `test-channel`:


## Send messages


### Broadcast using the client libraries

You can use the Supabase client libraries to send Broadcast messages.


### Broadcast from the Database

You can send messages directly from your database using the `realtime.send()` function:

```sql
select
  realtime.send(
    jsonb_build_object('hello', 'world'), -- JSONB Payload
    'event', -- Event name
    'topic', -- Topic
    false -- Public / Private flag
  );
```

It's a common use case to broadcast messages when a record is created, updated, or deleted. We provide a helper function specific to this use case, `realtime.broadcast_changes()`. For more details, check out the [Subscribing to Database Changes](/docs/guides/realtime/subscribing-to-database-changes) guide.


### Broadcast using the REST API

You can send a Broadcast message by making an HTTP request to Realtime servers.


## Broadcast options

You can pass configuration options while initializing the Supabase Client.


### Self-send messages


### Acknowledge messages

Use this to guarantee that the server has received the message before resolving `channelD.send`'s promise. If the `ack` config is not set to `true` when creating the channel, the promise returned by `channelD.send` will resolve immediately.


# Realtime Concepts

Learn about Channels and other extensions in Supabase Realtime

You can use Supabase Realtime to build real-time applications with collaborative/multiplayer functionality. It includes 3 core extensions:

*   [Broadcast](/docs/guides/realtime/broadcast): sends rapid, ephemeral messages to other connected clients. You can use it to track mouse movements, for example.
*   [Presence](/docs/guides/realtime/presence): sends user state between connected clients. You can use it to show an "online" status, which disappears when a user is disconnected.
*   [Postgres Changes](/docs/guides/realtime/postgres-changes): receives database changes in real-time.


## Channels

A Channel is the basic building block of Realtime. You can think of a Channel as a chatroom, similar to a Discord or Slack channel, where participants are able to see who's online and send and receive messages.

When you initialize your Supabase Realtime client, you define a `topic` that uniquely references a channel. Clients can bi-directionally send and receive messages over a Channel.

```js
import { createClient } from '@supabase/supabase-js'

const supabase = createClient('https://<project>.supabase.co', '<your-anon-key>')

const roomOne = supabase.channel('room-one') // set your topic here
```


## Broadcast

Realtime Broadcast follows the [publish-subscribe pattern](https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern) where a client publishes messages to a channel based on a unique topic. For example, a user could send a message to a channel with topic `room-one`.

```js
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('https://<project>.supabase.co', '<your-anon-key>')
const roomOne = supabase.channel('room-one') // set your topic here

// ---cut---
roomOne.send({
  type: 'broadcast',
  event: 'test',
  payload: { message: 'hello, world' },
})
```

Other clients can receive the message in real-time by subscribing to the Channel with topic `room-one`. These clients continue to receive messages as long as they are subscribed and connected to the same Channel topic.

An example use-case is sharing a user's cursor position with other clients in an online game.


## Presence

Presence can be used to share an individual's state with others within a Channel.

```js
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('https://<project>.supabase.co', '<your-anon-key>')
const roomOne = supabase.channel('room-one') // set your topic here

// ---cut---
const presenceTrackStatus = await roomOne.track({
  user: 'user-1',
  online_at: new Date().toISOString(),
})
```

Each client maintains their own state, and this is then combined into a "shared state" for that Channel topic. It's commonly used for sharing statuses (e.g. "online" or "inactive"). The neat thing about Presence is that if a client is suddenly disconnected (for example, they go offline), their state is automatically removed from the shared state. If you've ever tried to build an “I'm online” feature which handles unexpected disconnects, you'll appreciate how useful this is.
When a new client subscribes to a channel, it will immediately receive the channel's latest state in a single message because the state is held by the Realtime server.


## Postgres Changes

The Postgres Changes extension listens for database changes and sends them to clients. Clients are required to subscribe with a JWT dictating which changes they are allowed to receive based on the database's [Row Level Security](/docs/guides/database/postgres/row-level-security).

```js
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('your_project_url', 'your_supabase_api_key')

// ---cut---
const allChanges = supabase
  .channel('schema-db-changes')
  .on(
    'postgres_changes',
    {
      event: '*',
      schema: 'public',
    },
    (payload) => console.log(payload)
  )
  .subscribe()
```

Anyone with access to a valid JWT signed with the project's JWT secret is able to listen to your database's changes, unless tables have [Row Level Security](/docs/guides/database/postgres/row-level-security) enabled and policies in place.

Clients can choose to receive `INSERT`, `UPDATE`, `DELETE`, or `*` (all) changes for all changes in a schema, a table in a schema, or a column's value in a table. Your clients should only listen to tables in the `public` schema and you must first enable the tables you want your clients to listen to.


## Choosing between Broadcast and Presence

We recommend using Broadcast by default, and then Presence when required. Presence utilizes an in-memory conflict-free replicated data type (CRDT) to track and synchronize shared state in an eventually consistent manner. It computes the difference between existing state and new state changes and sends the necessary updates to clients via Broadcast. This is computationally heavy, so you should use it sparingly. If you use Presence, it's best to throttle your changes so that you are sending updates less frequently.


# Operational Error Codes

List of operational codes to help understand your deployment and usage.

| Code                                 | Description                                                                                                                         | Action                                                                                             |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `RealtimeDisabledForConfiguration`   | The configuration provided to Realtime on connect will not be able to provide you any Postgres Changes                              | Verify your configuration on channel startup as you might not have your tables properly registered |
| `TenantNotFound`                     | The tenant you are trying to connect to does not exist                                                                              | Verify the tenant name you are trying to connect to exists in the realtime.tenants table           |
| `ErrorConnectingToWebSocket`         | Error when trying to connect to the WebSocket server                                                                                | Verify user information on connect                                                                 |
| `ErrorAuthorizingWebSocket`          | Error when trying to authorize the WebSocket connection                                                                             | Verify user information on connect                                                                 |
| `TableHasSpacesInName`               | The table you are trying to listen to has spaces in its name which we are unable to support                                         | Change the table name to not have spaces in it                                                     |
| `UnableToDeleteTenant`               | Error when trying to delete a tenant                                                                                                | Contact Support                                                                                    |
| `UnableToSetPolicies`                | Error when setting up Authorization Policies                                                                                        | Contact Support                                                                                    |
| `UnableCheckoutConnection`           | Error when trying to checkout a connection from the tenant pool                                                                     | Contact Support                                                                                    |
| `UnableToSubscribeToPostgres`        | Error when trying to subscribe to Postgres changes                                                                                  | Contact Support                                                                                    |
| `ChannelRateLimitReached`            | The number of channels you can create has reached its limit                                                                         | Contact support to increase your rate limits                                                       |
| `ConnectionRateLimitReached`         | The number of connected clients as reached its limit                                                                                | Contact support to increase your rate limits                                                       |
| `ClientJoinRateLimitReached`         | The rate of joins per second from your clients as reached the channel limits                                                        | Contact support to increase your rate limits                                                       |
| `UnableToConnectToTenantDatabase`    | Realtime was not able to connect to the tenant's database                                                                           | Contact support for further instructions                                                           |
| `RealtimeNodeDisconnected`           | Realtime is a distributed application and this means that one the system is unable to communicate with one of the distributed nodes | Contact support for further instructions                                                           |
| `MigrationsFailedToRun`              | Error when running the migrations against the Tenant database that are required by Realtime                                         | Contact support for further instructions                                                           |
| `ErrorStartingPostgresCDCStream`     | Error when starting the Postgres CDC stream which is used for Postgres Changes                                                      | Contact support for further instructions                                                           |
| `UnknownDataProcessed`               | An unknown data type was processed by the Realtime system                                                                           | Contact support for further instructions                                                           |
| `ErrorStartingPostgresCDC`           | Error when starting the Postgres CDC extension which is used for Postgres Changes                                                   | Contact support for further instructions                                                           |
| `ReplicationSlotBeingUsed`           | The replication slot is being used by another transaction                                                                           | Contact support for further instructions                                                           |
| `PoolingReplicationPreparationError` | Error when preparing the replication slot                                                                                           | Contact support for further instructions                                                           |
| `PoolingReplicationError`            | Error when pooling the replication slot                                                                                             | Contact support for further instructions                                                           |
| `SubscriptionDeletionFailed`         | Error when trying to delete a subscription for Postgres changes                                                                     | Contact support for further instructions                                                           |
| `UnableToDeletePhantomSubscriptions` | Error when trying to delete subscriptions that are no longer being used                                                             | Contact support for further instructions                                                           |
| `UnableToCheckProcessesOnRemoteNode` | Error when trying to check the processes on a remote node                                                                           | Contact support for further instructions                                                           |
| `UnableToCreateCounter`              | Error when trying to create a counter to track rate limits for a tenant                                                             | Contact support for further instructions                                                           |
| `UnableToIncrementCounter`           | Error when trying to increment a counter to track rate limits for a tenant                                                          | Contact support for further instructions                                                           |
| `UnableToDecrementCounter`           | Error when trying to decrement a counter to track rate limits for a tenant                                                          | Contact support for further instructions                                                           |
| `UnableToUpdateCounter`              | Error when trying to update a counter to track rate limits for a tenant                                                             | Contact support for further instructions                                                           |
| `UnableToFindCounter`                | Error when trying to find a counter to track rate limits for a tenant                                                               | Contact support for further instructions                                                           |
| `UnhandledProcessMessage`            | Unhandled message received by a Realtime process                                                                                    | Contact support for further instructions                                                           |
| `UnknownError`                       | An unknown error occurred                                                                                                           | Contact support for further instructions                                                           |


# Postgres Changes

Listen to Postgres changes using Supabase Realtime.

Let's explore how to use Realtime's Postgres Changes feature to listen to database events.


## Quick start

In this example we'll set up a database table, secure it with Row Level Security, and subscribe to all changes using the Supabase client libraries.


## Usage

You can use the Supabase client libraries to subscribe to database changes.


### Listening to specific schemas

Subscribe to specific schema events using the `schema` parameter:

The channel name can be any string except 'realtime'.


### Listening to `INSERT` events

The channel name can be any string except 'realtime'.


### Listening to `UPDATE` events

The channel name can be any string except 'realtime'.


### Listening to `DELETE` events

The channel name can be any string except 'realtime'.


### Listening to specific tables

Subscribe to specific table events using the `table` parameter:

The channel name can be any string except 'realtime'.


### Listening to multiple changes

To listen to different events and schema/tables/filters combinations with the same channel:


### Filtering for specific changes

Use the `filter` parameter for granular changes:


## Available filters

Realtime offers filters so you can specify the data your client receives at a more granular level.


### Equal to (`eq`)

To listen to changes when a column's value in a table equals a client-specified value:

This filter uses Postgres's `=` filter.


### Not equal to (`neq`)

To listen to changes when a column's value in a table does not equal a client-specified value:

This filter uses Postgres's `!=` filter.


### Less than (`lt`)

To listen to changes when a column's value in a table is less than a client-specified value:

This filter uses Postgres's `<` filter, so it works for non-numeric types. Make sure to check the expected behavior of the compared data's type.


### Less than or equal to (`lte`)

To listen to changes when a column's value in a table is less than or equal to a client-specified value:

This filter uses Postgres' `<=` filter, so it works for non-numeric types. Make sure to check the expected behavior of the compared data's type.


### Greater than (`gt`)

To listen to changes when a column's value in a table is greater than a client-specified value:

This filter uses Postgres's `>` filter, so it works for non-numeric types. Make sure to check the expected behavior of the compared data's type.


### Greater than or equal to (`gte`)

To listen to changes when a column's value in a table is greater than or equal to a client-specified value:

This filter uses Postgres's `>=` filter, so it works for non-numeric types. Make sure to check the expected behavior of the compared data's type.


### Contained in list (in)

To listen to changes when a column's value in a table equals any client-specified values:

This filter uses Postgres's `= ANY`. Realtime allows a maximum of 100 values for this filter.


## Receiving `old` records

By default, only `new` record changes are sent but if you want to receive the `old` record (previous values) whenever you `UPDATE` or `DELETE` a record, you can set the `replica identity` of your table to `full`:

```sql
alter table
  messages replica identity full;
```


## Private schemas

Postgres Changes works out of the box for tables in the `public` schema. You can listen to tables in your private schemas by granting table `SELECT` permissions to the database role found in your access token. You can run a query similar to the following:

```sql
grant select on "non_private_schema"."some_table" to authenticated;
```


## Custom tokens

You may choose to sign your own tokens to customize claims that can be checked in your RLS policies.

Your project JWT secret is found with your [Project API keys](https://app.supabase.com/project/_/settings/api) in your dashboard.

To use your own JWT with Realtime make sure to set the token after instantiating the Supabase client and before connecting to a Channel.


### Refreshed tokens

You will need to refresh tokens on your own, but once generated, you can pass them to Realtime.


## Limitations


### Delete events are not filterable

You can't filter Delete events when tracking Postgres Changes. This limitation is due to the way changes are pulled from Postgres.


### Spaces in table names

Realtime currently does not work when table names contain spaces.


### Database instance and realtime performance

Realtime systems usually require forethought because of their scaling dynamics. For the `Postgres Changes` feature, every change event must be checked to see if the subscribed user has access. For instance, if you have 100 users subscribed to a table where you make a single insert, it will then trigger 100 "reads": one for each user.

There can be a database bottleneck which limits message throughput. If your database cannot authorize the changes rapidly enough, the changes will be delayed until you receive a timeout.

Database changes are processed on a single thread to maintain the change order. That means compute upgrades don't have a large effect on the performance of Postgres change subscriptions. You can estimate the expected maximum throughput for your database below.

If you are using Postgres Changes at scale, you should consider using separate "public" table without RLS and filters. Alternatively, you can use Realtime server-side only and then re-stream the changes to your clients using a Realtime Broadcast.

Enter your database settings to estimate the maximum throughput for your instance:

Don't forget to run your own benchmarks to make sure that the performance is acceptable for your use case.

We are making many improvements to Realtime's Postgres Changes. If you are uncertain about the performance of your use case, reach out using [Support Form](https://supabase.com/dashboard/support/new) and we will be happy to help you. We have a team of engineers that can advise you on the best solution for your use-case.


# Presence

Share state between users with Realtime Presence.

Let's explore how to implement Realtime Presence to track state between multiple users.


## Usage

You can use the Supabase client libraries to track Presence state between users.


### Initialize the client

Go to your Supabase project's [API Settings](https://supabase.com/dashboard/project/_/settings/api) and grab the `URL` and `anon` public API key.


### Sync and track state


### Sending state

You can send state to all subscribers using `track()`:

A client will receive state from any other client that is subscribed to the same topic (in this case `room_01`). It will also automatically trigger its own `sync` and `join` event handlers.


### Stop tracking

You can stop tracking presence using the `untrack()` method. This will trigger the `sync` and `leave` event handlers.


## Presence options

You can pass configuration options while initializing the Supabase Client.


### Presence key

By default, Presence will generate a unique `UUIDv1` key on the server to track a client channel's state. If you prefer, you can provide a custom key when creating the channel. This key should be unique among clients.


# Realtime Pricing



You are charged for the number of Realtime messages and the number of Realtime peak connections.


## Messages

For a detailed explanation of how charges are calculated, refer to [Manage Realtime Messages usage](/docs/guides/platform/manage-your-usage/realtime-messages).


## Peak connections

For a detailed explanation of how charges are calculated, refer to [Manage Realtime Peak Connections usage](/docs/guides/platform/manage-your-usage/realtime-peak-connections).


# Realtime Protocol



The Realtime Protocol is a set of message formats used for communication over a WebSocket connection between a Realtime client and server. These messages are used to initiate a connection, update access tokens, receive system status updates, and receive real-time updates from the Postgres database.


## Connection

In the initial message, the client sends a message specifying the features they want to use (Broadcast, Presence, Postgres Changes).

```ts
{
   "event": "phx_join",
   "topic": string,
   "payload": {
      "config": {
         "broadcast": {
            "self": boolean
         },
         "presence": {
            "key": string
         },
         "postgres_changes": [
            {
               "event": "*" | "INSERT" | "UPDATE" | "DELETE",
               "schema": string,
               "table": string,
               "filter": string + '=' + "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in" +  '.' + string
            }
         ]
      }
   },
   "ref": string
}
```

In response, the server sends the Postgres configuration with a unique ID. With this ID, the client should route incoming changes to the appropriate callback.

```ts
{
   "event": "phx_reply",
   "topic": string,
   "payload": {
      "response": {
         "postgres_changes": [
            {
               "id": number,
               "event": "*" | "INSERT" | "UPDATE" | "DELETE",
               "schema": string,
               "table": string,
               "filter": string + '=' + "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in" +  '.' + string
            }
         ]
      },
      "status": "ok" | "error"
   },
   "ref": string
}
```


## System messages

System message are used to inform a client about the status of the Postgres subscription. The `payload.status` indicates if the subscription successful or not.
The body of the `payload.message` can be "Subscribed to Postgres" or "Subscribing to Postgres failed" with subscription params.

```ts
{
   "event": "system",
   "topic": string,
   "payload":{
      "channel": string,
      "extension": "postgres_changes",
      "message": "Subscribed to PostgreSQL" | "Subscribing to PostgreSQL failed",
      "status": "ok" | "error"
   },
   "ref": null,
}
```


## Heartbeat

The heartbeat message should be sent every 30 seconds to avoid a connection timeout.

```ts
{
   "event": "heartbeat",
   "topic": "phoenix",
   "payload": {},
   "ref": string
}
```


## Access token

To update the access token, you need to send to the server a message specifying a new token in the `payload.access_token` value.

```ts
{
   "event": "access_token",
   "topic": string,
   "payload":{
      "access_token": string
   },
   "ref": string
}
```


## Postgres CDC message

Realtime sends a message with the following structure. By default, the payload only includes new record changes, and the `old` entry includes the changed row's primary id. If you want to receive old records, you can set the replicate identity of your table to full. Check out [this section of the guide](/docs/guides/realtime/postgres-changes#receiving-old-records).

```ts
{
   "event": "postgres_changes",
   "topic": string,
   "payload": {
      "data": {
         schema: string,
         table: string,
         commit_timestamp: string,
         eventType: "*" | "INSERT" | "UPDATE" | "DELETE",
         new: {[key: string]: boolean | number | string | null},
         old: {[key: string]: number | string},
         errors: string | null
      },
      "ids": Array<number>
   },
   "ref": null
}
```


## Broadcast message

Structure of the broadcast event

```ts
{
   "event": "broadcast",
   "topic": string,
   "payload": {
      "event": string,
      "payload": {[key: string]: boolean | number | string | null | undefined},
      "type": "broadcast"
   },
   "ref": null
}
```


## Presence message

The Presence events allow clients to monitor the online status of other clients in real-time.


### State update

After joining, the server sends a `presence_state` message to a client with presence information. The payload field contains keys in UUID format, where each key represents a client and its value is a JSON object containing information about that client.

```ts
{
   "event": "presence_state",
   "topic": string,
   "payload": {
      [key: string]: {metas: Array<{phx_ref: string, name: string, t: float}>}
   },
   "ref": null
}
```


### Diff update

After a change to the presence state, such as a client joining or leaving, the server sends a presence\_diff message to update the client's view of the presence state. The payload field contains two keys, `joins` and `leaves`, which represent clients that have joined and left, respectively. The values associated with each key are UUIDs of the clients.

```ts
{
   "event": "presence_diff",
   "topic": string,
   "payload": {
      "joins": {metas: Array<{phx_ref: string, name: string, t: float}>},
      "leaves": {metas: Array<{phx_ref: string, name: string, t: float}>}
   },
   "ref": null
}
```


# Realtime Quotas



Our cluster supports millions of concurrent connections and message throughput for production workloads.


## Quotas by plan

|                                                                                        | Free  | Pro   | Pro (no spend cap) | Team   | Enterprise |
| -------------------------------------------------------------------------------------- | ----- | ----- | ------------------ | ------ | ---------- |
| **Concurrent connections**                                                             | 200   | 500   | 10,000             | 10,000 | 10,000+    |
| **Messages per second**                                                                | 100   | 500   | 2,500              | 2,500  | 2,500+     |
| **Channel joins per second**                                                           | 100   | 500   | 2,500              | 2,500  | 2,500+     |
| **Channels per connection**                                                            | 100   | 100   | 100                | 100    | 100+       |
| **Presence keys per object**                                                           | 10    | 10    | 10                 | 10     | 10+        |
| **Presence messages per second**                                                       | 20    | 50    | 1,000              | 1,000  | 1,000+     |
| **Broadcast payload size KB**                                                          | 256   | 3,000 | 3,000              | 3,000  | 3,000+     |
| **Postgres change payload size KB ([**read more**](#postgres-changes-payload-quota))** | 1,024 | 1,024 | 1,024              | 1,024  | 1,024+     |

Beyond the Free and Pro Plan you can customize your quotas by [contacting support](https://supabase.com/dashboard/support/new).


## Quota errors

When you exceed a quota, errors will appear in the backend logs and client-side messages in the WebSocket connection.

*   **Logs**: check the [Realtime logs](https://supabase.com/dashboard/project/_/database/realtime-logs) inside your project Dashboard.
*   **WebSocket errors**: Use your browser's developer tools to find the WebSocket initiation request and view individual messages.

Some quotas can cause a Channel join to be refused. Realtime will reply with one of the following WebSocket messages:


### `too_many_channels`

Too many channels currently joined for a single connection.


### `too_many_connections`

Too many total concurrent connections for a project.


### `too_many_joins`

Too many Channel joins per second.


### `tenant_events`

Connections will be disconnected if your project is generating too many messages per second. `supabase-js` will reconnect automatically when the message throughput decreases below your plan quota. An `event` is a WebSocket message delivered to, or sent from a client.


## Postgres changes payload quota

When this quota is reached, the `new` and `old` record payloads only include the fields with a value size of less than or equal to 64 bytes.


# Listening to Postgres Changes with Flutter



The Postgres Changes extension listens for database changes and sends them to clients which enables you to receive database changes in real-time.


# Using Realtime Presence with Flutter



Use Supabase Presence to display the currently online users on your Flutter application.

Displaying the list of currently online users is a common feature for real-time collaborative applications. Supabase Presence makes it easy to track users joining and leaving the session so that you can make a collaborative app.


# Using Realtime with Next.js



In this guide, we explore the best ways to receive real-time Postgres changes with your Next.js application.
We'll show both client and server side updates, and explore which option is best.


# Subscribing to Database Changes

Listen to database changes in real-time from your website or application.

You can use Supabase to subscribe to real-time database changes. There are two options available:

1.  [Broadcast](/docs/guides/realtime/broadcast). This is the recommended method for scalability and security.
2.  [Postgres Changes](/docs/guides/realtime/postgres-changes). This is a simpler method. It requires less setup, but does not scale as well as Broadcast.


## Using Broadcast

To automatically send messages when a record is created, updated, or deleted, we can attach a [Postgres trigger](/docs/guides/database/postgres/triggers) to any table. Supabase Realtime provides a `realtime.broadcast_changes()` function which we can use in conjunction with a trigger.


### Broadcast authorization

[Realtime Authorization](/docs/guides/realtime/authorization) is required for receiving Broadcast messages. This is an example of a policy that allows authenticated users to listen to messages from topics:

```sql
create policy "Authenticated users can receive broadcasts"
on "realtime"."messages"
for select
to authenticated
using ( true );
```


### Create a trigger function

Let's create a function that we can call any time a record is created, updated, or deleted. This function will make use of some of Postgres's native [trigger variables](https://www.postgresql.org/docs/current/plpgsql-trigger.html#PLPGSQL-DML-TRIGGER). For this example, we want to have a topic with the name `topic:<record id>` to which we're going to broadcast events.

```sql
create or replace function public.your_table_changes()
returns trigger
language plpgsql
as $$
begin
  perform realtime.broadcast_changes(
    'topic:' || coalesce(NEW.topic, OLD.topic) ::text, -- topic - the topic to which we're broadcasting
    TG_OP,                                             -- event - the event that triggered the function
    TG_OP,                                             -- operation - the operation that triggered the function
    TG_TABLE_NAME,                                     -- table - the table that caused the trigger
    TG_TABLE_SCHEMA,                                   -- schema - the schema of the table that caused the trigger
    NEW,                                               -- new record - the record after the change
    OLD                                                -- old record - the record before the change
  );
  return null;
end;
$$;
```


### Create a trigger

Let's set up a trigger so the function is executed after any changes to the table.

```sql
create trigger handle_your_table_changes
after insert or update or delete
on public.your_table
for each row
execute function your_table_changes ();
```


#### Listening on client side

Finally, on the client side, listen to the topic `topic:<record_id>` to receive the events. Remember to set the channel as a private channel, since `realtime.broadcast_changes` uses Realtime Authorization.

```js
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('your_project_url', 'your_supabase_api_key')

// ---cut---
const gameId = 'id'
await supabase.realtime.setAuth() // Needed for Realtime Authorization
const changes = supabase
  .channel(`topic:${gameId}`, {
    config: { private: true },
  })
  .on('broadcast', { event: 'INSERT' }, (payload) => console.log(payload))
  .on('broadcast', { event: 'UPDATE' }, (payload) => console.log(payload))
  .on('broadcast', { event: 'DELETE' }, (payload) => console.log(payload))
  .subscribe()
```


## Using Postgres Changes

Postgres Changes are simple to use, but have some [limitations](/docs/guides/realtime/postgres-changes#limitations) as your application scales. We recommend using Broadcast for most use cases.


### Enable Postgres Changes

You'll first need to create a `supabase_realtime` publication and add your tables (that you want to subscribe to) to the publication:

```sql
begin;

-- remove the supabase_realtime publication
drop
  publication if exists supabase_realtime;

-- re-create the supabase_realtime publication with no tables
create publication supabase_realtime;

commit;

-- add a table called 'messages' to the publication
-- (update this to match your tables)
alter
  publication supabase_realtime add table messages;
```


### Streaming inserts

You can use the `INSERT` event to stream all new rows.

```js
// @noImplicitAny: false
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('your_project_url', 'your_supabase_api_key')

// ---cut---
const channel = supabase
  .channel('schema-db-changes')
  .on(
    'postgres_changes',
    {
      event: 'INSERT',
      schema: 'public',
    },
    (payload) => console.log(payload)
  )
  .subscribe()
```


### Streaming updates

You can use the `UPDATE` event to stream all updated rows.

```js
// @noImplicitAny: false
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('your_project_url', 'your_supabase_api_key')

// ---cut---
const channel = supabase
  .channel('schema-db-changes')
  .on(
    'postgres_changes',
    {
      event: 'UPDATE',
      schema: 'public',
    },
    (payload) => console.log(payload)
  )
  .subscribe()
```


# Resources





# Glossary



Definitions for terminology and acronyms used in the Supabase documentation.


## Access token

An access token is a short-lived (usually no more than 1 hour) token that authorizes a client to access resources on a server. It comes in the form of a [JSON Web Token (JWT)](#json-web-token-jwt).


## Authentication

Authentication (often abbreviated `authn.`) is the process of verifying the identity of a user. Verification of the identity of a user can happen in multiple ways:

1.  Asking users for something they know. For example: password, passphrase.
2.  Checking that users have access to something they own. For example: an email address, a phone number, a hardware key, recovery codes.
3.  Confirming that users have some biological features. For example: a fingerprint, a certain facial structure, an iris print.


## Authenticator app

An authenticator app generates time-based one-time passwords (TOTPs). These passwords are generated based off a long and difficult to guess secret string. The secret is initially passed to the application by scanning a QR code.


## Authorization

Authorization (often abbreviated `authz.`) is the process of verifying if a certain identity is allowed to access resources. Authorization often occurs by verifying an access token.


## Identity provider

An identity provider is software or service that allows third-party applications to identify users without the exchange of passwords. Social login and enterprise single-sign on won't be possible without identity providers.

Social login platforms typically use the OAuth protocol, while enterprise single-sign on is based on the OIDC or SAML protocols.


## JSON Web Token (JWT)

A [JSON Web Token](https://jwt.io/introduction) is a type of data structure, represented as a string, that usually contains identity and authorization information about a user. It encodes information about its lifetime and is signed with cryptographic key making it tamper resistant.

Access tokens are JWTs and by inspecting the information they contain you can allow or deny access to resources. Row level security policies are based on the information present in JWTs.


## JWT signing secret

JWTs issued by Supabase are signed using the HMAC-SHA256 algorithm. The secret key used in the signing is called the JWT signing secret. You should not share this secret with someone or some thing you don't trust, nor should you post it publicly. Anyone with access to the secret can create arbitrary JWTs.


## Multi-factor authentication (MFA or 2FA)

Multi-factor authentication is the process of authenticating a user's identity by using a combination of factors: something users know, something users have or something they are.


## Nonce

Nonce means number used once. In reality though, it is a unique and difficult to guess string used to either initialize a protocol or algorithm securely, or detect abuse in various forms of replay attacks.


## OAuth

OAuth is a protocol allowing third-party applications to request and receive authorization from their users. It is typically used to implement social login, and serves as a base for enterprise single-sign on in the OIDC protocol. Applications can request different levels of access, including basic user identification information such as name, email address, and user ID.


## OIDC

OIDC stands for OpenID Connect and is a protocol that enables single-sign on for enterprises. OIDC is based on modern web technologies such as OAuth and JSON Web Tokens. It is commonly used instead of the older SAML protocol.


## One-time password (OTP)

A one-time password is a short, randomly generated and difficult to guess password or code that is sent to a device (like a phone number) or generated by a device or application.


## Password hashing function

Password hashing functions are specially-designed algorithms that allow web servers to verify a password without storing it as-is. Unlike other difficult to guess strings generated from secure random number generators, passwords are picked by users and often are easy to guess by attackers. These algorithms slow down and make it very costly for attackers to guess passwords.

There are three generally accepted password hashing functions: Argon2, bcrypt and scrypt.


## Password strength

Password strength is a measurement of how difficult a password is to guess. Simple measurement includes calculating the number of possibilities given the types of characters used in the password. For example a password of only letters has fewer variations than ones with letters and digits. Better measurements include strategies such as looking for similarity to words, phrases or already known passwords.


## PKCE

Proof Key for Code Exchange is an extension to the OAuth protocol that enables secure exchange of refresh and access tokens between an application (web app, single-page app or mobile app) and the authorization server. It is used in places where the exchange of the refresh and access token may be intercepted by third parties such as other applications running in the operating system. This is a common problem on mobile devices where the operating system may hand out URLs to other applications. This can sometimes be also exploited in single-page apps too.


## Provider refresh token

A provider refresh token is a refresh token issued by a third-party identity provider which can be used to refresh the provider token returned.


## Provider tokens

A provider token is a long-lived token issued by a third-party identity provider. These are issued by social login services (e.g., Google, Twitter, Apple, Microsoft) and uniquely identify a user on those platforms.


## Refresh token

A refresh token is a long-lived (in most cases with an indefinite lifetime) token that is meant to be stored and exchanged for a new refresh and access tokens only once. Once a refresh token is exchanged it becomes invalid, and can't be exchanged again. In practice, though, a refresh token can be exchanged multiple times but in a short time window.


## Refresh token flow

The refresh token flow is a mechanism that issues a new refresh and access token on the basis of a valid refresh token. It is used to extend authorization access for an application. An application that is being constantly used will invoke the refresh token flow just before the access token expires.


## Replay attack

A replay attack is when sensitive information is stolen or intercepted by attackers who then attempt to use it again (thus replay) in an effort to compromise a system. Commonly replay attacks can be mitigated with the proper use of nonces.


## Row level security policies (RLS)

Row level security policies are special objects within the Postgres database that limit the available operations or data returned to clients. RLS policies use information contained in a JWT to identify users and the actions and data they are allowed to perform or view.


## SAML

SAML stands for Security Assertion Markup Language and is a protocol that enables single-sign on for enterprises. SAML was invented in the early 2000s and is based on XML technology. It is the de facto standard for enabling single-sign on for enterprises, although the more recent OIDC (OpenID Connect) protocol is gaining popularity.


## Session

A session or authentication session is the concept that binds a verified user identity to a web browser. A session usually is long-lived, and can be terminated by the user logging out. An access and refresh token pair represent a session in the browser, and they are stored in local storage or as cookies.


## Single-sign on (SSO)

Single-sign on allows enterprises to centrally manage accounts and access to applications. They use identity provider software or services to organize employee information in directories and connect those accounts with applications via OIDC or SAML protocols.


## Time-based one-time password (TOTP)

A time-based one-time password is a one-time password generated at regular time intervals from a secret, usually from an application in a mobile device (e.g., Google Authenticator, 1Password).


# Supabase Security



Supabase is a hosted platform which makes it very simple to get started without needing to manage any infrastructure. The hosted platform comes with many security and compliance controls managed by Supabase.


# Compliance

Supabase is SOC 2 Type 2 compliant and regularly audited. All projects at Supabase are governed by the same set of compliance controls.
The [SOC 2 Compliance Guide](/docs/guides/security/soc-2-compliance) explains Supabase's SOC 2 responsibilities and controls in more detail.

The [HIPAA Compliance Guide](/docs/guides/security/hipaa-compliance) explains Supabase's HIPAA responsibilities. Additional [security and compliance controls](/docs/guides/deployment/shared-responsibility-model#managing-healthcare-data) for projects that deal with electronic Protected Health Information (ePHI) and require HIPAA compliance are available through the HIPAA add-on.


# Platform configuration

Each product offered by Supabase comes with customizable security controls and these security controls help ensure that applications built on Supabase are secure, compliant, and resilient against various threats.

The [security configuration guides](/docs/guides/security/product-security) provide detailed information for configuring individual products.


# HIPAA Compliance and Supabase



The [Health Insurance Portability and Accountability Act (HIPAA)](https://www.hhs.gov/hipaa/for-professionals/privacy/laws-regulations/index.html) is a comprehensive law that protects individuals' health information while ensuring the continuity of health insurance coverage. It sets standards for privacy and security that must be followed by all entities that handle Protected Health Information (PHI), also known as electronic PHI (ePHI). HIPAA is specific to the United States, however many countries have similar or laws already in place or under legislation.

Under HIPAA, both covered entities and business associates have distinct responsibilities to ensure the protection of PHI. Supabase acts as a business associate for customers (the covered entity) who wish to provide healthcare related services. As a business associate, Supabase has a number of obligations and has undergone auditing of the security and privacy controls that are in place to meet these. Supabase has signed a Business Associate Agreement (BAA) with all of our vendors who would have access to ePHI, such as AWS, and ensure that we follow their terms listed in the agreements. Similarly when a customer signs a BAA with us, they have some responsibilities they agree to when using Supabase to store PHI.


### Customer responsibilities

Covered entities (the customer) are organizations that directly handle PHI, such as health plans, healthcare clearinghouses, and healthcare providers that conduct certain electronic transactions.

1.  **Compliance with HIPAA Rules**: Covered entities must comply with the [HIPAA Privacy Rule](https://www.hhs.gov/hipaa/for-professionals/privacy/index.html), [Security Rule](https://www.hhs.gov/hipaa/for-professionals/security/index.html), and [Breach Notification Rule](https://www.hhs.gov/hipaa/for-professionals/breach-notification/index.html) to protect the privacy and security of ePHI.
2.  **Business Associate Agreements (BAAs)**: Customers must sign a BAA with Supabase. When the covered entity engages a business associate to help carry out its healthcare activities, it must have a written BAA. This agreement outlines the business associate's responsibilities and requires them to comply with HIPAA Rules.
3.  **Internal Compliance Programs**: Customers must [configure their HIPAA projects](/docs/guides/platform/hipaa-projects) and follow the guidance given by the security advisor. Covered entities are responsible for implementing internal processes and compliance programs to ensure they meet HIPAA requirements.


### Supabase responsibilities

Supabase as the business associate, and the vendors used by Supabase, are the entities that perform functions or activities on behalf of the customer.

1.  **Direct Liability**: Supabase is directly liable for compliance with certain provisions of the HIPAA Rules. This means Supabase has to implement safeguards to protect ePHI and report breaches to the customer.
2.  **Compliance with BAAs**: Supabase must comply with the terms of the BAA, which includes implementing appropriate administrative, physical, and technical safeguards to protect ePHI.
3.  **Vendor Management**: Supabase must also ensure that our vendors, who may have access to ePHI, comply with HIPAA Rules. This is done through a BAA with each vendor.


## Staying compliant and secure

Compliance is a continuous process and should not be treated as a point-in-time audit of controls. Supabase applies all the necessary privacy and security controls to ensure HIPAA compliance at audit time, but also has additional checks and monitoring in place to ensure those controls are not disabled or altered in between audit periods. Customers commit to doing the same in their HIPAA environments. Supabase provides a growing set of checks that warn customers of changes to their projects that disable or weaken HIPAA required controls. Customers will receive warnings and guidance via the Security Advisor, however the responsibility of applying the recommended controls falls directly to the customer.

Our [shared responsibility model](/docs/guides/deployment/shared-responsibility-model#managing-healthcare-data) document discusses both HIPAA and general data management best practices, how this responsibility is shared between customers and Supabase, and how to stay compliant.


## Frequently asked questions

**What is the difference between SOC 2 and HIPAA?**

Both are frameworks for protecting sensitive data, however they serve two different purposes. They share many security and privacy controls and meeting the controls of one normally means being close to complying with the other.

The main differentiator comes down to purpose and scope.

*   SOC 2 is not industry-specific and can be applied to any service organization that handles customer data.
*   HIPAA is a federal regulation in the United States. HIPAA sets standards for the privacy and security of PHI/ePHI, ensuring that patient data is handled confidentially and securely.

**Are Supabase HIPAA environments also SOC 2 compliant?**

Yes. Supabase applies the same SOC 2 controls to all environments, with additional controls being applied to HIPAA environments.

**How often is Supabase audited?**

Supabase undergoes annual audits. The HIPAA controls are audited during the same audit period as the SOC 2 controls.


## Resources

1.  [Health Insurance Portability and Accountability Act (HIPAA)](https://www.hhs.gov/hipaa/for-professionals/privacy/laws-regulations/index.html)
2.  [HIPAA Privacy Rule](https://www.hhs.gov/hipaa/for-professionals/privacy/index.html)
3.  [Security Rule](https://www.hhs.gov/hipaa/for-professionals/security/index.html)
4.  [Breach Notification Rule](https://www.hhs.gov/hipaa/for-professionals/breach-notification/index.html)
5.  [Configuring HIPAA projects](/docs/guides/platform/hipaa-projects) on Supabase
6.  [Shared Responsibility Model](/docs/guides/deployment/shared-responsibility-model)
7.  [HIPAA shared responsibility](/docs/guides/deployment/shared-responsibility-model#managing-healthcare-data)


# Secure configuration of Supabase products



The Supabase [production checklist](/docs/guides/deployment/going-into-prod) provides detailed advice on preparing an app for production. While our [SOC 2](/docs/guides/security/soc-2-compliance) and [HIPAA](/docs/guides/security/hipaa-compliance) compliance documents outline the roles and responsibilities for building a secure and compliant app.

Various products at Supabase have their own hardening and configuration guides, below is a definitive list of these to help guide your way.


## Auth

*   [Password security](/docs/guides/auth/password-security)
*   [Rate limits](/docs/guides/auth/rate-limits)
*   [Bot detection / Prevention](/docs/guides/auth/auth-captcha)
*   [JWTs](/docs/guides/auth/jwts)


## Database

*   [Row Level Security](/docs/guides/database/postgres/row-level-security)
*   [Column Level Security](/docs/guides/database/postgres/column-level-security)
*   [Hardening the Data API](/docs/guides/database/hardening-data-api)
*   [Additional security controls for the Data API](/docs/guides/api/securing-your-api)
*   [Custom claims and role based access control](/docs/guides/database/postgres/custom-claims-and-role-based-access-control-rbac)
*   [Managing Postgres roles](/docs/guides/database/postgres/roles)
*   [Managing secrets with Vault](/docs/guides/database/vault)
*   [Superuser access and unsupported operations](docs/guides/database/postgres/roles-superuser)


## Storage

*   [Object ownership](/docs/guides/storage/security/ownership)
*   [Access control](/docs/guides/storage/security/access-control)
    *   The Storage API docs contain hints about required [RLS policy permissions](/docs/reference/javascript/storage-createbucket)
*   [Custom roles with the storage schema](/docs/guides/storage/schema/custom-roles)


## Realtime

*   [Authorization](docs/guides/realtime/authorization)


# Security testing of your Supabase projects



Supabase customer support policy for penetration testing

Customers of Supabase are permitted to carry out security assessments or penetration tests of their hosted Supabase project components. This testing may be carried out without prior approval for the customer services listed under [permitted services](#permitted-services). Supabase does not permit hosting security tooling that may be perceived as malicious or part of a campaign against Supabase customers or external services. This section is covered by the [Supabase Acceptable Use Policy](https://supabase.com/aup) (AUP).

It is the customer’s responsibility to ensure that testing activities are aligned with this policy. Any testing performed outside of the policy will be seen as testing directly against Supabase and may be flagged as abuse behaviour. If Supabase receives an abuse report for activities related to your security testing, we will forward these to you. If you discover a security issue within any of the Supabase products, contact [Supabase Security](mailto:security@supabase.io) immediately.

Furthermore, Supabase runs a [Vulnerability Disclosure Program](https://hackerone.com/ca63b563-9661-4ac3-8d23-7581582ef451/embedded_submissions/new) (VDP) with HackerOne, and external security researchers may report any bugs found within the scope of the aforementioned program. Customer penetration testing does not form part of this VDP.


### Permitted services

*   Authentication
*   Database
*   Edge Functions
*   Storage
*   Realtime
*   `https://<customer_project_ref>.supabase.co/*`
*   `https://db.<customer_project_ref>.supabase.co/*`


### Prohibited testing and activities

*   Any activity contrary to what is listed in the AUP.
*   Denial of Service (DoS) and Distributed Denial of Service (DDoS) testing.
*   Cross-tenant attacks, testing that directly targets other Supabase customers' accounts, organizations, and projects not under the customer’s control.
*   Request flooding.


## Terms and conditions

The customer agrees to the following,

Security testing:

*   Will be limited to the services within the customer’s project.
*   Is subject to the general [Terms of Service](https://supabase.com/terms).
*   Is within the [Acceptable Usage Policy](https://supabase.com/aup).
*   Will be stopped if contacted by Supabase due to a breach of the above or a negative impact on Supabase and Supabase customers.
*   Any vulnerabilities discovered directly in a Supabase product will be reported to Supabase Security within 24 hours of completion of testing.


# SOC 2 Compliance and Supabase



Supabase is Systems and Organization Controls 2 (SOC 2) Type 2 compliant and is assessed annually to ensure continued adherence to the SOC 2 security framework. SOC 2 assesses Supabase’s adherence to, and implementation of, controls governing the security, availability, processing integrity, confidentiality, and privacy on the Supabase platform. These controls define requirements for the management and storage of customer data on the platform. These controls applied to Supabase, as a service provider, serve two customer data environments.

The first environment is the customer relationship with Supabase, this refers to the data Supabase has on a customer of the platform. All billing, contact, usage and contract information is managed and stored according to SOC 2 requirements.

The second environment is the backend as a service (the product) that Supabase provides to customers. Supabase implements the controls from the SOC 2 framework to ensure the security of the platform, which hosts the backend as a service (the product), including the Postgres Database, Storage, Authentication, Realtime, Edge Functions and Data API features. Supabase can assert that the environment hosting customer data, stored within the product, adheres to SOC 2 requirements. And the management and storage of data within this environment (the product) is strictly controlled and kept secure.

Supabase’s SOC 2 compliance does not transfer to environments outside of the Supabase product or Supabase’s control. This is known as the security or compliance boundary and forms part of the Shared Responsibility Model that Supabase and their customers enter into.


# Meeting compliance requirements

SOC 2 compliance is a critical aspect of data security for Supabase and our customers. Being fully SOC 2 compliant is a shared responsibility and here’s a breakdown of the responsibilities for both parties:


### Supabase responsibilities

1.  **Security Measures**: Supabase implements robust security controls to protect customer data. These includes measures to prevent data breaches and ensure the confidentiality and integrity of the information managed and stored by the platform. Supabase is obliged to be vigilant about security risks and must demonstrate that our security measures meet industry standards through regular audits.
2.  **Compliance Audits**: Supabase undergoes SOC 2 audits yearly to verify that our data management practices comply with the Trust Services Criteria (TSC), which include security, availability, processing integrity, confidentiality, and privacy. These audits are conducted by an independent third party.
3.  **Incident Response**: Supabase has an incident response plan in place to handle data breaches efficiently. This plan outlines how the organization detects issues, responds to incidents, and manages system vulnerabilities.
4.  **Reporting**: Upon a successful audit, Supabase receive a SOC 2 report that details our compliance status. This report is available to customers as a SOC 2 Type 2 report, and allows customers and stakeholders to assure that Supabase has implemented adequate and the requisite safeguards to protect sensitive information.


### Customer responsibilities

1.  **Compliance Requirements**: Understand your own compliance requirements. While SOC 2 compliance is not a legal requirement, many enterprise customers require their providers to have a SOC 2 report. This is because it provides assurance that the provider has implemented robust controls to protect customer data.
2.  **Due Diligence**: Customers must perform due diligence when selecting Supabase as a provider. This includes reviewing the SOC 2 Type 2 report to ensure that Supabase meets the expected security standards. Customers should also understand the division of responsibilities between themselves and Supabase to avoid duplication of effort.
3.  **Monitoring and Review**: Customers should regularly monitor and review Supabase’s compliance status.
4.  **Control Compliance**: If a customer needs to be SOC 2 compliant, they should themselves implement the requisite controls and undergo a SOC 2 audit.


### Shared responsibilities

1.  **Data Security**: Both customers and Supabase share the responsibility of ensuring data security. While the Supabase, as the provider, implements the security controls, the customer must ensure that their use of the Supabase platform does not compromise these controls.
2.  **Control Compliance**: Supabase asserts through our SOC 2 that all requisite security controls are met. Customers wishing to also be SOC 2 compliant need to go through their own SOC 2 audit, verifying that security controls are met on the customer's side.

In summary, SOC 2 compliance involves a shared responsibility between Supabase and our customers to ensure the security and integrity of data. Supabase, as a provider, must implement and maintain robust security measures, customers must perform due diligence and monitor Supabase's compliance status, while also implement their own compliance controls to protect their sensitive information.


## Frequently asked questions

**How often is Supabase SOC 2 audited?**

Supabase has obtained SOC 2 Type 2 certification, which means Supabase's controls are fully audited annually. The auditor's reports on these examinations are issued as soon as they are ready after the audit. Supabase makes the SOC 2 Type 2 report available to [Enterprise and Team Plan](https://supabase.com/pricing) customers. The audit report covers a rolling 12-month window, known as the audit period, and runs from 1 March to 28 February of the next calendar year.

**How to obtain Supabase's SOC 2 Type 2 report?**

To access the SOC 2 Type 2 report, you must be a Enterprise or Team Plan Supabase customer. The report is downloadable from the [Legal Documents](https://supabase.com/dashboard/org/_/documents) section in the organization dashboard.

**Why does it matter that Supabase is SOC 2 Compliant?**

SOC 2 is used to assert that controls are in place to ensure the proper management and storage of data. SOC 2 provides a framework for measuring how secure a service provider is and re-evaluates the provider on an annual basis. This provides the confidence and assurance that data stored within the Supabase platform is correctly secured and managed.

**If Supabase’s SOC 2 does not transfer to the customer, why does it matter that Supabase has SOC 2?**

Even though Supabase’s SOC 2 compliance does not transfer outside of the product, it does provide the assurance that all data within the product is correctly managed and stored. Supabase can assert that only authorized persons have access to the data, and security controls are in place to prevent, detect and respond to data intrusions. This forms part of a customer’s own adherence to the SOC 2 framework and relieves part of the burden of data management and storage on the customer. In many organizations' security and risk departments require all vendors or sub-processors to be SOC 2 compliant.

**What is the security or compliance boundary?**

This defines the boundary or border between Supabase and customer responsibility for data security within the Shared Responsibility Model. Customer data stored within the Supabase product, on the Supabase side of the security boundary, is managed and secured by Supabase. Supabase ensures the safe handling and storage of data within this environment. This includes controls for preventing unauthorized access, monitoring data access, alerting, data backups and redundancy. Data on the customer side of the boundary, the data that enters and leaves the Supabase product, is the responsibility of the customer. Management and possible storage of such data outside of Supabase should be performed by the customer, and any security and compliance controls are the responsibility of the customer.

**We have strong data residency requirements. Does Supabase SOC 2 cover data residency?**

While SOC 2 itself does not mandate specific data residency requirements, organizations may still need to comply with other regulatory frameworks, such as GDPR, that do have such requirements. Ensuring projects are deployed in the correct region is a customer responsibility as each Supabase project is deployed into the region the customer specifies at creation time. All data will remain within the chosen region.
[Read replicas](/docs/guides/platform/read-replicas) can be created for multi-region availability, it remains the customer's responsibility to ensure regions chosen for read replicas are within the geographic area required by any additional regulatory frameworks.

**Does SOC 2 cover health related data (HIPAA)?**

SOC 2 is non-industry specific and provides a framework for the security and privacy of data. This is however not sufficient in most cases when dealing with Protected Healthcare Information (PHI), which requires additional privacy and legal controls.
When dealing with PHI in the United States or for United States customers, HIPAA is mandatory.


## Resources

1.  [System and Organization Controls: SOC Suite of Services](https://www.aicpa-cima.com/resources/landing/system-and-organization-controls-soc-suite-of-services)
2.  [Shared Responsibility Model](/docs/guides/deployment/shared-responsibility-model)


# Self-Hosting

Host Supabase on your own infrastructure.

There are several ways to host Supabase on your own computer, server, or cloud.


## Officially supported

Supabase is also a hosted platform. If you want to get started for free, visit [supabase.com/dashboard](https://supabase.com/dashboard).


## Community supported

There are several community-driven projects to help you deploy Supabase. We encourage you to try them out and contribute back to the community.


## Third-party guides

The following third-party providers have shown consistent support for the self-hosted version of Supabase:.


# Self-Hosting with Docker

Learn how to configure and deploy Supabase with Docker.

Docker is the easiest way to get started with self-hosted Supabase. It should only take you a few minutes to get up and running. This guide assumes you are running the command from the machine you intend to host from.


## Contents

1.  [Before you begin](#before-you-begin)
2.  [Installing and running Supabase](#installing-and-running-supabase)
3.  [Accessing your services](#accessing-supabase-studio)
4.  [Updating your services](#updating-your-services)
5.  [Securing your services](#securing-your-services)


## Before you begin

You need the following installed in your system: [Git](https://git-scm.com/downloads) and Docker ([Windows](https://docs.docker.com/desktop/install/windows-install/), [macOS](https://docs.docker.com/desktop/install/mac-install/), or [Linux](https://docs.docker.com/desktop/install/linux-install/)).


## Installing and running Supabase

Follow these steps to start Supabase on your machine:

After all the services have started you can see them running in the background:

```sh
docker compose ps
```

All of the services should have a status `running (healthy)`. If you see a status like `created` but not `running`, try starting that service manually with `docker compose start <service-name>`.


### Accessing Supabase Studio

You can access Supabase Studio through the API gateway on port `8000`. For example: `http://<your-ip>:8000`, or [localhost:8000](http://localhost:8000) if you are running Docker locally.

You will be prompted for a username and password. By default, the credentials are:

*   Username: `supabase`
*   Password: `this_password_is_insecure_and_should_be_updated`

You should change these credentials as soon as possible using the [instructions](#dashboard-authentication) below.


### Accessing the APIs

Each of the APIs are available through the same API gateway:

*   REST: `http://<your-ip>:8000/rest/v1/`
*   Auth: `http://<your-domain>:8000/auth/v1/`
*   Storage: `http://<your-domain>:8000/storage/v1/`
*   Realtime: `http://<your-domain>:8000/realtime/v1/`


### Accessing your Edge Functions

Edge Functions are stored in `volumes/functions`. The default setup has a `hello` Function that you can invoke on `http://<your-domain>:8000/functions/v1/hello`.

You can add new Functions as `volumes/functions/<FUNCTION_NAME>/index.ts`. Restart the `functions` service to pick up the changes: `docker compose restart functions --no-deps`


### Accessing Postgres

By default, the Supabase stack runs the [Supavisor](https://supabase.github.io/supavisor/development/docs/) connection pooler. Supavisor provides efficient management of database connections.

You can connect to the Postgres database using the following methods:

1.  For session-based connections (equivalent to direct Postgres connections):

```bash
psql 'postgres://postgres.your-tenant-id:your-super-secret-and-long-postgres-password@localhost:5432/postgres'
```

2.  For pooled transactional connections:

```bash
psql 'postgres://postgres.your-tenant-id:your-super-secret-and-long-postgres-password@localhost:6543/postgres'
```

The default tenant ID is `your-tenant-id`, and the default password is `your-super-secret-and-long-postgres-password`. You should change these as soon as possible using the [instructions below](#update-secrets).

By default, the database is not accessible from outside the local machine but the pooler is. You can [change this](#exposing-your-postgres-database) by updating the `docker-compose.yml` file.

You may also want to connect to your Postgres database via an ORM or another direct method other than `psql`.

For this you can use the standard Postgres connection string.
You can find the the environment values mentioned below in the `.env` file which will be covered in the next section.

    postgres://postgres:[POSTGRES_PASSWORD]@[your-server-ip]:5432/[POSTGRES_DB]


## Updating your services

For security reasons, we "pin" the versions of each service in the docker-compose file (these versions are updated ~monthly). If you want to update any services immediately, you can do so by updating the version number in the docker compose file and then running `docker compose pull`. You can find all the latest docker images in the [Supabase Docker Hub](https://hub.docker.com/u/supabase).

You should update your services frequently to get the latest features and bug fixes and security patches. Note that you will need to restart the services to pick up the changes, which will result in some downtime for your services.

**Example**
You'll want to update the Studio(Dashboard) frequently to get the latest features and bug fixes. To update the Dashboard:

1.  Visit the [supabase/studio](https://hub.docker.com/r/supabase/studio/tags) image in the [Supabase Docker Hub](https://hub.docker.com/u/supabase)
2.  Find the latest version (tag) number. It will look something like `20241029-46e1e40`
3.  Update the `image` field in the `docker-compose.yml` file to the new version. It should look like this: `image: supabase/studio:20241028-a265374`
4.  Run `docker compose pull` and then `docker compose up -d` to restart the service with the new version.


## Securing your services

While we provided you with some example secrets for getting started, you should NEVER deploy your Supabase setup using the defaults we have provided. Follow all of the steps in this section to ensure you have a secure setup, and then [restart all services](#restarting-all-services) to pick up the changes.


### Generate API keys

We need to generate secure keys for accessing your services. We'll use the `JWT Secret` to generate `anon` and `service` API keys using the form below.

1.  **Obtain a Secret**: Use the 40-character secret provided, or create your own. If creating, ensure it's a strong, random string of 40 characters.
2.  **Store Securely**: Save the secret in a secure location on your local machine. Don't share this secret publicly or commit it to version control.
3.  **Generate a JWT**: Use the form below to generate a new `JWT` using your secret.


### Update API keys

Run this form twice to generate new `anon` and `service` API keys. Replace the values in the `./docker/.env` file:

*   `ANON_KEY` - replace with an `anon` key
*   `SERVICE_ROLE_KEY` - replace with a `service` key

You will need to [restart](#restarting-all-services) the services for the changes to take effect.


### Update secrets

Update the `./docker/.env` file with your own secrets. In particular, these are required:

*   `POSTGRES_PASSWORD`: the password for the `postgres` role.
*   `JWT_SECRET`: used by PostgREST and GoTrue, among others.
*   `SITE_URL`: the base URL of your site.
*   `SMTP_*`: mail server credentials. You can use any SMTP server.
*   `POOLER_TENANT_ID`: the tenant-id that will be used by Supavisor pooler for your connection string

You will need to [restart](#restarting-all-services) the services for the changes to take effect.


### Dashboard authentication

The Dashboard is protected with basic authentication. The default user and password MUST be updated before using Supabase in production.
Update the following values in the `./docker/.env` file:

*   `DASHBOARD_USERNAME`: The default username for the Dashboard
*   `DASHBOARD_PASSWORD`: The default password for the Dashboard

You can also add more credentials for multiple users in `./docker/volumes/api/kong.yml`. For example:

```yaml docker/volumes/api/kong.yml
basicauth_credentials:
  - consumer: DASHBOARD
    username: user_one
    password: password_one
  - consumer: DASHBOARD
    username: user_two
    password: password_two
```

To enable all dashboard features outside of `localhost`, update the following value in the `./docker/.env` file:

*   `SUPABASE_PUBLIC_URL`: The URL or IP used to access the dashboard

You will need to [restart](#restarting-all-services) the services for the changes to take effect.


## Restarting all services

You can restart services to pick up any configuration changes by running:

```sh
# Stop and remove the containers
docker compose down

# Recreate and start the containers
docker compose up -d
```

Be aware that this will result in downtime. Simply restarting the services does not apply configuration changes.


## Stopping all services

You can stop Supabase by running `docker compose stop` in same directory as your `docker-compose.yml` file.


## Uninstalling

You can stop Supabase by running the following in same directory as your `docker-compose.yml` file:

```sh
# Stop docker and remove volumes:
docker compose down -v

# Remove Postgres data:
rm -rf volumes/db/data/
```

This will destroy all data in the database and storage volumes, so be careful!


## Managing your secrets

Many components inside Supabase use secure secrets and passwords. These are listed in the self-hosting [env file](https://github.com/supabase/supabase/blob/master/docker/.env.example), but we strongly recommend using a secrets manager when deploying to production. Plain text files like dotenv lead to accidental costly leaks.

Some suggested systems include:

*   [Doppler](https://www.doppler.com/)
*   [Infisical](https://infisical.com/)
*   [Key Vault](https://docs.microsoft.com/en-us/azure/key-vault/general/overview) by Azure (Microsoft)
*   [Secrets Manager](https://aws.amazon.com/secrets-manager/) by AWS
*   [Secrets Manager](https://cloud.google.com/secret-manager) by GCP
*   [Vault](https://www.hashicorp.com/products/vault) by HashiCorp


## Advanced

Everything beyond this point in the guide helps you understand how the system works and how you can modify it to suit your needs.


### Architecture

Supabase is a combination of open source tools, each specifically chosen for Enterprise-readiness.

If the tools and communities already exist, with an MIT, Apache 2, or equivalent open license, we will use and support that tool.
If the tool doesn't exist, we build and open source it ourselves.

*   [Kong](https://github.com/Kong/kong) is a cloud-native API gateway.
*   [GoTrue](https://github.com/supabase/gotrue) is an JWT based API for managing users and issuing JWT tokens.
*   [PostgREST](http://postgrest.org/) is a web server that turns your Postgres database directly into a RESTful API
*   [Realtime](https://github.com/supabase/realtime) is an Elixir server that allows you to listen to Postgres inserts, updates, and deletes using WebSockets. Realtime polls Postgres' built-in replication functionality for database changes, converts changes to JSON, then broadcasts the JSON over WebSockets to authorized clients.
*   [Storage](https://github.com/supabase/storage-api) provides a RESTful interface for managing Files stored in S3, using Postgres to manage permissions.
*   [`postgres-meta`](https://github.com/supabase/postgres-meta) is a RESTful API for managing your Postgres, allowing you to fetch tables, add roles, and run queries, etc.
*   [Postgres](https://www.postgresql.org/) is an object-relational database system with over 30 years of active development that has earned it a strong reputation for reliability, feature robustness, and performance.
*   [Supavisor](https://github.com/supabase/supavisor) is a scalable connection pooler for Postgres, allowing for efficient management of database connections.

For the system to work cohesively, some services require additional configuration within the Postgres database. For example, the APIs and Auth system require several [default roles](/docs/guides/database/postgres/roles) and the `pgjwt` Postgres extension.

You can find all the default extensions inside the [schema migration scripts repo](https://github.com/supabase/postgres/tree/develop/migrations). These scripts are mounted at `/docker-entrypoint-initdb.d` to run automatically when starting the database container.


### Configuring services

Each system has a number of configuration options which can be found in the relevant product documentation.

*   [Postgres](https://hub.docker.com/_/postgres/)
*   [PostgREST](https://postgrest.org/en/stable/configuration.html)
*   [Realtime](https://github.com/supabase/realtime#server)
*   [Auth](https://github.com/supabase/auth)
*   [Storage](https://github.com/supabase/storage-api)
*   [Kong](https://docs.konghq.com/gateway/latest/install/docker/)
*   [Supavisor](https://supabase.github.io/supavisor/development/docs/)

These configuration items are generally added to the `env` section of each service, inside the `docker-compose.yml` section. If these configuration items are sensitive, they should be stored in a [secret manager](/docs/guides/self-hosting#managing-your-secrets) or using an `.env` file and then referenced using the `${}` syntax.


### Common configuration

Each system can be [configured](../self-hosting#configuration) independently. Some of the most common configuration options are listed below.


#### Configuring an email server

You will need to use a production-ready SMTP server for sending emails. You can configure the SMTP server by updating the following environment variables:

```sh .env
SMTP_ADMIN_EMAIL=
SMTP_HOST=
SMTP_PORT=
SMTP_USER=
SMTP_PASS=
SMTP_SENDER_NAME=
```

We recommend using [AWS SES](https://aws.amazon.com/ses/). It's extremely cheap and reliable. Restart all services to pick up the new configuration.


#### Configuring S3 Storage

By default all files are stored locally on the server. You can configure the Storage service to use S3 by updating the following environment variables:

```yaml docker-compose.yml
storage:
  environment: STORAGE_BACKEND=s3
    GLOBAL_S3_BUCKET=name-of-your-s3-bucket
    REGION=region-of-your-s3-bucket
```

You can find all the available options in the [storage repository](https://github.com/supabase/storage-api/blob/master/.env.sample). Restart the `storage` service to pick up the changes: `docker compose restart storage --no-deps`


#### Configuring Supabase AI Assistant

Configuring the Supabase AI Assistant is optional. By adding your own `OPENAI_API_KEY`, you can enable AI services, which help with writing SQL queries, statements, and policies.


#### Setting database's `log_min_messages`

By default, `docker compose` sets the database's `log_min_messages` configuration to `fatal` to prevent redundant logs generated by Realtime. You can configure `log_min_messages` using any of the Postgres [Severity Levels](https://www.postgresql.org/docs/current/runtime-config-logging.html#RUNTIME-CONFIG-SEVERITY-LEVELS).


#### Accessing Postgres through Supavisor

By default, the Postgres database is accessible through the Supavisor connection pooler. This allows for more efficient management of database connections. You can connect to the pooled database using the `POOLER_PROXY_PORT_TRANSACTION` port and `POSTGRES_PORT` for session based connections.

For more information on configuring and using Supavisor, see the [Supavisor documentation](https://supabase.github.io/supavisor/).


#### Exposing your Postgres database

If you need direct access to the Postgres database without going through Supavisor, you can expose it by updating the `docker-compose.yml` file:

```yaml docker-compose.yml
# Comment or remove the supavisor section of the docker-compose file
#  supavisor:
#    ports:
# ...
db:
  ports:
    - ${POSTGRES_PORT}:${POSTGRES_PORT}
```

This is less-secure, so make sure you are running a firewall in front of your server.


#### File storage backend on macOS

By default, Storage backend is set to `file`, which is to use local files as the storage backend. For macOS compatibility, you need to choose `VirtioFS` as the Docker container file sharing implementation (in Docker Desktop -> Preferences -> General).


#### Setting up logging with the Analytics server

Additional configuration is required for self-hosting the Analytics server. For the full setup instructions, see [Self Hosting Analytics](https://supabase.com/docs/reference/self-hosting-analytics/introduction#getting-started).


### Upgrading Analytics

Due to the changes in the Analytics server, you will need to run the following commands to upgrade your Analytics server:

```sh
### Destroy analytics to transition to postgres self hosted solution without other data loss

# Enter the container and use your .env POSTGRES_PASSWORD value to login
docker exec -it $(docker ps | grep supabase-db | awk '{print $1}') psql -U supabase_admin --password
# Drop all the data in the _analytics schema
DROP PUBLICATION logflare_pub; DROP SCHEMA _analytics CASCADE; CREATE SCHEMA _analytics;\q
# Drop the analytics container
docker rm supabase-analytics
```

***


## Demo

A minimal setup working on Ubuntu, hosted on DigitalOcean.


### Demo using DigitalOcean

1.  A DigitalOcean Droplet with 1 GB memory and 25 GB solid-state drive (SSD) is sufficient to start
2.  To access the Dashboard, use the ipv4 IP address of your Droplet.
3.  If you're unable to access Dashboard, run `docker compose ps` to see if the Studio service is running and healthy.


# Storage

Use Supabase to store and serve files.

Supabase Storage makes it simple to upload and serve files of any size, providing a robust framework for file access controls.


## Features

You can use Supabase Storage to store images, videos, documents, and any other file type. Serve your assets with a global CDN to reduce latency from over 285 cities globally. Supabase Storage includes a built-in image optimizer, so you can resize and compress your media files on the fly.


## Examples

Check out all of the Storage [templates and examples](https://github.com/supabase/supabase/tree/master/examples/storage) in our GitHub repository.


## Resources

Find the source code and documentation in the Supabase GitHub repository.


# Creating Buckets



You can create a bucket using the Supabase Dashboard. Since storage is interoperable with your Postgres database, you can also use SQL or our client libraries.
Here we create a bucket called "avatars":


## Restricting uploads

When creating a bucket you can add additional configurations to restrict the type or size of files you want this bucket to contain.
For example, imagine you want to allow your users to upload only images to the `avatars` bucket and the size must not be greater than 1MB.

You can achieve the following by providing: `allowedMimeTypes` and `maxFileSize`

```js
import { createClient } from '@supabase/supabase-js'
const supabase = createClient(process.env.SUPABASE_URL!, process.env.SUPABASE_KEY!)

// ---cut---
// Use the JS library to create a bucket.

const { data, error } = await supabase.storage.createBucket('avatars', {
  public: true,
  allowedMimeTypes: ['image/*'],
  fileSizeLimit: '1MB',
})
```

If an upload request doesn't meet the above restrictions it will be rejected.

For more information check [File Limits](/docs/guides/storage/uploads/file-limits) Section.


# Storage Buckets



Buckets allow you to keep your files organized and determines the [Access Model](#access-model) for your assets. [Upload restrictions](/docs/guides/storage/buckets/creating-buckets#restricting-uploads) like max file size and allowed content types are also defined at the bucket level.


## Access model

There are 2 access models for buckets, **public** and **private** buckets.


### Private buckets

When a bucket is set to **Private** all operations are subject to access control via [RLS policies](/docs/guides/storage/security/access-control). This also applies when downloading assets. Buckets are private by default.

The only ways to download assets within a private bucket is to:

*   Use the [download method](/docs/reference/javascript/storage-from-download) by providing a authorization header containing your user's JWT. The RLS policy you create on the `storage.objects` table will use this user to determine if they have access.
*   Create a signed URL with the [`createSignedUrl` method](/docs/reference/javascript/storage-from-createsignedurl) that can be accessed for a limited time.


#### Example use cases:

*   Uploading users' sensitive documents
*   Securing private assets by using RLS to set up fine-grain access controls


### Public buckets

When a bucket is designated as 'Public,' it effectively bypasses access controls for both retrieving and serving files within the bucket. This means that anyone who possesses the asset URL can readily access the file.

Access control is still enforced for other types of operations including uploading, deleting, moving, and copying.


#### Example use cases:

*   User profile pictures
*   User public media
*   Blog post content

Public buckets are more performant than private buckets since they are [cached differently](/docs/guides/storage/cdn/fundamentals#public-vs-private-buckets).


# Storage CDN



All assets uploaded to Supabase Storage are cached on a Content Delivery Network (CDN) to improve the latency for users all around the world. CDNs are a geographically distributed set of servers or **nodes** which cache content from an **origin server**. For Supabase Storage, the origin is the storage server running in the [same region as your project](https://supabase.com/dashboard/project/_/settings/general). Aside from performance, CDNs also help with security and availability by mitigating Distributed Denial of Service (DDoS) and other application attacks.


### Example

Let's walk through an example of how a CDN helps with performance.

A new bucket is created for a Supabase project launched in Singapore. All requests to the Supabase Storage API are routed to the CDN first.

A user from the United States requests an object and is routed to the U.S. CDN. At this point, that CDN node does not have the object in its cache and pings the origin server in Singapore.
![CDN cache miss](/docs/img/cdn-cache-miss.png)

Another user, also in the United States, requests the same object and is served directly from the CDN cache in the United States instead of routing the request back to Singapore.
![CDN cache hit](/docs/img/cdn-cache-hit.png)

The cache status of a particular request is sent in the `cf-cache-status` header. A cache status of `MISS` indicates that the CDN node did not have the object in its cache and had to ping the origin to get it. A cache status of `HIT` indicates that the object was sent directly from the CDN.


### Public vs private buckets

Objects in public buckets do not require any authorization to access objects. This leads to a better cache hit rate compared to private buckets.

For private buckets, permissions for accessing each object is checked on a per user level. For example, if two different users access the same object in a private bucket from the same region, it results in a cache miss for both the users since they might have different security policies attached to them.
On the other hand, if two different users access the same object in a public bucket from the same region, it results in a cache hit for the second user.


# Cache Metrics



Cache hits can be determined via the `metadata.response.headers.cf_cache_status` key in our [Logs Explorer](/docs/guides/platform/logs#logs-explorer). Any value that corresponds to either `HIT`, `STALE`, `REVALIDATED`, or `UPDATING` is categorized as a cache hit.
The following example query will show the top cache misses from the `edge_logs`:

```sql
select
  r.path as path,
  r.search as search,
  count(id) as count
from
  edge_logs as f
  cross join unnest(f.metadata) as m
  cross join unnest(m.request) as r
  cross join unnest(m.response) as res
  cross join unnest(res.headers) as h
where
  starts_with(r.path, '/storage/v1/object')
  and r.method = 'GET'
  and h.cf_cache_status in ('MISS', 'NONE/UNKNOWN', 'EXPIRED', 'BYPASS', 'DYNAMIC')
group by path, search
order by count desc
limit 50;
```

Try out [this query](https://supabase.com/dashboard/project/_/logs/explorer?q=%0Aselect%0A++r.path+as+path%2C%0A++r.search+as+search%2C%0A++count%28id%29+as+count%0Afrom%0A++edge_logs+as+f%0A++cross+join+unnest%28f.metadata%29+as+m%0A++cross+join+unnest%28m.request%29+as+r%0A++cross+join+unnest%28m.response%29+as+res%0A++cross+join+unnest%28res.headers%29+as+h%0Awhere%0A++starts_with%28r.path%2C+%27%2Fstorage%2Fv1%2Fobject%27%29%0A++and+r.method+%3D+%27GET%27%0A++and+h.cf_cache_status+in+%28%27MISS%27%2C+%27NONE%2FUNKNOWN%27%2C+%27EXPIRED%27%2C+%27BYPASS%27%2C+%27DYNAMIC%27%29%0Agroup+by+path%2C+search%0Aorder+by+count+desc%0Alimit+50%3B) in the Logs Explorer.

Your cache hit ratio over time can then be determined using the following query:

```sql
select
  timestamp_trunc(timestamp, hour) as timestamp,
  countif(h.cf_cache_status in ('HIT', 'STALE', 'REVALIDATED', 'UPDATING')) / count(f.id) as ratio
from
  edge_logs as f
  cross join unnest(f.metadata) as m
  cross join unnest(m.request) as r
  cross join unnest(m.response) as res
  cross join unnest(res.headers) as h
where starts_with(r.path, '/storage/v1/object') and r.method = 'GET'
group by timestamp
order by timestamp desc;
```

Try out [this query](https://supabase.com/dashboard/project/_/logs/explorer?q=%0Aselect%0A++timestamp_trunc%28timestamp%2C+hour%29+as+timestamp%2C%0A++countif%28h.cf_cache_status+in+%28%27HIT%27%2C+%27STALE%27%2C+%27REVALIDATED%27%2C+%27UPDATING%27%29%29+%2F+count%28f.id%29+as+ratio%0Afrom%0A++edge_logs+as+f%0A++cross+join+unnest%28f.metadata%29+as+m%0A++cross+join+unnest%28m.request%29+as+r%0A++cross+join+unnest%28m.response%29+as+res%0A++cross+join+unnest%28res.headers%29+as+h%0Awhere+starts_with%28r.path%2C+%27%2Fstorage%2Fv1%2Fobject%27%29+and+r.method+%3D+%27GET%27%0Agroup+by+timestamp%0Aorder+by+timestamp+desc%3B) in the Logs Explorer.


# Smart CDN



With Smart CDN caching enabled, the asset metadata in your database is synchronized to the edge. This automatically revalidates the cache when the asset is changed or deleted.

Moreover, the Smart CDN achieves a greater cache hit rate by shielding the origin server from asset requests that remain unchanged, even when different query strings are used in the URL.


## Cache duration

When Smart CDN is enabled, the asset is cached on the CDN for as long as possible. You can still control how long assets are stored in the browser using the [`cacheControl`](/docs/reference/javascript/storage-from-upload) option when uploading a file. Smart CDN caching works with all types of storage operations including signed URLs.

When a file is updated or deleted, the CDN cache is automatically invalidated to reflect the change (including transformed images). It can take **up to 60 seconds** for the CDN cache to be invalidated as the asset metadata has to propagate across all the data-centers around the globe.

When an asset is invalidated at the CDN level, browsers may not update its cache. This is where cache eviction comes into play.


## Cache eviction

Even when an asset is marked as invalidated at the CDN level, browsers may not refresh their cache for that asset.

If you have assets that undergo frequent updates, it is advisable to upload the new asset to a different path. This approach ensures that you always have the most up-to-date asset accessible.

If you anticipate that your asset might be deleted, it's advisable to set a shorter browser Time-to-Live (TTL) value using the `cacheControl` option. The default TTL is typically set to 1 hour, which is generally a reasonable default value.


## Bypassing cache

If you need to ensure assets refresh directly from the origin server and bypass the cache, you can achieve this by adding a unique query string to the URL.

For instance, you can use a URL like `/storage/v1/object/sign/profile-pictures/cat.jpg?version=1` with a long browser cache (e.g., 1 year). To update the picture, increment the version query parameter in the URL, like `/storage/v1/object/sign/profile-pictures/cat.jpg?version=2`. The CDN will recognize it as a new object and fetch the updated version from the origin.


# Error Codes

Learn about the Storage error codes and how to resolve them

## Storage error codes

Error codes in Storage are returned as part of the response body. They are useful for debugging and understanding what went wrong with your request.
The error codes are returned in the following format:

```json
{
  "code": "error_code",
  "message": "error_message"
}
```

Here is the full list of error codes and their descriptions:

| `ErrorCode`                 | Description                                                     | `StatusCode` | Resolution                                                                                                                                                                                           |
| --------------------------- | --------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NoSuchBucket`              | The specified bucket does not exist.                            | 404          | Verify the bucket name and ensure it exists in the system, if it exists you don't have permissions to access it.                                                                                     |
| `NoSuchKey`                 | The specified key does not exist.                               | 404          | Check the key name and ensure it exists in the specified bucket, if it exists you don't have permissions to access it.                                                                               |
| `NoSuchUpload`              | The specified upload does not exist.                            | 404          | The upload ID provided might not exists or the Upload was previously aborted                                                                                                                         |
| `InvalidJWT`                | The provided JWT (JSON Web Token) is invalid.                   | 401          | The JWT provided might be expired or malformed, provide a valid JWT                                                                                                                                  |
| `InvalidRequest`            | The request is not properly formed.                             | 400          | Review the request parameters and structure, ensure they meet the API's requirements, the error message will provide more details                                                                    |
| `TenantNotFound`            | The specified tenant does not exist.                            | 404          | The Storage service had issues while provisioning, [Contact Support](https://supabase.com/dashboard/support/new)                                                                                     |
| `EntityTooLarge`            | The entity being uploaded is too large.                         | 413          | Verify the max-file-limit is equal or higher to the resource you are trying to upload, you can change this value on the [Project Setting](https://supabase.com/dashboard/project/_/settings/storage) |
| `InternalError`             | An internal server error occurred.                              | 500          | Investigate server logs to identify the cause of the internal error. If you think it's a Storage error [Contact Support](https://supabase.com/dashboard/support/new)                                 |
| `ResourceAlreadyExists`     | The specified resource already exists.                          | 409          | Use a different name or identifier for the resource to avoid conflicts. Use `x-upsert:true` header to overwrite the resource.                                                                        |
| `InvalidBucketName`         | The specified bucket name is invalid.                           | 400          | Ensure the bucket name follows the naming conventions and does not contain invalid characters.                                                                                                       |
| `InvalidKey`                | The specified key is invalid.                                   | 400          | Verify the key name and ensure it follows the naming conventions.                                                                                                                                    |
| `InvalidRange`              | The specified range is not valid.                               | 416          | Make sure that range provided is within the file size boundary and follow the [HTTP Range spec](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Range)                                     |
| `InvalidMimeType`           | The specified MIME type is not valid.                           | 400          | Provide a valid MIME type, ensure using the standard MIME type format                                                                                                                                |
| `InvalidUploadId`           | The specified upload ID is invalid.                             | 400          | The upload ID provided is invalid or missing. Make sure to provide a active upload ID                                                                                                                |
| `KeyAlreadyExists`          | The specified key already exists.                               | 409          | Use a different key name to avoid conflicts with existing keys. Use `x-upsert:true` header to overwrite the resource.                                                                                |
| `BucketAlreadyExists`       | The specified bucket already exists.                            | 409          | Choose a unique name for the bucket that does not conflict with existing buckets.                                                                                                                    |
| `DatabaseTimeout`           | Timeout occurred while accessing the database.                  | 504          | Investigate database performance and increase the default pool size. If this error still occurs, upgrade your instance                                                                               |
| `InvalidSignature`          | The signature provided does not match the calculated signature. | 403          | Check that you are providing the correct signature format, for more information refer to [SignatureV4](https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html)          |
| `SignatureDoesNotMatch`     | The request signature does not match the calculated signature.  | 403          | Check your credentials, access key id / access secret key / region that are all correct, refer to [S3 Authentication](/docs/guides/storage/s3/authentication).                                       |
| `AccessDenied`              | Access to the specified resource is denied.                     | 403          | Check that you have the correct RLS policy to allow access to this resource                                                                                                                          |
| `ResourceLocked`            | The specified resource is locked.                               | 423          | This resource cannot be altered while there is a lock. Wait and try the request again                                                                                                                |
| `DatabaseError`             | An error occurred while accessing the database.                 | 500          | Investigate database logs and system configuration to identify and address the database error.                                                                                                       |
| `MissingContentLength`      | The Content-Length header is missing.                           | 411          | Ensure the Content-Length header is included in the request with the correct value.                                                                                                                  |
| `MissingParameter`          | A required parameter is missing in the request.                 | 400          | Provide all required parameters in the request to fulfill the API's requirements. The message field will contain more details                                                                        |
| `InvalidUploadSignature`    | The provided upload signature is invalid.                       | 403          | The `MultiPartUpload` record was altered while the upload was ongoing, the signature do not match. Do not alter the upload record                                                                    |
| `LockTimeout`               | Timeout occurred while waiting for a lock.                      | 423          | The lock couldn't be acquired within the specified timeout. Wait and try the request again                                                                                                           |
| `S3Error`                   | An error occurred related to Amazon S3.                         | -            | Refer to Amazon S3 documentation or [Contact Support](https://supabase.com/dashboard/support/new) for assistance with resolving the S3 error.                                                        |
| `S3InvalidAccessKeyId`      | The provided AWS access key ID is invalid.                      | 403          | Verify the AWS access key ID provided and ensure it is correct and active.                                                                                                                           |
| `S3MaximumCredentialsLimit` | The maximum number of credentials has been reached.             | 400          | The maximum limit of credentials is reached.                                                                                                                                                         |
| `InvalidChecksum`           | The checksum of the entity does not match.                      | 400          | Recalculate the checksum of the entity and ensure it matches the one provided in the request.                                                                                                        |
| `MissingPart`               | A part of the entity is missing.                                | 400          | Ensure all parts of the entity are included in the request before completing the operation.                                                                                                          |
| `SlowDown`                  | The request rate is too high and has been throttled.            | 503          | Reduce the request rate or implement exponential backoff and retry mechanisms to handle throttling.                                                                                                  |


## Legacy error codes

As we are transitioning to a new error code system, you might still see the following error format:

```json
{
  "httpStatusCode": 400,
  "code": "error_code",
  "message": "error_message"
}
```

Here's a list of the most common error codes and their potential resolutions:


### 404 `not_found`

Indicates that the resource is not found or you don't have the correct permission to access it
**Resolution:**

*   Add a RLS policy to grant permission to the resource. See our [Access Control docs](/docs/guides/storage/uploads/access-control) for more information.
*   Ensure you include the user `Authorization` header
*   Verify the object exists


### 409 `already_exists`

Indicates that the resource already exists.
**Resolution:**

*   Use the `upsert` functionality in order to overwrite the file. Find out more [here](/docs/guides/storage/uploads/standard-uploads#overwriting-files).


### 403 `unauthorized`

You don't have permission to action this request
**Resolution:**

*   Add RLS policy to grant permission. See our [Access Control docs](/docs/guides/storage/security/access-control) for more information.
*   Ensure you include the user `Authorization` header


### 429 `too many requests`

This problem typically arises when a large number of clients are concurrently interacting with the Storage service, and the pooler has reached its `max_clients` limit.

**Resolution:**

*   Increase the max\_clients limits of the pooler.
*   Upgrade to a bigger project compute instance [here](https://supabase.com/dashboard/project/_/settings/addons).


### 544 `database_timeout`

This problem arises when a high number of clients are concurrently using the Storage service, and Postgres doesn't have enough available connections to efficiently handle requests to Storage.

**Resolution:**

*   Increase the pool\_size limits of the pooler.
*   Upgrade to a bigger project compute instance [here](https://supabase.com/dashboard/project/_/settings/addons).


### 500 `internal_server_error`

This issue occurs where there is a unhandled error.
**Resolution:**

*   File a support ticket to Storage team [here](https://supabase.com/dashboard/support/new)


# Logs



Accessing the [Storage Logs](/dashboard/project/__/logs/explorer?q=select+id%2C+storage_logs.timestamp%2C+event_message+from+storage_logs%0A++%0A++order+by+timestamp+desc%0A++limit+100%0A++) allows you to examine all incoming request logs to your Storage service. You can also filter logs and delve into specific aspects of your requests.


### Common log queries


#### Filter by status 5XX error

```sql
select
  id,
  storage_logs.timestamp,
  event_message,
  r.statusCode,
  e.message as errorMessage,
  e.raw as rawError
from
  storage_logs
  cross join unnest(metadata) as m
  cross join unnest(m.res) as r
  cross join unnest(m.error) as e
where r.statusCode >= 500
order by timestamp desc
limit 100;
```


#### Filter by status 4XX error

```sql
select
  id,
  storage_logs.timestamp,
  event_message,
  r.statusCode,
  e.message as errorMessage,
  e.raw as rawError
from
  storage_logs
  cross join unnest(metadata) as m
  cross join unnest(m.res) as r
  cross join unnest(m.error) as e
where r.statusCode >= 400 and r.statusCode < 500
order by timestamp desc
limit 100;
```


#### Filter by method

```sql
select id, storage_logs.timestamp, event_message, r.method
from
  storage_logs
  cross join unnest(metadata) as m
  cross join unnest(m.req) as r
where r.method in ("POST")
order by timestamp desc
limit 100;
```


#### Filter by IP address

```sql
select id, storage_logs.timestamp, event_message, r.remoteAddress
from
  storage_logs
  cross join unnest(metadata) as m
  cross join unnest(m.req) as r
where r.remoteAddress in ("IP_ADDRESS")
order by timestamp desc
limit 100;
```


# Copy Objects

Learn how to copy and move objects

## Copy objects

You can copy objects between buckets or within the same bucket. Currently only objects up to 5 GB can be copied using the API.

When making a copy of an object, the owner of the new object will be the user who initiated the copy operation.


### Copying objects within the same bucket

To copy an object within the same bucket, use the `copy` method.

```javascript
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('your_project_url', 'your_supabase_api_key')

// ---cut---
await supabase.storage.from('avatars').copy('public/avatar1.png', 'private/avatar2.png')
```


### Copying objects across buckets

To copy an object across buckets, use the `copy` method and specify the destination bucket.

```javascript
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('your_project_url', 'your_supabase_api_key')

// ---cut---
await supabase.storage.from('avatars').copy('public/avatar1.png', 'private/avatar2.png', {
  destinationBucket: 'avatars2',
})
```


## Move objects

You can move objects between buckets or within the same bucket. Currently only objects up to 5GB can be moved using the API.

When moving an object, the owner of the new object will be the user who initiated the move operation. Once the object is moved, the original object will no longer exist.


### Moving objects within the same bucket

To move an object within the same bucket, you can use the `move` method.

```javascript
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('your_project_url', 'your_supabase_api_key')

// ---cut---
const { data, error } = await supabase.storage
  .from('avatars')
  .move('public/avatar1.png', 'private/avatar2.png')
```


### Moving objects across buckets

To move an object across buckets, use the `move` method and specify the destination bucket.

```javascript
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('your_project_url', 'your_supabase_api_key')

// ---cut---
await supabase.storage.from('avatars').move('public/avatar1.png', 'private/avatar2.png', {
  destinationBucket: 'avatars2',
})
```


## Permissions

For a user to move and copy objects, they need `select` permission on the source object and `insert` permission on the destination object. For example:

```sql
create policy "User can select their own objects (in any buckets)"
on storage.objects
for select
to authenticated
using (
    owner_id = (select auth.uid())
);

create policy "User can upload in their own folders (in any buckets)"
on storage.objects
for insert
to authenticated
with check (
    (storage.folder(name))[1] = (select auth.uid())
);
```


# Delete Objects

Learn about deleting objects

When you delete one or more objects from a bucket, the files are permanently removed and not recoverable. You can delete a single object or multiple objects at once.


## Delete objects

To delete one or more objects, use the `remove` method.

```javascript
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('your_project_url', 'your_supabase_api_key')

// ---cut---
await supabase.storage.from('bucket').remove(['object-path-2', 'folder/avatar2.png'])
```


## RLS

To delete an object, the user must have the `delete` permission on the object. For example:

```sql
create policy "User can delete their own objects"
on storage.objects
for delete
TO authenticated
USING (
    owner = (select auth.uid()::text)
);
```


# Pricing



You are charged for the total size of all assets in your buckets.

For a detailed explanation of how charges are calculated, refer to [Manage Storage size usage](/docs/guides/platform/manage-your-usage/storage-size).


# Storage Optimizations

Scaling Storage

Here are some optimizations that you can consider to improve performance and reduce costs as you start scaling Storage.


## Egress

If your project has high egress, these optimizations can help reducing it.


#### Resize images

Images typically make up most of your egress. By keeping them as small as possible, you can cut down on egress and boost your application's performance. You can take advantage of our [Image Transformation](/docs/guides/storage/serving/image-transformations) service to optimize any image on the fly.


#### Set a high cache-control value

Using the browser cache can effectively lower your egress since the asset remains stored in the user's browser after the initial download. Setting a high `cache-control` value ensures the asset stays in the user's browser for an extended period, decreasing the need to download it from the server repeatedly. Read more [here](/docs/guides/storage/cdn/smart-cdn#cache-duration)


#### Limit the upload size

You have the option to set a maximum upload size for your bucket. Doing this can prevent users from uploading and then downloading excessively large files. You can control the maximum file size by configuring this option at the [bucket level](/docs/guides/storage/buckets/creating-buckets).


## Optimize listing objects

Once you have a substantial number of objects, you might observe that the `supabase.storage.list()` method starts to slow down. This occurs because the endpoint is quite generic and attempts to retrieve both folders and objects in a single query. While this approach is very useful for building features like the Storage viewer on the Supabase dashboard, it can impact performance with a large number of objects.

If your application doesn't need the entire hierarchy computed you can speed up drastically the query execution for listing your objects by creating a Postgres function as following:

```sql
create or replace function list_objects(
    bucketid text,
    prefix text,
    limits int default 100,
    offsets int default 0
) returns table (
    name text,
    id uuid,
    updated_at timestamptz,
    created_at timestamptz,
    last_accessed_at timestamptz,
    metadata jsonb
) as $$
begin
    return query SELECT
        objects.name,
        objects.id,
        objects.updated_at,
        objects.created_at,
        objects.last_accessed_at,
        objects.metadata
    FROM storage.objects
    WHERE objects.name like prefix || '%'
    AND bucket_id = bucketid
    ORDER BY name ASC
    LIMIT limits
    OFFSET offsets;
end;
$$ language plpgsql stable;
```

You can then use the your Postgres function as following:

Using SQL:

```sql
select * from list_objects('bucket_id', '', 100, 0);
```

Using the SDK:

```js
const { data, error } = await supabase.rpc('list_objects', {
  bucketid: 'yourbucket',
  prefix: '',
  limit: 100,
  offset: 0,
})
```


## Optimizing RLS

When creating RLS policies against the storage tables you can add indexes to the interested columns to speed up the lookup


# Storage Quickstart

Learn how to use Supabase to store and serve files.

This guide shows the basic functionality of Supabase Storage. Find a full [example application on GitHub](https://github.com/supabase/supabase/tree/master/examples/user-management/nextjs-user-management).


## Concepts

Supabase Storage consists of Files, Folders, and Buckets.


### Files

Files can be any sort of media file. This includes images, GIFs, and videos. It is best practice to store files outside of your database because of their sizes. For security, HTML files are returned as plain text.


### Folders

Folders are a way to organize your files (just like on your computer). There is no right or wrong way to organize your files. You can store them in whichever folder structure suits your project.


### Buckets

Buckets are distinct containers for files and folders. You can think of them like "super folders". Generally you would create distinct buckets for different Security and Access Rules. For example, you might keep all video files in a "video" bucket, and profile pictures in an "avatar" bucket.


## Create a bucket

You can create a bucket using the Supabase Dashboard. Since the storage is interoperable with your Postgres database, you can also use SQL or our client libraries. Here we create a bucket called "avatars":


## Upload a file

You can upload a file from the Dashboard, or within a browser using our JS libraries.


## Download a file

You can download a file from the Dashboard, or within a browser using our JS libraries.


## Add security rules

To restrict access to your files you can use either the Dashboard or SQL.

***


# S3 Authentication

Learn about authenticating with Supabase Storage S3.

You have two options to authenticate with Supabase Storage S3:

*   Using the generated S3 access keys from your [project settings](/dashboard/project/_/settings/storage) (Intended exclusively for server-side use)
*   Using a Session Token, which will allow you to authenticate with a user JWT token and provide limited access via Row Level Security (RLS).


## S3 access keys

To authenticate with S3, generate a pair of credentials (Access Key ID and Secret Access Key), copy the endpoint and region from the [project settings page](/dashboard/project/_/settings/storage).

This is all the information you need to connect to Supabase Storage using any S3-compatible service.


## Session token

You can authenticate to Supabase S3 with a user JWT token to provide limited access via RLS to all S3 operations. This is useful when you want initialize the S3 client on the server scoped to a specific user, or use the S3 client directly from the client side.

All S3 operations performed with the Session Token are scoped to the authenticated user. RLS policies on the Storage Schema are respected.

To authenticate with S3 using a Session Token, use the following credentials:

*   access\_key\_id: `project_ref`
*   secret\_access\_key: `anonKey`
*   session\_token: `valid jwt token`

For example, using the `aws-sdk` library:

```javascript
import { S3Client } from '@aws-sdk/client-s3'

const {
  data: { session },
} = await supabase.auth.getSession()

const client = new S3Client({
  forcePathStyle: true,
  region: 'project_region',
  endpoint: 'https://project_ref.supabase.co/storage/v1/s3',
  credentials: {
    accessKeyId: 'project_ref',
    secretAccessKey: 'anonKey',
    sessionToken: session.access_token,
  },
})
```


# S3 Compatibility

Learn about the compatibility of Supabase Storage with S3.

Supabase Storage is compatible with the S3 protocol. You can use any S3 client to interact with your Storage objects.

Storage supports [standard](/docs/guides/storage/uploads/standard-uploads), [resumable](/docs/guides/storage/uploads/resumable-uploads) and [S3 uploads](/docs/guides/storage/uploads/s3-uploads) and all these protocols are interoperable. You can upload a file with the S3 protocol and list it with the REST API or upload with Resumable uploads and list with S3.

Storage supports presigning a URL using query parameters. Specifically, Supabase Storage expects requests to be made using [AWS Signature Version 4](https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-query-string-auth.html). To enable this feature, enable the S3 connection via S3 protocol in the Settings page for Supabase Storage.


## Implemented endpoints

The most commonly used endpoints are implemented, and more will be added. Implemented S3 endpoints are marked with ✅ in the following tables.


### Bucket operations

| API Name                                                                                                                       | Feature                                                                                                                                                                                                                                                                                           |
| ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ✅ [ListBuckets](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListBuckets.html)                                         |                                                                                                                                                                                                                                                                                                   |
| ✅ [HeadBucket](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadBucket.html)                                           | ❌ Bucket Owner: ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                              |
| ✅ [CreateBucket](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateBucket.html)                                       | ❌ ACL: ❌ x-amz-acl ❌ x-amz-grant-full-control ❌ x-amz-grant-read ❌ x-amz-grant-read-acp ❌ x-amz-grant-write ❌ x-amz-grant-write-acp❌ Object Locking: ❌ x-amz-bucket-object-lock-enabled❌ Bucket Owner: ❌ x-amz-expected-bucket-owner |
| ✅ [DeleteBucket](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteBucket.html)                                       | ❌ Bucket Owner: ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                              |
| ✅ [GetBucketLocation](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketLocation.html)                             | ❌ Bucket Owner: ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                              |
| ❌ [DeleteBucketCors](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteBucketCors.html)                               | ❌ Bucket Owner: ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                              |
| ❌ [GetBucketEncryption](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketEncryption.html)                         | ❌ Bucket Owner: ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                              |
| ❌ [GetBucketLifecycleConfiguration](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketLifecycleConfiguration.html) | ❌ Bucket Owner: ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                              |
| ❌ [GetBucketCors](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketCors.html)                                     | ❌ Bucket Owner: ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                              |
| ❌ [PutBucketCors](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketCors.html)                                     | ❌ Checksums: ❌ x-amz-sdk-checksum-algorithm ❌ x-amz-checksum-algorithm❌ Bucket Owner: ❌ x-amz-expected-bucket-owner                                                                                                                                                      |
| ❌ [PutBucketLifecycleConfiguration](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketLifecycleConfiguration.html) | ❌ Checksums: ❌ x-amz-sdk-checksum-algorithm ❌ x-amz-checksum-algorithm❌ Bucket Owner: ❌ x-amz-expected-bucket-owner                                                                                                                                                      |


### Object operations

| API Name                                                                                                       | Feature                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ✅ [HeadObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html)                           | ✅ Conditional Operations: ✅ If-Match ✅ If-Modified-Since ✅ If-None-Match ✅ If-Unmodified-Since✅ Range: ✅ Range (has no effect in HeadObject) ✅ partNumber❌ SSE-C: ❌ x-amz-server-side-encryption-customer-algorithm ❌ x-amz-server-side-encryption-customer-key ❌ x-amz-server-side-encryption-customer-key-MD5❌ Request Payer: ❌ x-amz-request-payer❌ Bucket Owner: ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ✅ [ListObjects](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjects.html)                         | Query Parameters: ✅ delimiter ✅ encoding-type ✅ marker ✅ max-keys ✅ prefix❌ Request Payer: ❌ x-amz-request-payer❌ Bucket Owner: ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ✅ [ListObjectsV2](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html)                     | Query Parameters: ✅ list-type ✅ continuation-token ✅ delimiter ✅ encoding-type ✅ fetch-owner ✅ max-keys ✅ prefix ✅ start-after❌ Request Payer: ❌ x-amz-request-payer❌ Bucket Owner: ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ✅ [GetObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html)                             | ✅ Conditional Operations: ✅ If-Match ✅ If-Modified-Since ✅ If-None-Match ✅ If-Unmodified-Since✅ Range: ✅ Range ✅ PartNumber❌ SSE-C: ❌ x-amz-server-side-encryption-customer-algorithm ❌ x-amz-server-side-encryption-customer-key ❌ x-amz-server-side-encryption-customer-key-MD5❌ Request Payer: ❌ x-amz-request-payer❌ Bucket Owner: ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ✅ [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)                             | System Metadata: ✅ Content-Type ✅ Cache-Control ✅ Content-Disposition ✅ Content-Encoding ✅ Content-Language ✅ Expires ❌ Content-MD5❌ Object Lifecycle❌ Website: ❌ x-amz-website-redirect-location❌ SSE-C: ❌ x-amz-server-side-encryption ❌ x-amz-server-side-encryption-customer-algorithm ❌ x-amz-server-side-encryption-customer-key ❌ x-amz-server-side-encryption-customer-key-MD5 ❌ x-amz-server-side-encryption-aws-kms-key-id ❌ x-amz-server-side-encryption-context ❌ x-amz-server-side-encryption-bucket-key-enabled❌ Request Payer: ❌ x-amz-request-payer❌ Tagging: ❌ x-amz-tagging❌ Object Locking: ❌ x-amz-object-lock-mode ❌ x-amz-object-lock-retain-until-date ❌ x-amz-object-lock-legal-hold❌ ACL: ❌ x-amz-acl ❌ x-amz-grant-full-control ❌ x-amz-grant-read ❌ x-amz-grant-read-acp ❌ x-amz-grant-write-acp❌ Bucket Owner: ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ✅ [DeleteObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObject.html)                       | ❌ Multi-factor authentication: ❌ x-amz-mfa❌ Object Locking: ❌ x-amz-bypass-governance-retention❌ Request Payer: ❌ x-amz-request-payer❌ Bucket Owner: ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ✅ [DeleteObjects](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjects.html)                     | ❌ Multi-factor authentication: ❌ x-amz-mfa❌ Object Locking: ❌ x-amz-bypass-governance-retention❌ Request Payer: ❌ x-amz-request-payer❌ Bucket Owner: ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ✅ [ListMultipartUploads](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListMultipartUploads.html)       | ✅ Query Parameters: ✅ delimiter ✅ encoding-type ✅ key-marker ✅️ max-uploads ✅ prefix ✅ upload-id-marker                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ✅ [CreateMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateMultipartUpload.html)     | ✅ System Metadata: ✅ Content-Type ✅ Cache-Control ✅ Content-Disposition ✅ Content-Encoding ✅ Content-Language ✅ Expires ❌ Content-MD5❌ Website: ❌ x-amz-website-redirect-location❌ SSE-C: ❌ x-amz-server-side-encryption ❌ x-amz-server-side-encryption-customer-algorithm ❌ x-amz-server-side-encryption-customer-key ❌ x-amz-server-side-encryption-customer-key-MD5 ❌ x-amz-server-side-encryption-aws-kms-key-id ❌ x-amz-server-side-encryption-context ❌ x-amz-server-side-encryption-bucket-key-enabled❌ Request Payer: ❌ x-amz-request-payer❌ Tagging: ❌ x-amz-tagging❌ Object Locking: ❌ x-amz-object-lock-mode ❌ x-amz-object-lock-retain-until-date ❌ x-amz-object-lock-legal-hold❌ ACL: ❌ x-amz-acl ❌ x-amz-grant-full-control ❌ x-amz-grant-read ❌ x-amz-grant-read-acp ❌ x-amz-grant-write-acp❌ Storage class: ❌ x-amz-storage-class❌ Bucket Owner: ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ✅ [CompleteMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CompleteMultipartUpload.html) | ❌ Bucket Owner: ❌ x-amz-expected-bucket-owner❌ Request Payer: ❌ x-amz-request-payer                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ✅ [AbortMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/API_AbortMultipartUpload.html)       | ❌ Request Payer: ❌ x-amz-request-payer                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ✅ [CopyObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html)                           | ✅ Operation Metadata: ⚠️ x-amz-metadata-directive✅ System Metadata: ✅ Content-Type ✅ Cache-Control ✅ Content-Disposition ✅ Content-Encoding ✅ Content-Language ✅ Expires✅ Conditional Operations: ✅ x-amz-copy-source ✅ x-amz-copy-source-if-match ✅ x-amz-copy-source-if-modified-since ✅ x-amz-copy-source-if-none-match ✅ x-amz-copy-source-if-unmodified-since❌ ACL: ❌ x-amz-acl ❌ x-amz-grant-full-control ❌ x-amz-grant-read ❌ x-amz-grant-read-acp ❌ x-amz-grant-write-acp❌ Website: ❌ x-amz-website-redirect-location❌ SSE-C: ❌ x-amz-server-side-encryption ❌ x-amz-server-side-encryption-customer-algorithm ❌ x-amz-server-side-encryption-customer-key ❌ x-amz-server-side-encryption-customer-key-MD5 ❌ x-amz-server-side-encryption-aws-kms-key-id ❌ x-amz-server-side-encryption-context ❌ x-amz-server-side-encryption-bucket-key-enabled ❌ x-amz-copy-source-server-side-encryption-customer-algorithm ❌ x-amz-copy-source-server-side-encryption-customer-key ❌ x-amz-copy-source-server-side-encryption-customer-key-MD5❌ Request Payer: ❌ x-amz-request-payer❌ Tagging: ❌ x-amz-tagging ❌ x-amz-tagging-directive❌ Object Locking: ❌ x-amz-object-lock-mode ❌ x-amz-object-lock-retain-until-date ❌ x-amz-object-lock-legal-hold❌ Bucket Owner: ❌ x-amz-expected-bucket-owner ❌ x-amz-source-expected-bucket-owner❌ Checksums: ❌ x-amz-checksum-algorithm |
| ✅ [UploadPart](https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPart.html)                           | ✅ System Metadata:❌ Content-MD5❌ SSE-C: ❌ x-amz-server-side-encryption ❌ x-amz-server-side-encryption-customer-algorithm ❌ x-amz-server-side-encryption-customer-key ❌ x-amz-server-side-encryption-customer-key-MD5❌ Request Payer: ❌ x-amz-request-payer❌ Bucket Owner: ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ✅ [UploadPartCopy](https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPartCopy.html)                   | ❌ Conditional Operations: ❌ x-amz-copy-source ❌ x-amz-copy-source-if-match ❌ x-amz-copy-source-if-modified-since ❌ x-amz-copy-source-if-none-match ❌ x-amz-copy-source-if-unmodified-since✅ Range: ✅ x-amz-copy-source-range❌ SSE-C: ❌ x-amz-server-side-encryption-customer-algorithm ❌ x-amz-server-side-encryption-customer-key ❌ x-amz-server-side-encryption-customer-key-MD5 ❌ x-amz-copy-source-server-side-encryption-customer-algorithm ❌ x-amz-copy-source-server-side-encryption-customer-key ❌ x-amz-copy-source-server-side-encryption-customer-key-MD5❌ Request Payer: ❌ x-amz-request-payer❌ Bucket Owner: ❌ x-amz-expected-bucket-owner ❌ x-amz-source-expected-bucket-owner                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ✅ [ListParts](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListParts.html)                             | Query Parameters: ✅ max-parts ✅ part-number-marker❌ Request Payer: ❌ x-amz-request-payer❌ Bucket Owner: ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |


# Custom Roles

Learn about using custom roles with storage schema

In this guide, you will learn how to create and use custom roles with Storage to manage role-based access to objects and buckets. The same approach can be used to use custom roles with any other Supabase service.

Supabase Storage uses the same role-based access control system as any other Supabase service using RLS (Row Level Security).


## Create a custom role

Let's create a custom role `manager` to provide full read access to a specific bucket. For a more advanced setup, see the [RBAC Guide](/docs/guides/auth/custom-claims-and-role-based-access-control-rbac#create-auth-hook-to-apply-user-role).

```sql
create role 'manager';

-- Important to grant the role to the authenticator and anon role
grant manager to authenticator;
grant anon to manager;
```


## Create a policy

Let's create a policy that gives full read permissions to all objects in the bucket `teams` for the `manager` role.

```sql
create policy "Manager can view all files in the bucket 'teams'"
on storage.objects
for select
to manager
using (
 bucket_id = 'teams'
);
```


## Test the policy

To impersonate the `manager` role, you will need a valid JWT token with the `manager` role.
You can quickly create one using the `jsonwebtoken` library in Node.js.

```js
const jwt = require('jsonwebtoken')

const JWT_SECRET = 'your-jwt-secret' // You can find this in your Supabase project settings under API. Store this securely.
const USER_ID = '' // the user id that we want to give the manager role

const token = jwt.sign({ role: 'manager', sub: USER_ID }, JWT_SECRET, {
  expiresIn: '1h',
})
```

Now you can use this token to access the Storage API.

```js
const { StorageClient } = require('@supabase/storage-js')

const PROJECT_URL = 'https://your-project-id.supabase.co/storage/v1'

const storage = new StorageClient(PROJECT_URL, {
  authorization: `Bearer ${token}`,
})

await storage.from('teams').list()
```


# The Storage Schema

Learn about the storage schema

Storage uses Postgres to store metadata regarding your buckets and objects. Users can use RLS (Row-Level Security) policies for access control. This data is stored in a dedicated schema within your project called `storage`.

Here is the schema that represents the Storage service:

You have the option to query this table directly to retrieve information about your files in Storage without the need to go through our API.


## Modifying the schema

We strongly recommend refraining from making any alterations to the `storage` schema and treating it as read-only. This approach is important because any modifications to the schema on your end could potentially clash with our future updates, leading to downtime.

However, we encourage you to add custom indexes as they can significantly improve the performance of the RLS policies you create for enforcing access control.


# Storage Helper Functions

Learn the storage schema

Supabase Storage provides SQL helper functions which you can use to write RLS policies.


### `storage.filename()`

Returns the name of a file. For example, if your file is stored in `public/subfolder/avatar.png` it would return: `'avatar.png'`

**Usage**

This example demonstrates how you would allow any user to download a file called `favicon.ico`:

```sql
create policy "Allow public downloads"
on storage.objects
for select
to public
using (
  storage.filename(name) = 'favicon.ico'
);
```


### `storage.foldername()`

Returns an array path, with all of the subfolders that a file belongs to. For example, if your file is stored in `public/subfolder/avatar.png` it would return: `[ 'public', 'subfolder' ]`

**Usage**

This example demonstrates how you would allow authenticated users to upload files to a folder called `private`:

```sql
create policy "Allow authenticated uploads"
on storage.objects
for insert
to authenticated
with check (
  (storage.foldername(name))[1] = 'private'
);
```


### `storage.extension()`

Returns the extension of a file. For example, if your file is stored in `public/subfolder/avatar.png` it would return: `'png'`

**Usage**

This example demonstrates how you would allow restrict uploads to only PNG files inside a bucket called `cats`:

```sql
create policy "Only allow PNG uploads"
on storage.objects
for insert
to authenticated
with check (
  bucket_id = 'cats' and storage.extension(name) = 'png'
);
```


# Storage Access Control



Supabase Storage is designed to work perfectly with Postgres [Row Level Security](https://supabase.com/docs/guides/database/postgres/row-level-security) (RLS).

You can use RLS to create [Security Access Policies](https://www.postgresql.org/docs/current/sql-createpolicy.html) that are incredibly powerful and flexible, allowing you to restrict access based on your business needs.


## Access policies

By default Storage does not allow any uploads to buckets without RLS policies. You selectively allow certain operations by creating RLS policies on the `storage.objects` table.

You can find the documentation for the storage schema [here](/docs/guides/storage/schema/design) , and to simplify the process of crafting your policies, you can utilize these [helper functions](/docs/guides/storage/schema/helper-functions) .

For example, the only RLS policy required for [uploading](/docs/reference/javascript/storage-from-upload) objects is to grant the `INSERT` permission to the `storage.objects` table.

To allow overwriting files using the `upsert` functionality you will need to additionally grant `SELECT` and `UPDATE` permissions.


## Policy examples

An easy way to get started would be to create RLS policies for `SELECT`, `INSERT`, `UPDATE`, `DELETE` operations and restrict the policies to meet your security requirements. For example, one can start with the following `INSERT` policy:

```sql
create policy "policy_name"
ON storage.objects
for insert with check (
  true
);
```

and modify it to only allow authenticated users to upload assets to a specific bucket by changing it to:

```sql
create policy "policy_name"
on storage.objects for insert to authenticated with check (
    -- restrict bucket
    bucket_id = 'my_bucket_id'
);
```

This example demonstrates how you would allow authenticated users to upload files to a folder called `private` inside `my_bucket_id`:

```sql
create policy "Allow authenticated uploads"
on storage.objects
for insert
to authenticated
with check (
  bucket_id = 'my_bucket_id' and
  (storage.foldername(name))[1] = 'private'
);
```

This example demonstrates how you would allow authenticated users to upload files to a folder called with their `users.id` inside `my_bucket_id`:

```sql
create policy "Allow authenticated uploads"
on storage.objects
for insert
to authenticated
with check (
  bucket_id = 'my_bucket_id' and
  (storage.foldername(name))[1] = (select auth.uid()::text)
);
```

Allow a user to access a file that was previously uploaded by the same user:

```sql
create policy "Individual user Access"
on storage.objects for select
to authenticated
using ( (select auth.uid()) = owner_id::uuid );
```

***


## Bypassing access controls

If you exclusively use Storage from trusted clients, such as your own servers, and need to bypass the RLS policies, you can use the `service key` in the `Authorization` header. Service keys entirely bypass RLS policies, granting you unrestricted access to all Storage APIs.

Remember you should not share the service key publicly.


# Ownership



When creating new buckets or objects in Supabase Storage, an owner is automatically assigned to the bucket or object. The owner is the user who created the resource and the value is derived from the `sub` claim in the JWT.
We store the `owner` in the `owner_id` column.


## Access control

By itself, the ownership of a resource does not provide any access control. However, you can enforce the ownership by implementing access control against storage resources scoped to their owner.

For example, you can implement a policy where only the owner of an object can delete it. To do this, check the `owner_id` field of the object and compare it with the `sub` claim of the JWT:

```sql
create policy "User can delete their own objects"
on storage.objects
for delete
to authenticated
using (
    owner_id = (select auth.uid())
);
```

The use of RLS policies is just one way to enforce access control. You can also implement access control in your server code by following the same pattern.


# Bandwidth & Storage Egress

Bandwidth & Storage Egress

## Bandwidth & Storage egress

Free Plan Organizations in Supabase have a limit of 5 GB of bandwidth. This limit is calculated by the sum of all the data transferred from the Supabase servers to the client. This includes all the data transferred from the database, storage, and functions.


### Checking Storage egress requests in Logs Explorer:

We have a template query that you can use to get the number of requests for each object in [Logs Explorer](/dashboard/project/_/logs/explorer/templates).

```sql
select
  r.method as http_verb,
  r.path as filepath,
  count(*) as num_requests
from
  edge_logs
  cross join unnest(metadata) as m
  cross join unnest(m.request) as r
  cross join unnest(r.headers) as h
where (path like '%storage/v1/object/%' or path like '%storage/v1/render/%') and r.method = 'GET'
group by r.path, r.method
order by num_requests desc
limit 100;
```

Example of the output:

    [
        {"filepath":"/storage/v1/object/sign/large%20bucket/20230902_200037.gif",
        "http_verb":"GET",
        "num_requests":100
        },
        {"filepath":"/storage/v1/object/public/demob/Sports/volleyball.png",
        "http_verb":"GET",
        "num_requests":168
        }
    ]


### Calculating egress:

If you already know the size of those files, you can calculate the egress by multiplying the number of requests by the size of the file.
You can also get the size of the file with the following cURL:

```bash
curl -s -w "%{size_download}\n" -o /dev/null "https://my_project.supabase.co/storage/v1/object/large%20bucket/20230902_200037.gif"
```

This will return the size of the file in bytes.
For this example, let's say that `20230902_200037.gif` has a file size of 3 megabytes and `volleyball.png` has a file size of 570 kilobytes.

Now, we have to sum all the egress for all the files to get the total egress:

    100 * 3MB = 300MB
    168 * 570KB = 95.76MB
    Total Egress = 395.76MB

You can see that these values can get quite large, so it's important to keep track of the egress and optimize the files.


### Optimizing egress:

If you are on the Pro Plan, you can use the [Supabase Image Transformations](/docs/guides/storage/image-transformations) to optimize the images and reduce the egress.


# Serving assets from Storage

Serving assets from Storage

## Public buckets

As mentioned in the [Buckets Fundamentals](/docs/guides/storage/buckets/fundamentals) all files uploaded in a public bucket are publicly accessible and benefit a high CDN cache HIT ratio.

You can access them by using this conventional URL:

    https://[project_id].supabase.co/storage/v1/object/public/[bucket]/[asset-name]

You can also use the Supabase SDK `getPublicUrl` to generate this URL for you

```js
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('your_project_url', 'your_supabase_api_key')

// ---cut---
const { data } = supabase.storage.from('bucket').getPublicUrl('filePath.jpg')

console.log(data.publicUrl)
```


### Downloading

If you want the browser to start an automatic download of the asset instead of trying serving it, you can add the `?download` query string parameter.

By default it will use the asset name to save the file on disk. You can optionally pass a custom name to the `download` parameter as following: `?download=customname.jpg`


## Private buckets

Assets stored in a non-public bucket are considered private and are not accessible via a public URL like the public buckets.

You can access them only by:

*   Signing a time limited URL on the Server, for example with Edge Functions.
*   with a GET request the URL `https://[project_id].supabase.co/storage/v1/object/authenticated/[bucket]/[asset-name]` and the user Authorization header


### Signing URLs

You can sign a time-limited URL that you can share to your users by invoking the `createSignedUrl` method on the SDK.

```js
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('your_project_url', 'your_supabase_api_key')

// ---cut---
const { data, error } = await supabase.storage
  .from('bucket')
  .createSignedUrl('private-document.pdf', 3600)

if (data) {
  console.log(data.signedUrl)
}
```


# Storage Image Transformations

Transform images with Storage

Supabase Storage offers the functionality to optimize and resize images on the fly. Any image stored in your buckets can be transformed and optimized for fast delivery.


## Get a public URL for a transformed image

Our client libraries methods like `getPublicUrl` and `createSignedUrl` support the `transform` option. This returns the URL that serves the transformed image.

An example URL could look like this:

    https://project_id.supabase.co/storage/v1/render/image/public/bucket/image.jpg?width=500&height=600`


## Signing URLs with transformation options

To share a transformed image in a private bucket for a fixed amount of time, provide the transform option when you create the signed URL:

The transformation options are embedded into the token attached to the URL — they cannot be changed once signed.


## Downloading images

To download a transformed image, pass the `transform` option to the `download` function.


## Automatic image optimization (WebP)

When using the image transformation API, Storage will automatically find the best format supported by the client and return that to the client, without any code change. For instance, if you use Chrome when viewing a JPEG image and using transformation options, you'll see that images are automatically optimized as `webp` images.

As a result, this will lower the bandwidth that you send to your users and your application will load much faster.

**Disabling automatic optimization:**

In case you'd like to return the original format of the image and **opt-out** from the automatic image optimization detection, you can pass the `format=origin` parameter when requesting a transformed image, this is also supported in the JavaScript SDK starting from v2.2.0


## Next.js loader

You can use Supabase Image Transformation to optimize your Next.js images using a custom [Loader](https://nextjs.org/docs/api-reference/next/image#loader-configuration).

To get started, create a `supabase-image-loader.js` file in your Next.js project which exports a default function:

```ts
const projectId = '' // your supabase project id

export default function supabaseLoader({ src, width, quality }) {
  return `https://${projectId}.supabase.co/storage/v1/render/image/public/${src}?width=${width}&quality=${quality || 75}`
}
```

In your `nextjs.config.js` file add the following configuration to instruct Next.js to use our custom loader

```js
module.exports = {
  images: {
    loader: 'custom',
    loaderFile: './supabase-image-loader.js',
  },
}
```

At this point you are ready to use the `Image` component provided by Next.js

```tsx
import Image from 'next/image'

const MyImage = (props) => {
  return <Image src="bucket/image.png" alt="Picture of the author" width={500} height={500} />
}
```


## Transformation options

We currently support a few transformation options focusing on optimizing, resizing, and cropping images.


### Optimizing

You can set the quality of the returned image by passing a value from 20 to 100 (with 100 being the highest quality) to the `quality` parameter. This parameter defaults to 80.

Example:


### Resizing

You can use `width` and `height` parameters to resize an image to a specific dimension. If only one parameter is specified, the image will be resized and cropped, maintaining the aspect ratio.


### Modes

You can use different resizing modes to fit your needs, each of them uses a different approach to resize the image:

Use the `resize` parameter with one of the following values:

*   `cover` : resizes the image while keeping the aspect ratio to fill a given size and crops projecting parts. (default)

*   `contain` : resizes the image while keeping the aspect ratio to fit a given size.

*   `fill` : resizes the image without keeping the aspect ratio.

Example:


### Limits

*   Width and height must be an integer value between 1-2500.
*   The image size cannot exceed 25MB.
*   The image resolution cannot exceed 50MP.


### Supported image formats

| Format | Extension | Source | Result |
| ------ | --------- | ------ | ------ |
| PNG    | `png`     | ☑️     | ☑️     |
| JPEG   | `jpg`     | ☑️     | ☑️     |
| WebP   | `webp`    | ☑️     | ☑️     |
| AVIF   | `avif`    | ☑️     | ☑️     |
| GIF    | `gif`     | ☑️     | ☑️     |
| ICO    | `ico`     | ☑️     | ☑️     |
| SVG    | `svg`     | ☑️     | ☑️     |
| HEIC   | `heic`    | ☑️     | ❌     |
| BMP    | `bmp`     | ☑️     | ☑️     |
| TIFF   | `tiff`    | ☑️     | ☑️     |


## Pricing

For a detailed breakdown of how charges are calculated, refer to [Manage Storage Image Transformations usage](/docs/guides/platform/manage-your-usage/storage-image-transformations).


## Self hosting

Our solution to image resizing and optimization can be self-hosted as with any other Supabase product. Under the hood we use [imgproxy](https://imgproxy.net/)


#### imgproxy configuration:

Deploy an imgproxy container with the following configuration:

```yaml
imgproxy:
  image: darthsim/imgproxy
  environment:
    - IMGPROXY_ENABLE_WEBP_DETECTION=true
    - IMGPROXY_JPEG_PROGRESSIVE=true
```

Note: make sure that this service can only be reachable within an internal network and not exposed to the public internet


#### Storage API configuration:

Once [imgproxy](https://imgproxy.net/) is deployed we need to configure a couple of environment variables in your self-hosted [`storage-api`](https://github.com/supabase/storage-api) service as follows:

```shell
ENABLE_IMAGE_TRANSFORMATION=true
IMGPROXY_URL=yourinternalimgproxyurl.internal.com
```


# Limits

Learn how to increase Supabase file limits.

## Global file size

You can set the max file size across all your buckets by setting this global value in the dashboard [here](https://supabase.com/dashboard/project/_/settings/storage). For Free projects, the limit can't exceed 50 MB. On the Pro Plan and up, you can set this value to up to 50 GB. If you need more than 50 GB, [contact us](https://supabase.com/dashboard/support/new).

| Plan       | Max File Size Limit |
| ---------- | ------------------- |
| Free       | 50 MB               |
| Pro        | 50 GB               |
| Team       | 50 GB               |
| Enterprise | Custom              |

Additionally, you can specify the max file size on a per [bucket level](/docs/guides/storage/buckets/creating-buckets#restricting-uploads) but it can't be higher than this global limit. As a good practice, the global limit should be set to the highest possible file size that your application accepts, and apply per bucket limits.


## Per bucket restrictions

You can have different restrictions on a per bucket level such as restricting the file types (e.g. `pdf`, `images`, `videos`) or the max file size, which should be lower than the global limit. To apply these limit on a bucket level see [Creating Buckets](/docs/guides/storage/buckets/creating-buckets#restricting-uploads).


# Resumable Uploads

Learn how to upload files to Supabase Storage.

The resumable upload method is recommended when:

*   Uploading large files that may exceed 6MB in size
*   Network stability is a concern
*   You want to have progress events for your uploads

Supabase Storage implements the [TUS protocol](https://tus.io/) to enable resumable uploads. TUS stands for The Upload Server and is an open protocol for supporting resumable uploads. The protocol allows the upload process to be resumed from where it left off in case of interruptions. This method can be implemented using the [`tus-js-client`](https://github.com/tus/tus-js-client) library, or other client-side libraries like [Uppy](https://uppy.io/docs/tus/) that support the TUS protocol.


### Upload URL

When uploading using the resumable upload endpoint, the storage server creates a unique URL for each upload, even for multiple uploads to the same path. All chunks will be uploaded to this URL using the `PATCH` method.

This unique upload URL will be valid for **up to 24 hours**. If the upload is not completed within 24 hours, the URL will expire and you'll need to start the upload again. TUS client libraries typically create a new URL if the previous one expires.


### Concurrency

When two or more clients upload to the same upload URL only one of them will succeed. The other clients will receive a `409 Conflict` error. Only 1 client can upload to the same upload URL at a time which prevents data corruption.

When two or more clients upload a file to the same path using different upload URLs, the first client to complete the upload will succeed and the other clients will receive a `409 Conflict` error.

If you provide the `x-upsert` header the last client to complete the upload will succeed instead.


### Uppy example

You can check a [full example using Uppy](https://github.com/supabase/supabase/tree/master/examples/storage/resumable-upload-uppy).

Uppy has integrations with different frameworks:

*   [React](https://uppy.io/docs/react/)
*   [Svelte](https://uppy.io/docs/svelte/)
*   [Vue](https://uppy.io/docs/vue/)
*   [Angular](https://uppy.io/docs/angular/)


## Overwriting files

When uploading a file to a path that already exists, the default behavior is to return a `400 Asset Already Exists` error.
If you want to overwrite a file on a specific path you can set the `x-upsert` header to `true`.

We do advise against overwriting files when possible, as the CDN will take some time to propagate the changes to all the edge nodes leading to stale content.
Uploading a file to a new path is the recommended way to avoid propagation delays and stale content.

To learn more, see the [CDN](/docs/guides/storage/cdn/fundamentals) guide.


# S3 Uploads

Learn how to upload files to Supabase Storage using S3.

You can use the S3 protocol to upload files to Supabase Storage. To get started with S3, see the [S3 setup guide](/docs/guides/storage/s3/authentication).

The S3 protocol supports file upload using:

*   A single request
*   Multiple requests via Multipart Upload


## Single request uploads

The `PutObject` action uploads the file in a single request. This matches the behavior of the Supabase SDK [Standard Upload](/docs/guides/storage/uploads/standard-uploads).

Use `PutObject` to upload smaller files, where retrying the entire upload won't be an issue. The maximum file size on paid plans is 50 GB.

For example, using JavaScript and the `aws-sdk` client:

```javascript
import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3'

const s3Client = new S3Client({...})

const file = fs.createReadStream('path/to/file')

const uploadCommand = new PutObjectCommand({
  Bucket: 'bucket-name',
  Key: 'path/to/file',
  Body: file,
  ContentType: 'image/jpeg',
})

await s3Client.send(uploadCommand)
```


## Multipart uploads

Multipart Uploads split the file into smaller parts and upload them in parallel, maximizing the upload speed on a fast network. When uploading large files, this allows you to retry the upload of individual parts in case of network issues.

This method is preferable over [Resumable Upload](/docs/guides/storage/uploads/resumable-uploads) for server-side uploads, when you want to maximize upload speed at the cost of resumability. The maximum file size on paid plans is 50 GB.


### Upload a file in parts

Use the `Upload` class from an S3 client to upload a file in parts. For example, using JavaScript:

```javascript
import { S3Client } from '@aws-sdk/client-s3'
import { Upload } from '@aws-sdk/lib-storage'

const s3Client = new S3Client({...})

const file = fs.createReadStream('path/to/very-large-file')

const upload = new Upload(s3Client, {
  Bucket: 'bucket-name',
  Key: 'path/to/file',
  ContentType: 'image/jpeg',
  Body: file,
})

await uploader.done()
```


### Aborting multipart uploads

All multipart uploads are automatically aborted after 24 hours. To abort a multipart upload before that, you can use the [`AbortMultipartUpload`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_AbortMultipartUpload.html) action.


# Standard Uploads

Learn how to upload files to Supabase Storage.

## Uploading

The standard file upload method is ideal for small files that are not larger than 6MB.

It uses the traditional `multipart/form-data` format and is simple to implement using the supabase-js SDK. Here's an example of how to upload a file using the standard upload method:


## Overwriting files

When uploading a file to a path that already exists, the default behavior is to return a `400 Asset Already Exists` error.
If you want to overwrite a file on a specific path you can set the `upsert` options to `true` or using the `x-upsert` header.

We do advise against overwriting files when possible, as our Content Delivery Network will take sometime to propagate the changes to all the edge nodes leading to stale content.
Uploading a file to a new path is the recommended way to avoid propagation delays and stale content.


## Content type

By default, Storage will assume the content type of an asset from the file extension. If you want to specify the content type for your asset, pass the `contentType` option during upload.


## Concurrency

When two or more clients upload a file to the same path, the first client to complete the upload will succeed and the other clients will receive a `400 Asset Already Exists` error.
If you provide the `x-upsert` header the last client to complete the upload will succeed instead.


# Telemetry



Telemetry helps you understand what’s happening inside your app by collecting logs, metrics, and traces.

*   **Logs** capture individual events, such as errors or warnings, providing details about what happened at a specific moment.
*   **Metrics** track numerical data over time, like request latency or database query performance, helping you spot trends.
*   **Traces** show the flow of a request through different services, helping you debug slow or failing operations.

Supabase is working towards full support for the [OpenTelemetry](https://opentelemetry.io/) standard, making it easier to integrate with observability tools.

This section provides guidance on telemetry in Supabase, including how to work with Supabase Logs.


# Advanced Log Filtering



# Querying the logs


## Understanding field references

The log tables are queried with a subset of BigQuery SQL syntax. They all have three columns: `event_message`, `timestamp`, and `metadata`.

| column        | description                 |
| ------------- | --------------------------- |
| timestamp     | time event was recorded     |
| event\_message | the log's message           |
| metadata      | information about the event |

The `metadata` column is an array of JSON objects that stores important details about each recorded event. For example, in the Postgres table, the `metadata.parsed.error_severity` field indicates the error level of an event. To work with its values, you need to `unnest` them using a `cross join`.

This approach is commonly used with JSON and array columns, so it might look a bit unfamiliar if you're not used to working with these data types.

```sql
select
  event_message,
  parsed.error_severity,
  parsed.user_name
from
  postgres_logs
  -- extract first layer
  cross join unnest(postgres_logs.metadata) as metadata
  -- extract second layer
  cross join unnest(metadata.parsed) as parsed;
```


## Expanding results

Logs returned by queries may be difficult to read in table format. A row can be double-clicked to expand the results into more readable JSON:

![Expanding log results](/docs/img/guides/platform/expanded-log-results.png)


## Filtering with [regular expressions](https://en.wikipedia.org/wiki/Regular_expression)

The Logs use BigQuery Style regular expressions with the [regexp\_contains function](https://cloud.google.com/bigquery/docs/reference/standard-sql/string_functions#regexp_contains). In its most basic form, it will check if a string is present in a specified column.

```sql
select
  cast(timestamp as datetime) as timestamp,
  event_message,
  metadata
from postgres_logs
where regexp_contains(event_message, 'is present');
```

There are multiple operators that you should consider using:


### Find messages that start with a phrase

`^` only looks for values at the start of a string

```sql
-- find only messages that start with connection
regexp_contains(event_message, '^connection')
```


### Find messages that end with a phrase:

`$` only looks for values at the end of the string

```sql
-- find only messages that ends with port=12345
regexp_contains(event_message, '$port=12345')
```


### Ignore case sensitivity:

`(?i)` ignores capitalization for all proceeding characters

```sql
-- find all event_messages with the word "connection"
regexp_contains(event_message, '(?i)COnnecTion')
```


### Wildcards:

`.` can represent any string of characters

```sql
-- find event_messages like "hello<anything>world"
regexp_contains(event_message, 'hello.world')
```


### Alphanumeric ranges:

`[1-9a-zA-Z]` finds any strings with only numbers and letters

```sql
-- find event_messages that contain a number between 1 and 5 (inclusive)
regexp_contains(event_message, '[1-5]')
```


### Repeated values:

`x*` zero or more x
`x+` one or more x
`x?` zero or one x
`x{4,}` four or more x
`x{3}` exactly 3 x

```sql
-- find event_messages that contains any sequence of 3 digits
regexp_contains(event_message, '[0-9]{3}')
```


### Escaping reserved characters:

`\.` interpreted as period `.` instead of as a wildcard

```sql
-- escapes .
regexp_contains(event_message, 'hello world\.')
```


### `or` statements:

`x|y` any string with `x` or `y` present

```sql
-- find event_messages that have the word 'started' followed by either the word "host" or "authenticated"
regexp_contains(event_message, 'started host|authenticated')
```


### `and`/`or`/`not` statements in SQL:

`and`, `or`, and `not` are all native terms in SQL and can be used in conjunction with regular expressions to filter results

```sql
select
  cast(timestamp as datetime) as timestamp,
  event_message,
  metadata
from postgres_logs
where
  (regexp_contains(event_message, 'connection') and regexp_contains(event_message, 'host'))
  or not regexp_contains(event_message, 'received');
```


### Filtering and unnesting example

**Filter for Postgres**

```sql
select
  cast(postgres_logs.timestamp as datetime) as timestamp,
  parsed.error_severity,
  parsed.user_name,
  event_message
from
  postgres_logs
  cross join unnest(metadata) as metadata
  cross join unnest(metadata.parsed) as parsed
where regexp_contains(parsed.error_severity, 'ERROR|FATAL|PANIC')
order by timestamp desc
limit 100;
```


## Limitations


### Log tables cannot be joined together

Each product table operates independently without the ability to join with other log tables. This may change in the future.


### The `with` keyword and subqueries are not supported

The parser does not yet support `with` and subquery statements.


### The `ilike` and `similar to` keywords are not supported

Although `like` and other comparison operators can be used, `ilike` and `similar to` are incompatible with BigQuery's variant of SQL. `regexp_contains` can be used as an alternative.


### The wildcard operator `*` to select columns is not supported

The log parser is not able to parse the `*` operator for column selection. Instead, you can access all fields from the `metadata` column:

```sql
select
  cast(postgres_logs.timestamp as datetime) as timestamp,
  event_message,
  metadata
from
  <log_table_name>
order by timestamp desc
limit 100;
```


# Log Drains



Log drains will send all logs of the Supabase stack to one or more desired destinations. It is only available for customers on Team and Enterprise Plans. Log drains is available in the dashboard under [Project Settings > Log Drains](https://supabase.com/dashboard/project/_/settings/log-drains).

You can read about the initial announcement [here](https://supabase.com/blog/log-drains) and vote for your preferred drains in [this discussion](https://github.com/orgs/supabase/discussions/28324?sort=top).


# Supported destinations

The following table lists the supported destinations and the required setup configuration:

| Destination           | Transport Method | Configuration                                     |
| --------------------- | ---------------- | ------------------------------------------------- |
| Generic HTTP endpoint | HTTP             | URL  HTTP Version  Gzip  Headers |
| DataDog               | HTTP             | API Key  Region                             |
| Loki                  | HTTP             | URL  Headers                                |

HTTP requests are batched with a max of 250 logs or 1 second intervals, whichever happens first. Logs are compressed via Gzip if the destination supports it.


## Generic HTTP endpoint

Logs are sent as a POST request with a JSON body. Both HTTP/1 and HTTP/2 protocols are supported.
Custom headers can optionally be configured for all requests.

Note that requests are **unsigned**.


## DataDog logs

Logs sent to DataDog have the name of the log source set on the `service` field of the event and the source set to `Supabase`. Logs are gzipped before they are sent to DataDog.

The payload message is a JSON string of the raw log event, prefixed with the event timestamp.

To setup DataDog log drain, generate a DataDog API key [here](https://app.datadoghq.com/organization-settings/api-keys) and the location of your DataDog site.

If you are interested in other log drains, upvote them [here](https://github.com/orgs/supabase/discussions/28324)


## Loki

Logs sent to the Loki HTTP API are specifically formatted according to the HTTP API requirements. See the official Loki HTTP API documentation for [more details](https://grafana.com/docs/loki/latest/reference/loki-http-api/#ingest-logs).

Events are batched with a maximum of 250 events per request.

The log source and product name will be used as stream labels.

The `event_message` and `timestamp` fields will be dropped from the events to avoid duplicate data.

Loki must be configured to accept **structured metadata**, and it is advised to increase the default maximum number of structured metadata fields to at least 500 to accommodate large log event payloads of different products.


## Pricing

For a detailed breakdown of how charges are calculated, refer to [Manage Log Drain usage](/docs/guides/platform/manage-your-usage/log-drains).


# Logging



The Supabase Platform includes a Logs Explorer that allows log tracing and debugging. Log retention is based on your [project's pricing plan](https://supabase.com/pricing).


## Product logs

Supabase provides a logging interface specific to each product. You can use simple regular expressions for keywords and patterns to search log event messages. You can also export and download the log events matching your query as a spreadsheet.

***


## Working with API logs

[API logs](https://supabase.com/dashboard/project/_/logs/edge-logs) run through the Cloudflare edge servers and will have attached Cloudflare metadata under the `metadata.request.cf.*` fields.


### Allowed headers

A strict list of request and response headers are permitted in the API logs. Request and response headers will still be received by the server(s) and client(s), but will not be attached to the API logs generated.

Request headers:

*   `accept`
*   `cf-connecting-ip`
*   `cf-ipcountry`
*   `host`
*   `user-agent`
*   `x-forwarded-proto`
*   `referer`
*   `content-length`
*   `x-real-ip`
*   `x-client-info`
*   `x-forwarded-user-agent`
*   `range`
*   `prefer`

Response headers:

*   `cf-cache-status`
*   `cf-ray`
*   `content-location`
*   `content-range`
*   `content-type`
*   `content-length`
*   `date`
*   `transfer-encoding`
*   `x-kong-proxy-latency`
*   `x-kong-upstream-latency`
*   `sb-gateway-mode`
*   `sb-gateway-version`


### Additional request metadata

To attach additional metadata to a request, it is recommended to use the `User-Agent` header for purposes such as device or version identification.

For example:

    node MyApp/1.2.3 (device-id:abc123)
    Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0 MyApp/1.2.3 (Foo v1.3.2; Bar v2.2.2)


## Logging Postgres queries

To enable query logs for other categories of statements:

1.  [Enable the pgAudit extension](https://supabase.com/dashboard/project/_/database/extensions).
2.  Configure `pgaudit.log` (see below). Perform a fast reboot if needed.
3.  View your query logs under [Logs > Postgres Logs](https://supabase.com/dashboard/project/_/logs/postgres-logs).


### Configuring `pgaudit.log`

The stored value under `pgaudit.log` determines the classes of statements that are logged by [pgAudit extension](https://www.pgaudit.org/). Refer to the pgAudit documentation for the [full list of values](https://github.com/pgaudit/pgaudit/blob/master/README.md#pgauditlog).

To enable logging for function calls/do blocks, writes, and DDL statements for a single session, execute the following within the session:

```sql
-- temporary single-session config update
set pgaudit.log = 'function, write, ddl';
```

To *permanently* set a logging configuration (beyond a single session), execute the following, then perform a fast reboot:

```sql
-- equivalent permanent config update.
alter role postgres set pgaudit.log to 'function, write, ddl';
```

To help with debugging, we recommend adjusting the log scope to only relevant statements as having too wide of a scope would result in a lot of noise in your Postgres logs.

Note that in the above example, the role is set to `postgres`. To log user-traffic flowing through the [HTTP APIs](../../guides/database/api#rest-api-overview) powered by PostgREST, set your configuration values for the `authenticator`.

```sql
-- for API-related logs
alter role authenticator set pgaudit.log to 'write';
```

By default, the log level will be set to `log`. To view other levels, run the following:

```sql
-- adjust log level
alter role postgres set pgaudit.log_level to 'info';
alter role postgres set pgaudit.log_level to 'debug5';
```

Note that as per the pgAudit [log\_level documentation](https://github.com/pgaudit/pgaudit/blob/master/README.md#pgauditlog_level), `error`, `fatal`, and `panic` are not allowed.

To reset system-wide settings, execute the following, then perform a fast reboot:

```sql
-- resets stored config.
alter role postgres reset pgaudit.log
```


### `RAISE`d log messages in Postgres

Messages that are manually logged via `RAISE INFO`, `RAISE NOTICE`, `RAISE WARNING`, and `RAISE LOG` are shown in Postgres Logs. Note that only messages at or above your logging level are shown. Syncing of messages to Postgres Logs may take a few minutes.

If your logs aren't showing, check your logging level by running:

```sql
show log_min_messages;
```

Note that `LOG` is a higher level than `WARNING` and `ERROR`, so if your level is set to `LOG`, you will not see `WARNING` and `ERROR` messages.


## Logging realtime connections

Realtime doesn't log new WebSocket connections or Channel joins by default. Enable connection logging per client by including an `info` `log_level` parameter when instantiating the Supabase client.

```javascript
import { createClient } from '@supabase/supabase-js'

const options = {
  realtime: {
    params: {
      log_level: 'info',
    },
  },
}
const supabase = createClient('https://xyzcompany.supabase.co', 'public-anon-key', options)
```


## Logs Explorer

The [Logs Explorer](https://supabase.com/dashboard/project/_/logs-explorer) exposes logs from each part of the Supabase stack as a separate table that can be queried and joined using SQL.

![Logs Explorer](/docs/img/guides/platform/logs/logs-explorer.png)

You can access the following logs from the **Sources** drop-down:

*   `auth_logs`: GoTrue server logs, containing authentication/authorization activity.
*   `edge_logs`: Edge network logs, containing request and response metadata retrieved from Cloudflare.
*   `function_edge_logs`: Edge network logs for only edge functions, containing network requests and response metadata for each execution.
*   `function_logs`: Function internal logs, containing any `console` logging from within the edge function.
*   `postgres_logs`: Postgres database logs, containing statements executed by connected applications.
*   `realtime_logs`: Realtime server logs, containing client connection information.
*   `storage_logs`: Storage server logs, containing object upload and retrieval information.


## Querying with the Logs Explorer

The Logs Explorer uses BigQuery and supports all [available SQL functions and operators](https://cloud.google.com/bigquery/docs/reference/standard-sql/functions-and-operators).


### Timestamp display and behavior

Each log entry is stored with a `timestamp` as a `TIMESTAMP` data type. Use the appropriate [timestamp function](https://cloud.google.com/bigquery/docs/reference/standard-sql/timestamp_functions#timestamp) to utilize the `timestamp` field in a query.

Raw top-level timestamp values are rendered as unix microsecond. To render the timestamps in a human-readable format, use the `DATETIME()` function to convert the unix timestamp display into an ISO-8601 timestamp.

```sql
-- timestamp column without datetime()
select timestamp from ....
--  1664270180000

-- timestamp column with datetime()
select datetime(timestamp) from ....
-- 2022-09-27T09:17:10.439Z
```


### Unnesting arrays

Each log event stores metadata an array of objects with multiple levels, and can be seen by selecting single log events in the Logs Explorer. To query arrays, use `unnest()` on each array field and add it to the query as a join. This allows you to reference the nested objects with an alias and select their individual fields.

For example, to query the edge logs without any joins:

```sql
select timestamp, metadata from edge_logs as t;
```

The resulting `metadata` key is rendered as an array of objects in the Logs Explorer. In the following diagram, each box represents a nested array of objects:

![Without Unnesting](/docs/img/unnesting-none.png)

Perform a `cross join unnest()` to work with the keys nested in the `metadata` key.

To query for a nested value, add a join for each array level:

```sql
select timestamp, request.method, header.cf_ipcountry
from
  edge_logs as t
  cross join unnest(t.metadata) as metadata
  cross join unnest(metadata.request) as request
  cross join unnest(request.headers) as header;
```

This surfaces the following columns available for selection:
![With Two Level Unnesting](/docs/img/unnesting-2.png)

This allows you to select the `method` and `cf_ipcountry` columns. In JS dot notation, the full paths for each selected column are:

*   `metadata[].request[].method`
*   `metadata[].request[].headers[].cf_ipcountry`


### LIMIT and result row limitations

The Logs Explorer has a maximum of 1000 rows per run. Use `LIMIT` to optimize your queries by reducing the number of rows returned further.


### Best practices

1.  Include a filter over **timestamp**

Querying your entire log history might seem appealing. For **Enterprise** customers that have a large retention range, you run the risk of timeouts due additional time required to scan the larger dataset.

2.  Avoid selecting large nested objects. Select individual values instead.

When querying large objects, the columnar storage engine selects each column associated with each nested key, resulting in a large number of columns being selected. This inadvertently impacts the query speed and may result in timeouts or memory errors, especially for projects with a lot of logs.

Instead, select only the values required.

```sql
-- ❌ Avoid doing this
select
  datetime(timestamp),
  m as metadata -- <- metadata contains many nested keys
from
  edge_logs as t
  cross join unnest(t.metadata) as m;

-- ✅ Do this
select
  datetime(timestamp),
  r.method -- <- select only the required values
from
  edge_logs as t
  cross join unnest(t.metadata) as m
  cross join unnest(m.request) as r;
```


### Examples and templates

The Logs Explorer includes **Templates** (available in the Templates tab or the dropdown in the Query tab) to help you get started.

For example, you can enter the following query in the SQL Editor to retrieve each user's IP address:

```sql
select datetime(timestamp), h.x_real_ip
from
  edge_logs
  cross join unnest(metadata) as m
  cross join unnest(m.request) as r
  cross join unnest(r.headers) as h
where h.x_real_ip is not null and r.method = "GET";
```


### Logs field reference

Refer to the full field reference for each available source below. Do note that in order to access each nested key, you would need to perform the [necessary unnesting joins](#unnesting-arrays)


# Metrics



In addition to the reports and charts built in to the Supabase dashboard, each project hosted on the Supabase platform comes with a [Prometheus](https://prometheus.io/)-compatible metrics endpoint, updated every minute, which can be used to gather insight into the health and status of your project.

You can use this endpoint to ingest data into your own monitoring and alerting infrastructure, as long as it is capable of scraping Prometheus-compatible endpoints, in order to set up custom rules beyond those supported by the Supabase dashboard.


## Accessing the metrics endpoint

Your project's metrics endpoint is accessible at `https://<project-ref>.supabase.co/customer/v1/privileged/metrics`. Access to the endpoint is secured via HTTP Basic Auth; the username is `service_role`, while the password is the service role JWT available through the Supabase dashboard.

```shell
> curl https://<project-ref>.supabase.co/customer/v1/privileged/metrics --user 'service_role:<service-role-jwt>'
```


## Supabase Grafana

The pre-configured Supabase Grafana Dashboard is an advanced version of the [Dashboard's Database Reports](https://supabase.com/dashboard/project/_/reports/database). It visualizes over 200 database performance and health metrics.

![Supabase Grafana](/docs/img/guides/platform/supabase-grafana-prometheus.png)

Instructions are included in the README for deploying the repository using docker.


## Using the metrics endpoint in production

To set up monitoring for your project, you will need two things:

1.  A datastore - a place to store the metrics coming from your Supabase project over time
2.  A dashboard - a place to visualize the state of your Supabase project for a defined period


### Setting up a metrics datastore

One of the more well-known options is [Prometheus](https://prometheus.io/docs/introduction/overview/) and it is the tool used in this guide.

You can [self-host](https://prometheus.io/docs/prometheus/latest/installation/) Prometheus or choose a managed service to store your metrics. Some of the providers offering managed Prometheus are:

*   [Digital Ocean](https://marketplace.digitalocean.com/apps/prometheus)
*   [AWS](https://aws.amazon.com/prometheus/)
*   [Grafana Cloud](https://grafana.com/products/cloud/metrics/)

Follow the guides for the deployment option you choose


#### Adding a scrape job to Prometheus

For Prometheus, modify your `prometheus.yaml` file to add a Supabase job, and set the `metrics_path`, `scheme`, `basic_auth` and `targets` parameters. For example:

```yaml
scrape_configs:
  - job_name: "MySupabaseJob"
    metrics_path: "/customer/v1/privileged/metrics"
    scheme: https
    basic_auth:
      username: "service_role"
      password: "<your service_role JWT>"
    static_configs:
      - targets: [
        "<your Supabase Project ID>.supabase.co:443"
          ]
        labels:
          group: "MyGroupLabel"
```


### Setting up a dashboard

For this guide, we will be using [Grafana](https://grafana.com/docs/grafana/latest/introduction/).

You can [self-host](https://grafana.com/docs/grafana/latest/setup-grafana/installation/) Grafana or many providers offer managed Grafana, some of which are listed below:

*   [DigitalOcean](https://marketplace.digitalocean.com/apps/grafana)
*   [AWS](https://aws.amazon.com/grafana/)
*   [Grafana Cloud](https://grafana.com/grafana/)

Follow the guides of the provider you choose to get Grafana up and running.


### Adding a data source to Grafana

In the left-hand menu, select `Data sources` and click `Add new data source`.

Select `Prometheus` and enter the connection details for the Prometheus instance you have set up.

Under **Interval behavior**, set the **scraping interval** to 60s and test the data source. Once it has passed, save it.


### Adding the Supabase dashboard

In the left-hand menu, select `Dashboards` and click `New`. From the drop-down, select `Import`.

Copy the raw file from our [supabase-grafana](https://raw.githubusercontent.com/supabase/supabase-grafana/refs/heads/main/grafana/dashboard.json) repository and paste it (or upload the file).

Click `Load` and the dashboard will load from the project specified in your Prometheus job.


### Monitoring your project

You can configure alerts from Prometheus or Grafana. The `supabase-grafana` repository has a selection of [example alerts](https://github.com/supabase/supabase-grafana/blob/main/docs/example-alerts.md) that can be configured.


# Sentry integration

Integrate Sentry to monitor errors from a Supabase client

You can use [Sentry](https://sentry.io/welcome/) to monitor errors thrown from a Supabase JavaScript client. Install the [Supabase Sentry integration](https://github.com/supabase-community/sentry-integration-js) to get started.

The Sentry integration supports browser, Node, and edge environments.


## Installation

Install the Sentry integration using your package manager:


## Use

To use the Supabase Sentry integration, add it to your `integrations` list when initializing your Sentry client.

You can supply either the Supabase Client constructor or an already-initiated instance of a Supabase Client.

All available configuration options are available in our [`supabase-community/sentry-integration-js` repository](https://github.com/supabase-community/sentry-integration-js/blob/master/README.md#options).


## Deduplicating spans

If you're already monitoring HTTP errors in Sentry, for example with the HTTP, Fetch, or Undici integrations, you will get duplicate spans for Supabase calls. You can deduplicate the spans by skipping them in your other integration:

```ts
import * as Sentry from '@sentry/browser'
import { SupabaseClient } from '@supabase/supabase-js'
import { supabaseIntegration } from '@supabase/sentry-js-integration'

Sentry.init({
  dsn: SENTRY_DSN,
  integrations: [
    supabaseIntegration(SupabaseClient, Sentry, {
      tracing: true,
      breadcrumbs: true,
      errors: true,
    }),

    // @sentry/browser
    Sentry.browserTracingIntegration({
      shouldCreateSpanForRequest: (url) => {
        return !url.startsWith(`${SUPABASE_URL}/rest`)
      },
    }),

    // or @sentry/node
    Sentry.httpIntegration({
      tracing: {
        ignoreOutgoingRequests: (url) => {
          return url.startsWith(`${SUPABASE_URL}/rest`)
        },
      },
    }),

    // or @sentry/node with Fetch support
    Sentry.nativeNodeFetchIntegration({
      ignoreOutgoingRequests: (url) => {
        return url.startsWith(`${SUPABASE_URL}/rest`)
      },
    }),

    // or @sentry/WinterCGFetch for Next.js Middleware & Edge Functions
    Sentry.winterCGFetchIntegration({
      breadcrumbs: true,
      shouldCreateSpanForRequest: (url) => {
        return !url.startsWith(`${SUPABASE_URL}/rest`)
      },
    }),
  ],
})
```


## Example Next.js configuration

See this example for a setup with Next.js to cover browser, server, and edge environments. First, run through the [Sentry Next.js wizard](https://docs.sentry.io/platforms/javascript/guides/nextjs/#install) to generate the base Next.js configuration. Then add the Supabase Sentry Integration to all your `Sentry.init` calls with the appropriate filters.

Afterwards, build your application (`npm run build`) and start it locally (`npm run start`). You will now see the transactions being logged in the terminal when making supabase-js requests.