Provide WebSocket support in older Node.js
A Node.js 21 or earlier application uses Pool or Client for sessions or interactive transactions.
Neon · Pipe
webSocketConstructor
neonConfig.webSocketConstructor configures the WebSocket implementation used by Neon’s serverless driver. Set it before constructing a WebSocket-based Pool or Client when the runtime lacks a built-in WebSocket.
How it works
neonConfig.webSocketConstructor lets the Neon serverless driver use a supplied WebSocket implementation when a runtime lacks a built-in one. Set it before constructing a Pool or Client; Node.js 22 and later normally provide WebSocket themselves.
Syntax
neonConfig.webSocketConstructor = WebSocketConstructor;Returns
No value; it configures the WebSocket constructor used by the Neon serverless driver.
Key points
- Configure this option for the driver's WebSocket-based
PoolandClientconstructors. - A runtime without native WebSocket support can use the constructor exported by the
wspackage. - Import
neonConfigfrom@neondatabase/serverlessalongside the WebSocket client you plan to use. - Assign the constructor directly to
neonConfig.webSocketConstructorbefore opening a driver connection.
Common mistakes
- Older Node.js versions and some runtimes need an explicitly supplied WebSocket constructor.
- Do not add the external constructor unnecessarily when the runtime already provides WebSocket.
- A WebSocket constructor is unnecessary for one-shot queries or non-interactive transactions; use the HTTP driver instead.
Example: Configure ws for a Neon Pool
import { Pool, neonConfig } from '@neondatabase/serverless';
import ws from 'ws';
neonConfig.webSocketConstructor = ws;
const pool = new Pool({ connectionString: process.env.DATABASE_URL });
const result = await pool.query('SELECT 1');
console.log(result.rows);
await pool.end();Assign the ws implementation before creating a WebSocket-based Pool, then close the pool after querying.
When to use it
Adapt a non-browser runtime
A runtime does not expose a global WebSocket implementation but the application needs the Neon driver’s WebSocket transport.
Use the `ws` package with Neon
An application uses the ws package as its WebSocket implementation for a Neon connection.
Interview questions
QWhy would an application set neonConfig.webSocketConstructor?
Set neonConfig.webSocketConstructor to a compatible constructor, such as the ws export, before creating the Pool or Client. This supplies WebSocket support to runtimes that do not provide it globally.
Follow-up: When can the configuration be omitted? It can be omitted in Node.js 22 and later because those versions include a built-in WebSocket.
QWhich Neon clients are affected by this configuration?
The setting matters when using the serverless driver's WebSocket-based Pool or Client in a runtime without built-in WebSocket support. It is not needed merely to use the HTTP neon() function.
Follow-up: Which transport fits independent one-shot queries? Use the HTTP driver, because those operations do not require a persistent WebSocket session.
QWhen should WebSockets be chosen instead of HTTP?
Use a WebSocket constructor when the application needs Pool or Client functionality and the runtime lacks WebSocket support. Those clients provide session and transaction behavior over WebSockets.
Follow-up: Why not always choose WebSockets? HTTP is preferable for one-shot queries and non-interactive transactions, while WebSockets are for interactive transactions, sessions, or node-postgres compatibility.
Related
PoolClientneonConfigneon()WebSocketsHTTP