pgxio

SQL-first backend Alpha

Fast PostgreSQL APIs.
Low memory use.

A Rust module for Nginx that exposes PostgreSQL functions over HTTP and delivers change notifications over WebSockets.

Get started

How pgxio reduces overhead

Nginx event loop

HTTP, WebSockets, and nonblocking database I/O share Nginx’s event loop.

Reused database connections

Prepared statements and pipelining reduce repeated work and database round trips.

No JSON reserialization

PostgreSQL’s JSONB response text passes through unchanged. Disabling output validation also avoids response JSON parsing.

Zero-copy request forwarding Experimental

The patched-libpq build eliminates request-body copies into Rust and libpq for eligible requests. Automatic borrowing applies to qualifying large requests over plaintext database connections. Standard builds retain copying.

The benchmark above used copied buffers. Responses and TLS still involve copies.

How it works

pgxio.confConfiguration excerpt
# HTTP endpoints
pgxio_endpoint list_tasks
  web.list_tasks read_only;

pgxio_endpoint create_task
  web.create_task;

# WebSocket subscription authorization
pgxio_stream tasks
  web.authorize_tasks;
  1. 01

    Write SQL functions

    SQL functions accept and return JSON. They handle queries, business rules, and authorization.

  2. 02

    Publish explicit endpoints

    Declare the functions your API exposes. pgxio checks JWTs and calls each function inside a transaction.

  3. 03

    Subscribe to changes

    Authorized WebSocket subscriptions signal changes. Your client refetches the current snapshot over HTTP.

Browser / clientHTTP + WebSocket
pgxio inside NginxRust + nonblocking libpq
PostgreSQLFunctions + notifications

Subscriptions deliver change signals, not a durable event log. On reconnect, clients resubscribe and fetch a fresh snapshot.

Run locally

Run these commands from an existing pgxio checkout. You’ll need Docker Compose and Python 3.9 or newer.

The included development stack binds to localhost. pgxio is alpha software; this configuration is for local exploration.

Terminal · from your pgxio checkout
bin/pgxio init
bin/pgxio up
TOKEN=$(bin/pgxio token alice)

curl http://localhost:8080/v1/create_task \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"title":"Hello from pgxio"}'

curl http://localhost:8080/v1/list_tasks \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{}'