Transaction

interface Transaction {

query(statement: string, values: Value[]): Promise<Record<string, any>[]>

queryStream(statement: string, values: Value[] = []): RowStream

commit(): Promise<void>

rollback(): Promise<void>

}

Sometimes units of work include multiple steps that are difficult to wrap into a single query. In those cases, multiple queries can be run as part of a single Transaction.

Because transactions require a dedicated connection, transactions will be rolled back automatically if they are inactive for 5 seconds or take longer than 30 minutes to complete.

tip

If you need more dedicated connections for long-lived transactions, email [email protected] to upgrade to a dedicated instance

query

async function query(statement: string, values: Value[] = []): Promise<Record<string, any>[]>

Identitcal to the Client's query method, this method returns results from an individual query from within a single transaction. The results of these queries do not reflect the current state of the database outside of the transaction until the transaction's commit method has been called!

caution

Errors of any kind (including SQL errors) in query will result in a dropped transaction

queryStream

function queryStream(statement: string, values: Value[] = []): RowStream

Like query, but returning a stream of rows as they arrive from the server. This method is strongly preferred for large queries.

The RowStream returned by queryStream() is a standard Node stream that emits data, error, and end events. RowStream use object mode, returning Record<string, any> for each row as it arrives.

commit

async function commit(): Promise<void>

commit saves a unit of work after a series of queries. After commit, further calls to any of the methods on the original Transaction will throw an error.

rollback

async function rollback(): Promise<void>

rollback abandons a transaction instead of committing work in progress. After rollback, further calls to any of the methods on the original Transaction will throw an error.