pg_net

Overview

Package/source version 0.20.5 ships SQL/control version 0.20.4. PIGSTY 0.20.5 covers EL10 RPM and D12/D13/U24/U26 DEB for PostgreSQL 14-18; older PIGSTY platform cells remain on 0.9.2. shared_preload_libraries=pg_net is required.

Version

Build

You can build the RPM / DEB packages for pg_net using pig build:

pig build pkg pg_net         # build RPM / DEB packages

Install

You can install pg_net directly. First, make sure the PGDG and PIGSTY repositories are added and enabled:

pig repo add pgsql -u          # Add repo and update cache

Install the extension using pig or apt/yum/dnf:

pig install pg_net;          # Install for current active PG version

pig ext install -y pg_net -v 18  # PG 18
pig ext install -y pg_net -v 17  # PG 17
pig ext install -y pg_net -v 16  # PG 16
pig ext install -y pg_net -v 15  # PG 15
pig ext install -y pg_net -v 14  # PG 14

dnf install -y pg_net_18       # PG 18
dnf install -y pg_net_17       # PG 17
dnf install -y pg_net_16       # PG 16
dnf install -y pg_net_15       # PG 15
dnf install -y pg_net_14       # PG 14

apt install -y postgresql-18-pg-net   # PG 18
apt install -y postgresql-17-pg-net   # PG 17
apt install -y postgresql-16-pg-net   # PG 16
apt install -y postgresql-15-pg-net   # PG 15
apt install -y postgresql-14-pg-net   # PG 14

Preload:

shared_preload_libraries = 'pg_net';

Create Extension:

CREATE EXTENSION pg_net;

Usage

Sources: official README, v0.20.3 release notes.

pg_net queues asynchronous HTTP and HTTPS requests from SQL. It creates the net schema, stores pending work in net.http_request_queue, and stores responses in net._http_response. A background worker uses libcurl to process queued requests.

The extension requires shared_preload_libraries = 'pg_net' and libcurl >= 7.83.

GET Request

CREATE EXTENSION pg_net;

SELECT net.http_get(
  'https://postman-echo.com/get',
  params := '{"foo": "bar"}'::jsonb,
  headers := '{"API-KEY": "<key>"}'::jsonb,
  timeout_milliseconds := 1000
) AS request_id;

net.http_get(url, params, headers, timeout_milliseconds) returns a bigint request id.

POST Request

SELECT net.http_post(
  'https://postman-echo.com/post',
  body := '{"key": "value"}'::jsonb,
  headers := '{"Content-Type": "application/json"}'::jsonb,
  timeout_milliseconds := 1000
) AS request_id;

Send one table row as JSON:

WITH selected_row AS (
  SELECT * FROM my_table LIMIT 1
)
SELECT net.http_post(
  'https://api.example.com/data',
  to_jsonb(selected_row.*)
) AS request_id
FROM selected_row;

DELETE Request

SELECT net.http_delete(
  'https://api.example.com/resource/42',
  timeout_milliseconds := 2000
) AS request_id;

net.http_delete(url, params, headers, timeout_milliseconds) is SECURITY DEFINER and returns a bigint request id.

Checking Responses

SELECT id, status_code, content, error_msg, created
FROM net._http_response
ORDER BY created DESC;

Failed requests can be identified from status_code and error_msg. The response table does not preserve every original request argument, so store request metadata separately if you need retry workflows.

Configuration

SHOW pg_net.batch_size;
SHOW pg_net.ttl;
SHOW pg_net.database_name;
SHOW pg_net.username;

• pg_net.batch_size, default 200, limits how many queued requests the worker processes per cycle.
• pg_net.ttl, default 6 hours, controls response retention.
• pg_net.database_name, default postgres, selects the database where the worker runs.
• pg_net.username, default NULL, selects the worker connection user; NULL uses the bootstrap user.

Settings can be changed in postgresql.conf or with ALTER SYSTEM:

ALTER SYSTEM SET pg_net.ttl TO '1 hour';
ALTER SYSTEM SET pg_net.batch_size TO 500;
SELECT pg_reload_conf();

Changing pg_net.database_name or pg_net.username requires restarting the worker:

SELECT net.worker_restart();

Caveats

• Pigsty metadata carries pg_net 0.20.3 for PostgreSQL 14-18, but local package notes say 0.20.3 is available only on d12, d13, el10, u24, and u26; el8, el9, and u22 remain on 0.9.2 because of older libcurl.
• Upstream documents PostgreSQL 12+ compatibility, but this catalog row is packaged for PostgreSQL 14-18.
• pg_net supports only one database per cluster through pg_net.database_name.
• v0.20.3 is a worker/maintenance release: it flushes pgstat counters for autovacuum visibility and reports worker activity to pg_stat_activity; no new SQL request API was documented.