Single-request database work
An edge or serverless handler needs to fetch or modify data with one SQL statement.
Neon · Module
client.query
client.query executes parameterized SQL through Neon’s serverless driver. Use sql.query for conventional SQL strings with $1-style placeholders; the HTTP driver is designed for single queries and non-interactive transactions.
How it works
The Neon serverless driver's query function sends SQL to Postgres over HTTP. Use sql.query with a SQL string and an ordered values array for conventional placeholders such as $1; the result is normally an array of row objects. The HTTP mode is intended for single queries and non-interactive transactions.
Syntax
sql.query(query, values, options)Parameters
| Name | Type | Description |
|---|---|---|
query | string | SQL statement containing PostgreSQL placeholders such as $1 and $2. |
values | unknown[] | Values supplied in placeholder order. |
options | object | Optional query or result-format configuration supported by the driver. |
Returns
By default, an array of row objects keyed by column name; fullResults can be used when the complete result object is needed.
Key points
- Use the neon function to create the HTTP query interface.
- The default interface is a tagged-template function for safer SQL construction.
- Use sql.query when your code needs ordinary function-call syntax with PostgreSQL placeholders.
Common mistakes
- The default query function returned by neon() is intended for tagged-template calls; use sql.query when supplying a SQL string and values array.
- Use sql.query for conventional parameterized calls instead of invoking the default function as an ordinary function.
Example: Parameterized query
import { neon } from '@neondatabase/serverless';
const sql = neon(process.env.DATABASE_URL!);
const userId = 42;
const rows = await sql.query('SELECT id, email FROM users WHERE id = $1', [userId]);
console.log(rows);Executes a parameterized query over HTTP and returns the matching rows.
When to use it
Conventional parameterized SQL
Application code uses positional PostgreSQL parameters instead of tagged-template interpolation.
HTTP-based database access
A query must run without maintaining a database session or TCP connection.
Interview questions
QHow does client.query relate to the driver's HTTP query API?
client.query is the node-postgres-compatible query API exposed by the driver's WebSocket Client. It accepts a SQL statement and parameters, while the HTTP query function uses sql.query for conventional $1-style placeholders.
Follow-up: When should HTTP be preferred? Use it for one-shot queries and non-interactive transactions; choose Client or Pool over WebSockets for sessions or interactive transactions.
QHow are parameters passed to a query?
A conventional parameterized call supplies the SQL text first and an ordered values array second, for example sql.query('SELECT ... WHERE id = $1', [id]). Parameter placeholders refer to positions in that array.
Follow-up: Why not interpolate values into SQL? Parameter binding keeps values separate from the SQL text and avoids SQL-injection risks.
QWhat does a successful query return by default?
The default HTTP query function returns rows as an array of objects whose keys are column names. Result formatting can be changed with options such as fullResults and arrayMode.
Follow-up: What is the trade-off of arrayMode? It returns positional row values rather than objects, which can reduce repeated column-name data but requires column-order awareness.
Related
neon()PoolClientfullResultsarrayModetransaction