pgwasm

Overview

No upstream tag or release; package pins commit 535b5336, ports pgrx 0.18 to 0.19.1, and supports PostgreSQL 14-18. Preloading is optional and enables shared metrics.

Version

Build

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

pig build pkg pgwasm         # build RPM / DEB packages

Install

You can install pgwasm 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:

• Install
• pig
• dnf
• apt

pig install pgwasm;          # Install for current active PG version

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

dnf install -y pgwasm_18       # PG 18
dnf install -y pgwasm_17       # PG 17
dnf install -y pgwasm_16       # PG 16
dnf install -y pgwasm_15       # PG 15
dnf install -y pgwasm_14       # PG 14

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

Create Extension:

CREATE EXTENSION pgwasm;

Usage

Sources:

• pgwasm README at the documented revision
• pgwasm architecture and SQL lifecycle
• pgwasm GUC reference
• pgwasm WIT type mapping
• pgwasm control file

pgwasm loads WebAssembly components into PostgreSQL and registers WIT exports as typed PostgreSQL functions. Compiled artifacts are stored under the cluster data directory and reused by backend-local instance pools. This document follows pinned revision 535b53363f8208af139e757e508e66c46309ee29; the source declares version 0.1.0 but does not provide a tagged 0.1.0 release.

Core Workflow

Create the extension as a superuser. The following file-based workflow must be enabled and confined by an administrator before a loader role can use it:

CREATE EXTENSION pgwasm;

ALTER SYSTEM SET pgwasm.allow_load_from_file = on;
ALTER SYSTEM SET pgwasm.module_path = '/srv/pgwasm';
ALTER SYSTEM SET pgwasm.allowed_path_prefixes = '/srv/pgwasm';
SELECT pg_reload_conf();

GRANT pgwasm_loader TO app_runtime;

SELECT pgwasm.pgwasm_load(
    'arith',
    '{"path":"arith.component.wasm"}'::json,
    '{}'::json
);

SELECT * FROM pgwasm.pgwasm_functions();
SELECT * FROM pgwasm.pgwasm_modules();

SELECT pgwasm.pgwasm_unload('arith');

pgwasm_load(module_name text, bytes_or_path json, options json) accepts exactly one bytes or path source. File loading is off by default. A module name becomes the durable catalog key and the prefix for sanitized generated SQL function names.

Lifecycle and Type Mapping

• pgwasm_load validates, resolves policy, creates required PostgreSQL types and functions, compiles an AOT artifact, and records the module.
• pgwasm_reload replaces module bytes while preserving stable identities when signatures remain compatible.
• pgwasm_reconfigure narrows or changes policy and resource limits.
• pgwasm_unload removes generated functions, types, catalog rows, and artifacts; dependencies block removal unless cascade is explicitly selected.
• WIT records map to composite types, enums to PostgreSQL enums, lists to arrays or bytea, and supported variants, flags, options, results, and resources to documented PostgreSQL representations.
• pgwasm_modules(), pgwasm_functions(), pgwasm_wit_types(), pgwasm_policy_effective(), and pgwasm_stats() provide inspection.

Review the generated function signatures before granting execute privileges or calling a newly loaded component. Reloads with breaking WIT changes require an explicit policy decision and dependency review.

Sandbox and Privileges

The extension creates pgwasm_loader for lifecycle mutation and pgwasm_reader for observability. Loading, reloading, reconfiguring, and unloading require superuser or loader-role membership.

WASI filesystem, environment, sockets, HTTP, and SPI host-query access are all disabled by default. An administrator sets the cluster ceiling through pgwasm.* GUCs; per-module options can narrow that ceiling but cannot broaden it. Keep pgwasm.allowed_hosts, path prefixes, and filesystem preopens explicit and minimal.

Resource and Operational Boundaries

• The default module-size limit is 32 MiB, invocation memory is 1,024 WebAssembly pages, and the wall-clock deadline is 5 seconds. Fuel metering is available but off by default.
• Artifacts under $PGDATA/pgwasm/<module_id>/ are derived from module bytes and the Wasmtime build. Recompile them after incompatible Wasmtime or PostgreSQL upgrades rather than copying them as authoritative data.
• Shared counters depend on postmaster-time shared-memory allocation. Preload pgwasm when shared metrics are required; otherwise observability can fall back to non-shared counters and reports that state.
• The source exposes build features for PostgreSQL 13 through 18 and defaults to PostgreSQL 17, but the pinned revision has no published support matrix. Validate the exact PostgreSQL-major build and all required WIT mappings before deployment.
• Treat guest code as privileged database-adjacent code even with sandboxing: limit who can load modules, bound every capability and resource, and test traps, cancellation, reload, restart, and rollback behavior.