Single HTTP query
Run an isolated database read or write from a serverless or edge handler.
Neon · Function
sql
Neon's neon() function creates a tagged-template query function for running Postgres SQL over HTTP. It supports parameter-safe interpolation and exposes a transaction helper for multiple queries in one non-interactive transaction.
- Since
- 1.0.0
How it works
The neon() function accepts a database connection string and returns a query function. Invoke that function with a tagged template literal containing SQL and interpolated values; the driver sends the query over HTTP and returns the result rows. The returned query function also exposes transaction for multiple statements in one non-interactive transaction.
Syntax
neon(connectionString)Parameters
| Name | Type | Description |
|---|---|---|
connectionString | string | A Neon Postgres connection string, commonly supplied from process.env.DATABASE_URL. |
query | tagged template | SQL supplied as a tagged template literal, with interpolated values treated as parameters. |
Returns
A tagged-template query function that resolves to query result rows and exposes transaction(queriesOrFn, options).
Key points
- The driver executes queries over HTTP by default.
- The result of
neon()is itself the callable query interface. - Tagged-template invocation keeps interpolated values in the driver's safe parameter-handling path.
- The returned query function includes a transaction helper for grouping multiple statements.
- Use
transactionwhen several queries need one non-interactive transactional execution.
Common mistakes
- Call the returned function with a tagged template literal, not as an ordinary function with a SQL string and parameter array.
- HTTP mode is suited to single queries and non-interactive transactions; it is not a general replacement for a persistent interactive database session.
Example: Run a query with the Neon serverless driver
import { neon } from '@neondatabase/serverless';
const sql = neon(process.env.DATABASE_URL!);
const rows = await sql`SELECT NOW() AS current_time`;
console.log(rows);Creates a Neon query function and executes a parameter-safe SQL template query.
When to use it
Non-interactive transaction
Execute several related statements without opening an interactive session.
Parameterized SQL
Insert request-derived values while avoiding SQL string concatenation.
Interview questions
QWhat does the Neon serverless driver's neon() function return?
neon() creates a query function configured with the database connection string. The query function is used as a tagged template, and the driver sends each HTTP query through fetch.
Follow-up: How are multiple statements grouped atomically? Use the query function's transaction(queriesOrFn, options) property to execute them in one non-interactive transaction.
QHow should values be supplied to a query?
Use a tagged template such as sqlSELECT NOW(). Interpolated values are handled as parameters, and the documentation states that tagged-template-only usage improves protection against SQL injection.
Follow-up: Why not concatenate user input into the SQL text? Concatenation changes data into executable SQL text, whereas interpolation through the tagged template preserves parameterization.
QWhen is HTTP execution through the serverless driver appropriate?
The driver defaults to HTTP for queries. This is optimized for single queries and multiple queries in a non-interactive transaction, while the returned query function also provides a transaction helper.
Follow-up: What constraint follows from HTTP execution? Code requiring an interactive session should use an appropriate connection-oriented driver rather than assuming each request shares session state.
Related
transactionneonNeon serverless driverHTTP