method

SQL.Query.cancel

Cancels the query.

A query that Bun has not sent yet never runs. It rejects with ERR_POSTGRES_QUERY_CANCELLED (or the MYSQL / SQLITE code).

PostgreSQL: Bun asks the server to stop a running query, on a second connection. The query rejects with the server's error, errno "57014", or resolves if it ends first. A query that Bun sent behind another one, or that has another one sent behind it, rejects with ERR_POSTGRES_QUERY_CANCELLED and a hint, because the server may still run it.

MySQL: a query that Bun has sent runs to the end and settles with its result.

Referenced types

interface Query<T>

A pending SQL query. Extends Promise, so it can be awaited, and adds methods to control how it runs. The array it resolves to also has ResultMetadata.

A query is lazy. It starts in the call to then(), catch(), finally() or execute, and await calls then().

What then() and catch() return is a promise like any other: when it rejects with nothing to handle the rejection, that is reported as an unhandled rejection. So is an error that a finally() callback throws.

The failure of a query that was only started, with execute() or finally(), is not reported once it has a connection, nor when close({ timeout: 0 }) closes the pool while it waits for one, when it was cancelled before it started, or when its reservation, transaction or savepoint has ended. After execute(), a failure to connect, a pool that was already closed, a cancel() or the end of the time of close({ timeout }), with a timeout above 0, while it waits for a connection, and a query that cannot be built are reported. So is the failure of a query that SQLite runs outside a transaction.

Bun reads the parameters when it sends the query. Leave a Buffer, TypedArray, Date or object that you passed alone until the query settles.

readonly [Symbol.toStringTag]: string
active: boolean
True while a connection runs the query
cancelled: boolean
True after cancel was called
cancel(): Query<T>;
Cancels the query.
A query that Bun has not sent yet never runs. It rejects with ERR_POSTGRES_QUERY_CANCELLED (or the MYSQL / SQLITE code).
PostgreSQL: Bun asks the server to stop a running query, on a second connection. The query rejects with the server's error, errno "57014", or resolves if it ends first. A query that Bun sent behind another one, or that has another one sent behind it, rejects with ERR_POSTGRES_QUERY_CANCELLED and a hint, because the server may still run it.
MySQL: a query that Bun has sent runs to the end and settles with its result.
catch<TResult = never>(
onrejected?: null | (reason: any) => TResult | PromiseLike<TResult>
): Promise<T & ResultMetadata | TResult>;
Attaches a callback for only the rejection of the Promise.
@param onrejected
The callback to execute when the Promise is rejected.
@returns
A Promise for the completion of the callback.
execute(): Query<T>;
Starts executing the query. Queries are lazy: they only run when awaited or executed with this method.
finally(
onfinally?: null | () => void
): Promise<T & ResultMetadata>;
Attaches a callback that is invoked when the Promise is settled (fulfilled or rejected). The resolved value cannot be modified from the callback.
@param onfinally
The callback to execute when the Promise is settled (fulfilled or rejected).
@returns
A Promise for the completion of the callback.
raw(): Query<T>;
Returns rows as arrays of Buffer objects instead of objects.
PostgreSQL and MySQL: the bytes the server sent. On PostgreSQL a prepared query gets bool, int4, float4, float8, numeric, bytea, time, timestamp, timestamptz, int4[] and float4[] in binary and every other type as text; all types are text on the first run of a query without parameters, with .simple() and with prepare: false. On MySQL a prepared query is binary. SQLite: Uint8Array objects.
Call it before the query starts. After that, SQLite ignores it, and on PostgreSQL some types can arrive in the other format.
readable(): ReadableStream<Uint8Array<ArrayBuffer>>;
PostgreSQL only. Starts a COPY ... TO STDOUT query and returns the bytes that the server sends, in the format that the statement names. A chunk can end in the middle of a row.
Call it before the query starts. The query takes no parameters, and resolves with the row count in count when the server has finished. A failure reaches the stream, so the query needs no handler of its own.
await Bun.write("users.csv", new Response(sql`COPY users TO STDOUT (FORMAT csv)`.readable()));
simple(): Query<T>;
Executes the query as a simple query. Parameters are not allowed, but the query can contain multiple commands separated by semicolons.
then<TResult1 = T & ResultMetadata, TResult2 = never>(
onfulfilled?: null | (value: T & ResultMetadata) => TResult1 | PromiseLike<TResult1>,
onrejected?: null | (reason: any) => TResult2 | PromiseLike<TResult2>
): Promise<TResult1 | TResult2>;
Attaches callbacks for the resolution and/or rejection of the Promise.
@param onfulfilled
The callback to execute when the Promise is resolved.
@param onrejected
The callback to execute when the Promise is rejected.
@returns
A Promise for the completion of which ever callback is executed.
values(): Query<T>;
Returns each row as an array of values, in the same order as the columns in the query.
It has no effect after execute() on SQLite, which has run the query.
writable(): WritableStream<string | ArrayBufferLike | TypedArray<ArrayBufferLike> | DataView<ArrayBufferLike>>;
PostgreSQL only. Starts a COPY ... FROM STDIN query and returns a stream that takes the bytes for the server, in the format that the statement names.
close() resolves when the server has stored the rows, and rejects with the server's error. abort() stores nothing. The connection runs nothing else until then, so always close or abort the stream. Bun aborts a stream that is still open when its transaction, savepoint or reservation ends.
Call it before the query starts. The query takes no parameters, and resolves with the row count in count.
await Bun.file("users.csv").stream().pipeTo(sql`COPY users FROM STDIN (FORMAT csv)`.writable());