@neondatabase/serverless

When you require session support, interactive transactions, or compatibility with query builders like Kysely or Zapatos, use the Pool or Client constructors instead of the neon() function. These use WebSockets for communication.

Critical Usage Rules for Serverless/Edge

In environments like Vercel Edge Functions or Cloudflare Workers, WebSocket connections cannot outlive a single request.

1. Scope: You must create, use, and close Pool or Client objects within a single request handler.
2. Avoid Global Scope: Do not create these objects outside the request handler.
3. Cleanup: Always close the connection (e.g., using pool.end() or client.end()) to avoid exhausting available connections. In Vercel Edge Functions, use ctx.waitUntil(pool.end()) to ensure the connection closes without delaying the response.

Node.js WebSocket Configuration

In Node.js v21 and earlier, you must manually provide a WebSocket constructor (e.g., from the ws package) via neonConfig.webSocketConstructor.

import { Pool, neonConfig } from '@neondatabase/serverless';
import ws from 'ws';

// Required for Node v21 and below
neonConfig.webSocketConstructor = ws;

const pool = new Pool({ connectionString: process.env.DATABASE_URL });

This guide provides the sequence of commands to deploy wsproxy behind Nginx for TLS on an Ubuntu 22.04 host.

Prerequisites:

• Port 443 must be accessible (check firewall settings).
• Host must be running Ubuntu 22.04 (older versions may have incompatible Go versions).

Workflow:

1. Upgrade Ubuntu to 22.04.
2. Install and configure PostgreSQL with a password-authenticated user.
3. Build and install wsproxy from source.
4. Configure wsproxy as a systemd service.
5. Install Nginx and Certbot to handle TLS termination.
6. Configure Nginx to proxy WebSocket traffic to wsproxy.

# 1. Upgrade Ubuntu
sudo su
apt update -y && apt upgrade -y && apt dist-upgrade -y
apt autoremove -y && apt autoclean -y
apt install -y update-manager-core
do-release-upgrade

# 2. Setup Postgres
export HOSTDOMAIN=ws.example.com
apt install -y postgresql
echo 'create database wstest; create user wsclear; grant all privileges on database wstest to wsclear;' | sudo -u postgres psql
# Note: Run \password wsclear manually in psql to set password
perl -pi -e 's/^# IPv4 local connections:\n/# IPv4 local connections:\nhost all wsclear 127.0.0.1\/32 password\n/' /etc/postgresql/14/main/pg_hba.conf
service postgresql restart

# 3. Install wsproxy
adduser wsproxy --disabled-login
sudo su wsproxy
cd
git clone https://github.com/neondatabase/wsproxy.git
cd wsproxy
go build
exit

# 4. Configure systemd service
echo "
[Unit]
Description=wsproxy

[Service]
Type=simple
Restart=always
RestartSec=5s
User=wsproxy
Environment=LISTEN_PORT=:6543 ALLOW_ADDR_REGEX='^${HOSTDOMAIN}:5432\$"
ExecStart=/home/wsproxy/wsproxy/wsproxy

[Install]
WantedBy=multi-user.target
" > /lib/systemd/system/wsproxy.service

systemctl enable wsproxy
service wsproxy start

# 5. Install Nginx and Certbot
apt install -y golang nginx certbot python3-certbot-nginx
echo "127.0.0.1 ${HOSTDOMAIN}" >> /etc/hosts

# 6. Configure Nginx site
echo "
server {
  listen 80;
  listen [::]:80;
  server_name ${HOSTDOMAIN};
  location / {
    proxy_pass http://127.0.0.1:6543/;
    proxy_set_header Upgrade \$http_upgrade;
    proxy_set_header Connection Upgrade;
    proxy_set_header Host \$host;
  }
}
" > /etc/nginx/sites-available/wsproxy

ln -s /etc/nginx/sites-available/wsproxy /etc/nginx/sites-enabled/wsproxy
certbot --nginx -d ${HOSTDOMAIN}

# Final Nginx config is managed by Certbot; restart service
service nginx restart

If you are not using a Neon database, you can run your own WebSocket proxy to allow @neondatabase/serverless to connect to your own Postgres instances. This requires setting up a proxy (such as wsproxy) and securing it using one of two methods:

1. Nginx as a TLS Proxy: Place Nginx in front of wsproxy to handle TLS. In this setup, onward traffic from the proxy to Postgres is not secured by Nginx, so Postgres should reside on the same machine or be reached via a private network.
2. Experimental Pure-JS Encryption (subtls): Use the subtls library for end-to-end encryption. This does not require Nginx. To use this, set neonConfig.useSecureWebSocket and neonConfig.forceDisablePgSSL to false, and append ?sslmode=verify-full (or similar) to your connection string. Note: subtls is experimental and not recommended for production.

After setting up the proxy, you must configure the @neondatabase/serverless package with the wsProxy option (and subtls and rootCerts if using the experimental method).

The fetchOptions option allows you to pass a Record<string, any> that is merged with the underlying fetch call options. This can be applied to the neon() constructor, the transaction() function, or individual .query() calls.

Common use cases include:

• Setting request priority (e.g., 'high').
• Implementing timeouts using an AbortController signal.

import { neon } from '@neondatabase/serverless';

// Set high priority for all queries
const sql = neon(process.env.DATABASE_URL, {
  fetchOptions: { priority: 'high' },
});

// Implement a timeout for a specific query
const abortController = new AbortController();
const timeout = setTimeout(() => abortController.abort('timed out'), 10000);

try {
  const rows = await sql.query('SELECT * FROM posts WHERE id = $1', [postId], {
    fetchOptions: { signal: abortController.signal },
  });
} finally {
  clearTimeout(timeout);
}

You can customize how query results are returned by setting arrayMode or fullResults in the neon() constructor or the .query() options.

• arrayMode: boolean: When true, rows are returned as an array of arrays (e.g., [[val1, val2]]) instead of an array of objects. This is useful for performance or specific data shapes.
• fullResults: boolean: When true, the return value includes metadata similar to node-postgres (e.g., fields, rowCount, command), with the actual data located in the rows property.

import { neon } from '@neondatabase/serverless';

// Array mode: returns [[val1, val2]]
const sqlArray = neon(process.env.DATABASE_URL, { arrayMode: true });

// Full results: returns { rows: [...], fields: [...], rowCount: 1, ... }
const sqlFull = neon(process.env.DATABASE_URL, { fullResults: true });

// Using options directly in a query call
const results = await sql.query('SELECT * FROM posts WHERE id = $1', [postId], {
  arrayMode: true,
  fullResults: true
});