One-shot HTTP queries
A serverless function needs to run a single SQL query without maintaining a database session.
Neon · Const
serverless driver
Neon’s serverless driver lets JavaScript and TypeScript applications query Postgres from serverless and edge runtimes over HTTP or WebSockets. Use neon() over HTTP by default, reserving Pool or Client for sessions, interactive transactions, or pg compatibility.
How it works
The Neon serverless driver is a JavaScript and TypeScript Postgres driver for serverless and edge environments. Its neon() function sends queries over HTTP, while Pool and Client use WebSockets for interactive transactions, sessions, or compatibility with node-postgres.
Syntax
neon(connectionString)Parameters
| Name | Type | Description |
|---|---|---|
connectionString | string | Neon PostgreSQL connection string used to configure the client. |
Returns
A query client function from neon() that executes SQL over HTTP and resolves query results.
Key points
- The package provides a Postgres driver for JavaScript and TypeScript applications.
- It supports querying from serverless and edge runtimes through either supported transport.
- Installation is package-manager agnostic, provided the
@neondatabase/serverlesspackage is added to the project.
Common mistakes
- HTTP is the default choice for single queries and non-interactive transactions; WebSockets are for stateful or interactive use cases.
Example: Query Neon over HTTP
import { neon } from '@neondatabase/serverless';
const sql = neon(process.env.DATABASE_URL!);
const posts = await sql`SELECT * FROM posts`;
console.log(posts);Creates an HTTP-based Neon SQL client from the connection string and runs a parameterized query.
When to use it
Edge-runtime database access
An edge application runs in an environment where direct TCP database connections are unsuitable.
WebSocket sessions and interactive transactions
An application requires session state or multiple coordinated statements in an interactive transaction.
Interview questions
QWhat problem does the Neon serverless driver solve?
The driver is a JavaScript and TypeScript Postgres driver designed for serverless and edge runtimes. It communicates with Neon over HTTP or WebSockets instead of TCP.
Follow-up: Which transport should be preferred for a single query? Use HTTP through the neon() function because it is the documented default for single queries and non-interactive transactions.
QHow do you issue a basic query?
Call neon() with a Neon connection string, then execute a tagged-template query such as sql\SELECT ...\. The HTTP client is intended for single queries and non-interactive transactions.
Follow-up: How would the client change for an interactive transaction? Use Pool or Client over WebSockets, because those APIs maintain the state needed for interactive transactions.
QWhen should Pool or Client be used instead of neon()?
Use Pool or Client when the application needs interactive transactions, sessions, or compatibility with pg. For ordinary serverless queries, use neon() over HTTP instead.
Follow-up: Why is this distinction useful in edge environments? HTTP avoids requiring a TCP connection, matching runtimes that support HTTP-based database access but restrict traditional sockets.
Related
neon()PoolClient@neondatabase/serverless