Batch related operations
An HTTP or edge request needs several database reads or writes grouped into one unit of work.
Neon · Function
transaction
transaction() executes multiple Neon SQL queries together in one non-interactive transaction. Call it on the query function returned by neon() and provide an array of queries or a synchronous query-producing callback.
How it works
Call transaction() on the query function returned by neon(). Pass an array of tagged-template queries, or a non-async function that receives a query function and returns an array. Neon executes the queries together in one non-interactive transaction and returns their results in the corresponding order.
Syntax
transaction(queriesOrFn, options)Parameters
| Name | Type | Description |
|---|---|---|
queriesOrFn | Query[] | (sql: NeonQueryFunction) => Query[] | An array of queries, or a non-async function receiving a query function and returning an array of queries. |
options | TransactionOptions | Optional query and transaction configuration. |
Returns
A promise resolving to the query results in the same order as the supplied queries.
Key points
- After creating a query function with
neon(), invoke itstransaction()method. - Use it to group several queries into one atomic, non-interactive operation.
- The first argument can be an array containing the queries to execute.
- Alternatively, provide a synchronous callback that receives a query function and returns query expressions.
- The optional options argument inherits the regular query function’s option keys.
Common mistakes
- Put transaction and query options in the second argument to
transaction(), rather than attaching them to individual queries. - When setting
isolationLevel, use one of the four documented PostgreSQL isolation-level values. deferrablerequires both a read-only transaction and Serializable isolation.
Example: Execute multiple queries transactionally
import { neon } from '@neondatabase/serverless';
const sql = neon(process.env.DATABASE_URL!);
const [posts, tags] = await sql.transaction([
sql`SELECT * FROM posts ORDER BY posted_at DESC LIMIT ${10}`,
sql`SELECT * FROM tags`
]);
console.log({ posts, tags });Runs two parameterized queries together as one non-interactive transaction.
When to use it
Fetch multiple result sets
A request must retrieve independent result sets while minimizing separate database round trips.
Group coordinated writes
A write workflow needs all included statements to participate in the same non-interactive transaction.
Interview questions
QWhat does Neon’s transaction() function do?
transaction() is a property of the query function returned by neon(). It accepts an array of queries or a non-async callback that returns an array, and executes those queries in one non-interactive transaction.
Follow-up: When should WebSockets be used instead? Use the WebSocket driver for interactive transactions or session-oriented work; HTTP transactions are non-interactive.
QHow do you pass multiple queries to transaction()?
The array form lets you issue multiple queries together, and the returned results correspond to the queries in array order. The queries should be supplied as tagged-template expressions from the Neon query function.
Follow-up: How can transaction behavior be configured? Pass an options object as the second argument, including isolation, read-only, or deferrable settings.
QWhich options configure a transaction?
The second argument accepts the ordinary query options plus transaction-specific settings. Those settings include isolationLevel, readOnly, and deferrable.
Follow-up: What constraint applies to deferrable? It is effective only when readOnly is true and the isolation level is Serializable.
Related
neon()Neon serverless driverisolationLevelreadOnlydeferrable