Interactive transactions
An application must execute multiple statements within an interactive transaction.
Neon · Const
WebSocket driver
The Neon serverless driver supports WebSocket-based PostgreSQL access through Pool and Client. Use this transport for interactive transactions, sessions, or node-postgres compatibility; use HTTP by default for simpler queries.
How it works
The Neon serverless driver uses WebSockets through its Pool or Client constructors when an application needs a persistent session, interactive transactions, or node-postgres compatibility. The connection is established through the driver’s WebSocket transport, while Pool and Client expose familiar PostgreSQL APIs. In environments without a native WebSocket implementation, configure a constructor such as ws.
Syntax
new Pool(config)
new Client(config)Returns
Pool and Client expose query results through the node-postgres-compatible API; the page does not define a separate return value for a constant named WebSocket driver.
Key points
- Pool and Client are the driver’s WebSocket-enabled constructors.
- These constructors support sessions, transactions, and compatibility with the node-postgres API.
- HTTP is the preferred transport unless the application requires WebSocket-specific capabilities.
- Select WebSockets for interactive transactions, sessions, or node-postgres compatibility.
Common mistakes
- Older Node.js releases and some runtimes need an explicitly supplied WebSocket implementation.
- When the runtime lacks WebSocket support, provide a constructor from a compatible package such as ws.
- For Node.js 22 and newer, adding a separate WebSocket constructor is optional.
Example: Query with a WebSocket Pool
import { Pool } from '@neondatabase/serverless';
const pool = new Pool({ connectionString: process.env.DATABASE_URL });
const result = await pool.query('SELECT NOW()');
console.log(result.rows);
await pool.end();Creates a WebSocket-backed pool, runs a query through the node-postgres-compatible API, and closes the pool.
When to use it
Database sessions
Code requires a persistent PostgreSQL session rather than independent HTTP requests.
node-postgres compatibility
An ORM or library expects the node-postgres-compatible Pool or Client API.
Interview questions
QWhen should the Neon driver use WebSockets instead of HTTP?
Use WebSocket transport with Pool or Client when the application needs interactive transactions, sessions, or compatibility with node-postgres. The driver supports those constructors for WebSocket-based querying.
Follow-up: Why not use WebSockets for every query? HTTP is the default recommendation for single queries and non-interactive transactions because it is better suited to those request patterns.
QWhat do Pool and Client provide beyond basic HTTP querying?
Pool and Client provide session and transaction support and expose a node-postgres-compatible interface. That makes them suitable for applications or libraries expecting the pg-style API.
Follow-up: What configuration issue can arise on older Node.js versions? A WebSocket constructor must be supplied when the runtime does not provide one natively.
QWhy is this driver useful in serverless or edge runtimes?
The driver is designed for JavaScript and TypeScript applications in serverless and edge environments, where TCP connections may not be available. WebSockets provide the connection-oriented behavior needed for sessions and interactive transactions.
Follow-up: What should be checked before deployment? Verify that the target runtime supports WebSockets or configure an appropriate constructor through the driver settings.
Related
PoolClientneonConfig@neondatabase/serverless