Consistent multi-query reads
A request needs several independent reads to share one transactional snapshot.
Neon · Module
client.transaction
sql.transaction() executes multiple queries together in one non-interactive transaction. It accepts an array of queries or a synchronous query-producing function, with optional transaction settings.
How it works
The query function exposes transaction() for grouping multiple SQL queries into one non-interactive transaction. Pass either an array of tagged-template queries or a synchronous function that receives the query function and returns such an array. Optional transaction settings are supplied in a second argument.
Syntax
transaction(queriesOrFn, options)Parameters
| Name | Type | Description |
|---|---|---|
queriesOrFn | Query[] | (sql) => Query[] | An array of SQL queries, or a synchronous function receiving the query function and returning an array of queries. |
options | TransactionOptions | Optional query and transaction configuration, including isolationLevel, readOnly, and deferrable. |
Returns
A promise resolving to an array containing the result of each query, in the same order.
Key points
- Call transaction() as a method on the query function returned by neon().
- It batches multiple queries into one non-interactive transaction.
- The first argument may be an array of tagged-template queries.
- The second argument supports the normal query options as well as transaction-specific controls.
Common mistakes
- Put transaction settings in the second argument to transaction(), rather than attaching them to individual queries.
Example: Execute queries transactionally
import { neon } from '@neondatabase/serverless';
const sql = neon(process.env.DATABASE_URL);
const [users, posts] = await sql.transaction([
sql`SELECT * FROM users`,
sql`SELECT * FROM posts`
]);Runs both queries as one non-interactive transaction.
When to use it
Non-interactive grouped work
Several related statements must be submitted as one HTTP operation.
Controlled transaction semantics
A read workload needs explicit isolation or read-only behavior.
Interview questions
QWhat does sql.transaction() do, and what can its first argument contain?
transaction() groups multiple queries into one non-interactive transaction. Its first argument can be an array of queries or a synchronous function that returns an array of queries.
Follow-up: When should WebSockets be used instead? Use Pool or Client for interactive transactions, sessions, or node-postgres compatibility.
QWhich options can configure a transaction?
The second argument accepts ordinary query options plus isolationLevel, readOnly, and deferrable. These options configure how the transaction executes.
Follow-up: What combination is required for a deferrable transaction? readOnly must be true and isolationLevel must be Serializable, in addition to deferrable being true.
QWhen should transaction() be used instead of Pool or Client?
The HTTP neon() function is intended for single queries and non-interactive transactions. Pool or Client over WebSockets is intended when the transaction needs interaction across multiple steps or session behavior.
Follow-up: Why not use HTTP for an interactive transaction? HTTP executes the submitted batch rather than maintaining the persistent session required for interactive steps.
Related
neon()PoolClientisolationLevelreadOnlydeferrable