Session-based workflows
Run several dependent statements that must share one database session.
Neon · Class
Client
Neon’s Client is a WebSocket PostgreSQL client for JavaScript and TypeScript. Use it when an application needs a session, an interactive transaction, or node-postgres compatibility.
How it works
The Client constructor from @neondatabase/serverless uses the WebSocket transport and follows the node-postgres API. Connect it before issuing queries, then end it when finished; this mode is intended for sessions, interactive transactions, or node-postgres compatibility.
Syntax
new Client(config)Parameters
| Name | Type | Description |
|---|---|---|
config | string | ClientConfig | A Neon Postgres connection string, normally supplied through an environment variable. |
Returns
A WebSocket-based PostgreSQL client instance exposing the node-postgres-compatible client API.
Key points
- Client belongs to Neon’s JavaScript and TypeScript serverless Postgres driver.
- The driver supports serverless and edge environments through HTTP or WebSocket transports.
- Client supports stateful sessions and transactions.
- Client exposes compatibility with the node-postgres programming model.
Common mistakes
- Use Client for sessions and interactive transactions rather than one-shot queries, for which the HTTP
neon()function is the documented choice. - A Client maintains WebSocket-based session state, so it is not equivalent to an independent HTTP request for every query.
Example: Query with Client
import { Client } from '@neondatabase/serverless';
const client = new Client(process.env.DATABASE_URL);
await client.connect();
try {
const result = await client.query('SELECT NOW() AS current_time');
console.log(result.rows[0]);
} finally {
await client.end();
}Creates a WebSocket Client, connects, runs a query, and closes the connection.
When to use it
Interactive transactions
Execute a multi-step transaction whose statements depend on earlier results.
node-postgres compatibility
Adapt code or libraries built around the node-postgres client interface.
Interview questions
QWhat is Neon’s Client used for?
Client is a WebSocket-based constructor in @neondatabase/serverless. It provides session and transaction support and is compatible with the node-postgres API.
Follow-up: When should HTTP be preferred? Use the neon() function for single queries and non-interactive transactions because those do not require a persistent session.
QHow do you use a Neon Client safely?
Instantiate Client with the database connection string, call connect(), execute queries through query(), and call end() when the session is complete. This follows the WebSocket client pattern described for the driver.
Follow-up: Why must cleanup be explicit? The WebSocket session remains active until it is closed, so ending the client prevents an unused connection from remaining open.
QHow do Client and the HTTP driver mode differ?
Neon’s Client is intended for WebSocket usage, while the driver’s HTTP mode is intended for single queries and non-interactive transactions. The choice depends on whether the application needs a session or interactive transaction.
Follow-up: What compatibility benefit does Client provide? Its API is compatible with node-postgres, helping applications and tools that expect that client interface use the Neon driver.
Related
Poolneon()transaction()neonConfignode-postgres