This example demonstrates NpgsqlRest's reverse proxy feature, which allows you to forward HTTP requests to upstream services and optionally process the responses in PostgreSQL.

When a proxy endpoint function has no proxy response parameters, NpgsqlRest:

• Forwards the request to the upstream service
• Returns the upstream response directly to the client
• Does NOT open a database connection (saves connection pool resources)

-- Passthrough: no DB connection opened
create function ai_health()
returns void
language sql as $$select$$;

comment on function ai_health is 'proxy http://localhost:3001/health';

When a proxy endpoint function has proxy response parameters (_proxy_body, _proxy_status_code, etc.), NpgsqlRest:

• Forwards the request to the upstream service
• Passes the upstream response to your PostgreSQL function
• Your function can transform, enrich, cache, or validate the response

-- Transform: response is passed to PostgreSQL for processing
create function ai_summarize(
    _text text,
    _proxy_body text default null,
    _proxy_success boolean default null
)
returns json
language plpgsql as $$
begin
    -- Cache the result, enrich with metadata, etc.
    return _proxy_body::json;
end;
$$;

comment on function ai_summarize is 'proxy POST http://localhost:3001/summarize';

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Client    │────>│  NpgsqlRest │────>│  AI Service │
│  (Browser)  │<────│   (Proxy)   │<────│    (Bun)    │
└─────────────┘     └──────┬──────┘     └─────────────┘
                          │
                    ┌─────v─────┐
                    │ PostgreSQL │
                    │  (Cache)   │
                    └───────────┘

cd examples/10_proxy_ai_service
bun run upstream

bun run db:up

bun run dev

Navigate to http://127.0.0.1:8080

The proxy feature is enabled in config.json:

{
  "NpgsqlRest": {
    "ProxyOptions": {
      "Enabled": true,
      "Host": "http://localhost:3001",
      "DefaultTimeout": "00:00:30"
    }
  }
}

1. API Gateway: Route requests to different microservices
2. Caching Layer: Cache expensive external API calls in PostgreSQL
3. Data Enrichment: Combine external data with local database data
4. Rate Limiting: Track and limit API calls per user
5. Response Transformation: Modify external API responses before returning
6. Audit Logging: Log all external API interactions
7. Fallback Handling: Return cached data when upstream is unavailable