supabase/apps/docs/pages/guides/database/extensions/pgnet.mdx

import Layout from '~/layouts/DefaultGuideLayout'

export const meta = {
  id: 'pgnet',
  title: 'pg_net: Async Networking',
  description: 'pg_net: an async networking extension for PostgreSQL.',
}

<Admonition type="caution">

The pg_net API is in alpha. Functions signatures may change.

</Admonition>

[pg_net](https://github.com/supabase/pg_net/) is a PostgreSQL extension exposing a SQL interface for async networking with a focus on scalability and UX.

It differs from the `http` extension in that it is asynchronous by default. This makes it useful in blocking functions (like triggers).

## Enable the extension

<Tabs
  scrollable
  size="small"
  type="underlined"
  defaultActiveId="dashboard"
>
<TabPanel id="dashboard" label="Dashboard">

1. Go to the [Database](https://supabase.com/dashboard/project/_/database/tables) page in the Dashboard.
2. Click on **Extensions** in the sidebar.
3. Search for "pg_net" and enable the extension.

</TabPanel>
<TabPanel id="sql" label="SQL">

```sql
-- Example: enable the "pg_net" extension.
create extension pg_net;
-- Note: The extension creates its own schema/namespace named "net" to avoid naming conflicts.

-- Example: disable the "pg_net" extension
drop extension if exists pg_net;
drop schema net;
```

Even though the SQL code is `create extension`, this is the equivalent of "enabling the extension".
To disable an extension, call `drop extension`.

Procedural languages are automatically installed within `pg_catalog`, so you don't need to specify a schema.

</TabPanel>
</Tabs>

## `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]

<Admonition type="caution">

This is a Postgres SECURITY DEFINER function.

</Admonition>

```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,
    -- WARNING: this is currently ignored, so there is no timeout
    -- the maximum number of milliseconds the request may take before being cancelled
    timeout_milliseconds int default 1000
)
    -- 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)
```

After triggering `http_get`, use [`http_get_result`](#http_get_result) to get the result of the request.

## `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]

<Admonition type="caution">

This is a Postgres SECURITY DEFINER function

</Admonition>

```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,
    -- WARNING: this is currently ignored, so there is no timeout
    -- the maximum number of milliseconds the request may take before being cancelled
    timeout_milliseconds int default 1000
)
    -- 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)
```

After triggering `http_post`, use [`http_get_result`](#http_get_result) to get the result of the request.

## 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.functions.supabase.co/function-name',
        headers:='{"Content-Type": "application/json", "Authorization": "Bearer YOUR_ANON_KEY"}'::jsonb,
        body:='{"name": "pg_net"}'::jsonb
    ) as request_id;
```

## Resources

- Source code: [github.com/supabase/pg_net](https://github.com/supabase/pg_net/)
- Official Docs: [supabase.github.io/pg_net](https://supabase.github.io/pg_net/)

export const Page = ({ children }) => <Layout meta={meta} children={children} />

export default Page