Skip to content

API Reference

HTTP

net.http_get

description

Create an HTTP GET request returning the request's id

Note

HTTP requests are not started until the transaction is committed

signature
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
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
1
2
3
4
5
select net.http_get('https://news.ycombinator.com') as request_id;
request_id
----------
         1
(1 row)

net.http_post

description

Create an HTTP POST request with a JSON body, returning the request's id

Note

HTTP requests are not started until the transaction is committed

Note

the body's character set encoding matches the database's server_encoding setting

signature
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
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
1
2
3
4
5
6
7
8
9
select
    net.http_post(
        url:='https://httpbin.org/post',
        body:='{"hello": "world"}'::jsonb
    ) as request_id;
request_id
----------
         1
(1 row)

net.http_collect_response

description

Given a request_id reference, retrieve the response.

When async:=false is set it is recommended that statement_timeout is set for the maximum amount of time the caller is willing to wait in case the response is slow to populate.

Warning

net.http_collect_response must be in a separate transaction from the calls to net.http_<method>

signature
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
net.http_collect_response(
    -- request_id reference
    request_id bigint,
    -- when `true`, return immediately. when `false` wait for the request to complete before returning
    async bool default true
)
    -- http response composite wrapped in a result type
    returns net.http_response_result

    strict
    volatile
    parallel safe
usage
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
select
    net.http_post(
        url:='https://httpbin.org/post',
        body:='{"hello": "world"}'::jsonb
    ) as request_id;
request_id
----------
         1
(1 row)

select * from net.http_collect_response(1, async:=false);
status  | message | response
--------+---------+----------
SUCCESS        ok   (
                      status_code := 200,
                      headers     := '{"date": ...}',
                      body        := '{"args": ...}'
                    )::net.http_response_result


select
    (response).body::json
from
    net.http_collect_response(request_id:=1);
                               body
-------------------------------------------------------------------
 {
   "args": {},
   "data": "{\"hello\": \"world\"}",
   "files": {},
   "form": {},
   "headers": {
     "Accept": "*/*",
     "Content-Length": "18",
     "Content-Type": "application/json",
     "Host": "httpbin.org",
     "User-Agent": "pg_net/0.1",
     "X-Amzn-Trace-Id": "Root=1-61031a5c-7e1afeae69bffa8614d8e48e"
   },
   "json": {
     "hello": "world"
   },
   "origin": "135.63.38.488",
   "url": "https://httpbin.org/post"
 }
(1 row)

where response is a composite

1
2
3
status_code integer
headers jsonb
body text
Possible values for net.http_response_result.status are ('PENDING', 'SUCCESS', 'ERROR')