Neon · Module

sql.query

sql.query() runs manually parameterized SQL through Neon's serverless driver. Supply SQL with PostgreSQL placeholders and a separate values array to execute a query without interpolating values into the statement.

Since: 1.0.0

How it works

sql.query() executes SQL with positional parameters supplied separately from the query text. It is the manual-parameterization alternative to the driver's tagged-template form and returns query rows unless result options request additional metadata.

Syntax

await sql.query(query, params, options?)

Parameters

Name	Type	Description
`query`	`string`	SQL statement containing PostgreSQL positional placeholders such as `$1`.
`params`	`unknown[]`	Values bound to the statement's positional placeholders.
`options`	`object`	Optional query configuration, including result-format and fetch options.

Returns

By default, an array of row objects; with full results enabled, a result object containing the rows and additional metadata.

Key points

Use sql.query() when the SQL text and positional values are supplied separately.
Parameters correspond to PostgreSQL placeholders such as $1 and are passed in a separate array.
The ordinary sql callable is tag-only, while sql.query() provides the explicit function-call form.
The normal return value contains query rows without extra result metadata.

Common mistakes

The function returned directly by neon() is restricted to tagged-template usage; use sql.query() when manually supplying a SQL string and parameter array.
The default result is an array of row objects, not a metadata wrapper.

Example: Parameterized query

import { neon } from '@neondatabase/serverless';

const sql = neon(process.env.DATABASE_URL!);
const [post] = await sql.query(
  'SELECT id, title FROM posts WHERE id = $1',
  [1]
);
console.log(post);

Executes a manually parameterized SQL query and returns the resulting rows.

When to use it

Manual parameter binding

A query is assembled as a SQL string and values must be bound separately.

Serverless database access

An edge or serverless handler needs to execute a one-shot SQL statement over Neon's driver.

Per-query configuration

Application code needs result-format or fetch behavior configured per query.

Interview questions

QWhat problem does sql.query() solve?

sql.query() accepts a SQL string and a separate array of positional parameter values. The driver sends the values independently, which supports manually parameterized queries and avoids placing values directly into SQL text.

Follow-up: How would you retrieve column-oriented results? Pass an options object with arrayMode: true; the returned rows then use arrays rather than objects.

QHow does sql.query() differ from calling sql directly?

It is the explicit query-function form for manually parameterized SQL, such as sql.query('... WHERE id = $1', [id]). The direct function returned by neon() is intended for tagged-template calls instead.

Follow-up: What is the alternative syntax for a simple query? Use the tagged template sql\SELECT ...\ rather than calling the returned function as an ordinary function.

QWhat does the query return by default?

By default, the result is an array of objects containing the rows produced by the SQL statement. Configuration can change the shape or include additional result metadata.

Follow-up: Which option exposes metadata? Set fullResults: true; metadata and rows are then available through the returned result's rows property.

neon()
fullResults
arrayMode
fetchOptions
transaction()

Source: Neon serverless driver. Checked 2026-10-16.