Skip to content

sql: implement Query.cancel() for postgres - #33370

Closed
robobun wants to merge 42 commits into
mainfrom
farm/4be26dfa/postgres-query-cancel
Closed

robobun wants to merge 42 commits into
mainfrom
farm/4be26dfa/postgres-query-cancel

Conversation

@robobun

@robobun robobun commented Jul 5, 2026 •

Copy link
Copy Markdown
Collaborator

Merge #32149 first (Downsides). Open question for a maintainer: Downsides.

Problem

Fix

  • PostgresSQLConnection::open, split from createConnection, lets native code open a connection.
  • For the running query (the queue head), PostgresSQLConnection::cancel opens a second connection to the session's peer address, encrypted when the session is. It sends a CancelRequest unless the session runs another query. The query rejects with 57014.
  • A query that is not written yet, or written behind the head, rejects with ERR_POSTGRES_QUERY_CANCELLED (reject_in_flight, sql(postgres): reject only the query whose row the client cannot decode #43187).
  • Verified: test/js/sql/postgres-query-cancel.test.ts (31 tests, 29 fail without it), PostgreSQL 17.11 plain and TLS, test/js/sql/. Self-reviewed: 26 concerns raised, 21 addressed (Notes).

Background

  • A backend reads nothing while it runs a query. A CancelRequest names the backend process, so it only stops the queue head.
  • Considered a node:net socket: plaintext on a TLS session, no route to [::1], cancel key in JavaScript.

Downsides

  • Without sql: make transaction.close({ timeout }) roll back when pending queries drain before the timeout #32149, tx.close({timeout}) leaves an unhandled 57014 rejection when it cancels a running query (Notes).
  • A CancelRequest that the server handles after its query ended stops that connection's next query: 45 to 149 of 300 rounds on a loaded server, and the ROLLBACK of tx.close() in 2 of 400 (Notes). Open question: should Bun wait for the server to close the cancel connection, like libpq, pgx, pgjdbc and asyncpg?
  • Cost: 8 bytes and 2 writes per query, 32 bytes per connection. Release text: +7,424 bytes at 950a49c (Notes).
Notes

Repro

const q = sql`select pg_sleep(2)`.execute();
q.cancel();
await q; // main: resolves after 2 s, with rows. This PR: rejects with SQLSTATE 57014.

What cancel() does, by request state

do_cancel finds the connection that the query was dispatched to and calls PostgresSQLConnection::cancel. The connection owns the FIFO and the request counters, so it decides. A CancelRequest stops whatever the backend process runs now, and that is the request at the head of the FIFO.

  • Pending: no Bind, Execute or Query of the request is written. finish_request takes it out of pending_requests, the count that gates pipelining at enqueue time. on_js_error marks it Fail, and advance() discards it before it writes anything.
  • Written and the head of the FIFO (Binding, Running, PartialResponse): send_cancel_request opens the cancel connection. The backend answers the session with 57014, and the existing ErrorResponse path rejects the query. If that error arrives while the statement is still in Parsing, the statement goes back to Pending and is not failed (see below).
  • Written behind the head (pipelined): a CancelRequest would stop the query ahead of it. Each pipelined unit has its own Flush and Sync, so the backend answers it anyway. reject_in_flight rejects the promise, sets discard_response, and leaves the FIFO entry in place. The connection takes the replies of that request, rows or an error, and ReadyForQuery retires it. The error has the hint The server already received this query and still runs it. Bun discards the result., the way sql(postgres): reject only the query whose row the client cannot decode #43187 marks an undecodable row, so a caller can tell it from a query that was never sent and does not retry a write blindly.
  • No connection on the query yet (it is not dispatched, or do_run is on the stack): do_cancel marks the query, and do_run does not send it (see the next section).

reject_in_flight is main's on_undecodable_row from #43187 under a name that fits both callers.

A cancel() from the code of a parameter

The connection turns a parameter into its wire form while it encodes the Bind. An object does that with its own code (toString, toJSON), and that code can call cancel() on the query that it belongs to. main is safe from this only because cancel() does nothing there. Three changes make it safe here:

  • RequestCounter::Pending records on the request that it is in pending_requests, as Nonpipelinable and Pipelined already do for the other two counters. finish_request reads that record, so a second call does nothing. Before, advance() took the request out of the count ahead of the encode and cancel() took it out again.
  • encode_request, the one caller of the batch writers, fails the batch when the request was rejected while its parameters were converted. atomically then takes the batch out of the write buffer, so nothing of the request reaches the wire.
  • A cancel() that arrives while do_run is on the stack finds no connection on the query. do_cancel marks the query, and do_run throws ERR_POSTGRES_QUERY_CANCELLED and enqueues nothing.

Against PostgreSQL 17.11, debug builds, with a parameter whose toString() calls cancel() on its query or close() on its reserved connection:

case 950a49c now
cancel(), first run of the statement (advance() encodes the Bind) panic: pending_requests underflow rejects with ERR_POSTGRES_QUERY_CANCELLED, and the connection runs the next query
cancel(), prepared statement (do_run encodes the Bind) the cancel is lost: the query runs and resolves rejects with ERR_POSTGRES_QUERY_CANCELLED
reserved.close(), first run panic: pending_requests underflow rejects, and the process exits
reserved.close(), prepared statement the query rejects, and the process never exits rejects, and the process exits

The last row is also a hang on the released build 367d939 (killed after 60 s): do_run enqueues the query on the connection that its own parameter closed. Here reserved.close() cancels the query first, so do_run stops. A parameter that closes the connection in another way than through close() is not covered by this PR.

The cancel connection

PostgresSQLConnection::send_cancel_request runs on the session. It builds a ConnectParams and calls PostgresSQLConnection::open (see the split below), so the cancel connection is an ordinary native connection with the flag IS_CANCEL_REQUEST. It differs from a session in five places, each behind that flag:

  • send_startup_message writes the CancelRequest in place of the StartupMessage. First it asks its CancelTarget, which holds the session and the query, whether the packet can still stop the right query (see the late CancelRequest below). It reads the cancel key from the session at that time.
  • setup_tls does not call start() for it. on_handshake does. So the question above is asked when the connection can write, not when the handshake starts.
  • start does not restart the connection timer, so there is one budget from dial to hang-up. The budget is the connection timeout of the session, and at most 5 s.
  • on_data after the write fails the connection. A server answers a CancelRequest by hanging up, so a server that answers must not turn this into a session.
  • It is not counted as a postgres_connections use.

It always ends through fail. So ref_and_close closes it by main's rule for a failed connection (#44327): it sends its close_notify and FIN, and does not wait for the peer. An earlier revision of this PR had a close rule of its own for it.

The cancel key is an Option: a server that sent no BackendKeyData has none, and then cancel() on a running query does nothing. A process id of 0 is a key like any other.

What it takes from the session:

  • The target is the peer address and port of the session's socket (getpeername), or its unix socket path. A host name can resolve to another server on a second lookup. libpq's PQcancel also dials the stored address.
  • The certificate is checked against the host name of the session (tls_config.server_name), not against the dialed address. With a certificate that names only localhost, a session to localhost connected through ::1, and its cancel connection completed TLS with SNI localhost and delivered the CancelRequest. A session addressed as 127.0.0.1 was refused with that certificate.
  • sslmode is derived from what the session negotiated. A session with TLS makes a cancel connection that requires TLS, also under prefer. A session without TLS makes one with disable. The SSL_CTX is shared (SSL_CTX_up_ref) and the TLS options are copied, so SNI and certificate verification are the session's.
  • The socket group is the one of the session's socket, so the connection belongs to the same owner.

The cancel key never becomes a JavaScript value. handle.cancel() returns nothing, and the adapter has no cancel method. Measured with net.connect, net.createConnection, tls.connect, Bun.connect and net.Socket.prototype.{connect,write,end} patched before new SQL(): 0 patched calls during cancel(), and the query rejects with 57014.

An earlier revision sent the packet from the adapter on a node:net socket. On that revision postgres://postgres@[::1]:5432 connected but cancel() did nothing (select pg_sleep(3) resolved after 3019 ms), because URL parsing keeps the brackets and only the native connect strips them. On a TLS session it sent the 16 bytes in the clear.

The split of createConnection (the former #43942)

This PR was a stack of two. #43942 held the split alone, and its review is there. Its commits are in this branch unchanged (819cd9c).

call, the host function of createConnection, parses its JavaScript arguments and calls PostgresSQLConnection::open(global, group, ConnectParams). open allocates the connection, dials it and wraps it for JS. It returns the dial error of uws, and call throws it as the same exception as before. ConnectionStrings::new builds the one buffer that holds user, password, database, options and path, and the five slices into it. It is the only way to make them, so a second caller cannot pass slices that point elsewhere.

Three statements change for createConnection:

  • call looks up the socket group before open allocates the connection. It did so after the allocation. No JavaScript runs between the two.
  • call checks user, password, database and path for null bytes before it copies them into the buffer. It did so after the copy and then freed the buffer. The error is the same.
  • ConnectionStrings::new writes the terminator after each string (count_z, append_z). main reserves that byte and does not write it, so its buffer ends with 5 bytes that were never written. The allocation has the same size. The slices do not include the terminator, so the startup message has the same bytes.

Considered a second constructor for the cancel connection. It copies the 50-line struct initialiser, and the two copies drift.

Time bound

The cancel connection has one timer from its dial to its end. The budget is the connection timeout of the session, and at most 5 s.

  • A server that takes the CancelRequest and then neither answers nor hangs up: with connectionTimeout: 1 the client closes the cancel connection after 1.1 s (test the cancel connection ends when the server stays silent after the CancelRequest, debug build).
  • A server that drops the SYN of the cancel connection (a listener with a full backlog), while the session ends right after cancel(): with connectionTimeout: 1 the process exits 0.97 s after the cancel (2 runs, debug build). Since usockets: tell a socket's holder it is gone exactly once, whoever closes it and whether or not it ever opened #44327 uSockets reports the close of a socket that never opened, so this case needs no code in this PR.

A statement whose Parse is cancelled

The first run of a statement with no parameters sends Parse, Bind, Execute and Sync together, and the request is the running one. A backend that waits for a lock waits inside Parse. A cancel then gives an ErrorResponse with no ParseComplete before it. main fails the statement on every error in Parsing, and each query that shares the statement rejects with that error.

An error with SQLSTATE 57014 in Parsing now sets the statement back to Pending. The next query that shares it sends the Parse again. Against PostgreSQL 17.11, with another session holding ACCESS EXCLUSIVE on the table, two select v from t on one connection and cancel() on the first:

first query second query
before 57014 57014
now 57014 its row, when the lock is released

The rule reads the SQLSTATE only, so a statement_timeout inside Parse also stops failing the queries that share the statement.

Known limit: a CancelRequest that arrives before its query

The server ignores a cancel while it still reads the request. Bun sends the CancelRequest at once, also when bytes of the request are still in its write buffer. PostgreSQL 17.11 on loopback, release build, select pg_sleep(1), length($2) on an idle connection with a warm statement, execute() and cancel() in the same tick, 5 runs each:

size of the parameter result
64 KB 5 rejected with 57014
256 KB 5 rejected with 57014
1 MB 4 rejected, 1 lost
2 MB 2 rejected, 3 lost
4 MB 5 lost
8 MB 5 lost
8 MB, cancel() 300 ms later 5 rejected with 57014

"Lost" means that the query ran its full second and resolved. The 1 MB and 2 MB rows are a race, so their split is not a stable number. A simple query and a prepared query with a small parameter gave 20 of 20 rejected, on the debug and on the release build.

This PR does not fix it. A wait for the write buffer to drain is wrong: the buffer also holds the bytes of pipelined queries behind the head, and the server does not read those while it runs the head. A fix has to record when the bytes of one request have left the buffer, at every place that writes a request.

A late CancelRequest, and the open question

A CancelRequest names the backend process. The server acts on it after the postmaster has accepted the cancel connection and started a process for it. If the query has ended by then, the signal stops the query that the backend runs at that moment. A signal that meets an idle backend does nothing. Bun cannot take the packet back after the write.

The numbers in this section are from release builds of 950a49c and earlier revisions, as named. The code of this path has not changed since.

What this PR does. The cancel connection holds the session and the query (CancelTarget). When it can write, which on a TLS connection is the end of the handshake, it asks the session. It writes the packet unless the session is still connected and its backend no longer runs that query. In that case it hangs up and sends nothing. A session that closed gets the packet (see the next section).

What this PR does not do. The session writes its next request as soon as the backend is ready, also while a cancel connection is open. The open question at the end of this section is about that.

The size of the window on this machine. PostgreSQL 17.11 on loopback, release builds, 16 cores, load average 450 to 550 from other work. A raw protocol client on node:net, with no use of Bun.SQL, 200 cancels of a running pg_sleep(5), 2 runs:

step median p90 max
dial of the cancel connection 0.4 ms 0.6 ms 109 ms
from the dial until the ErrorResponse on the session 54 ms, 52 ms 248 ms, 216 ms 668 ms, 416 ms
from the dial until the server closes the cancel connection 132 ms, 117 ms 347 ms, 292 ms 759 ms, 689 ms
for comparison: pg_cancel_backend() on a second session, until the ErrorResponse 0.45 ms 0.5 ms 22 ms
for comparison: a new session, until ReadyForQuery 18 ms 265 ms 1449 ms

cancel() of this PR in the same measurement: a median of 46 to 95 ms in 5 runs, and 1.7 ms in the best case. So the time is the server's. It goes into the new connection and not into the signal. A server without this load has a smaller window.

How often the wrong query is stopped. A loop of 300 rounds per run on a pool of 1: A = select 1, A.cancel() in the same tick, await A, then B = select pg_sleep(0.01). The number is how often B, which nobody cancelled, rejected with 57014:

client B rejected, of 300
main e70cca7, where cancel() does nothing 0
358721d, before the check at write time 46, 181, 165
this PR, 950a49c 94, 148, 149, 45
raw protocol client, B written when A has ended 62, 57, 103
raw protocol client, B written when the server has closed the cancel connection 0, 0, 0

With B already queued behind A (select pg_sleep(0.03), simple protocol), 300 rounds per run:

first query 358721d 950a49c
select 1, cancel() in the same tick 129, 300, 296 68 to 287 in 13 runs
pg_sleep(0.002), cancel() in the same tick 149, 87, 44 62, 22, 88
pg_sleep(0.005), cancel() 3 ms later 155, 63, 78 56, 78, 80

What the numbers say:

  • The check at write time changes nothing that these loops can show. The dial takes 0.4 ms, so the packet is nearly always written while A runs. The server then needs tens of milliseconds, and A has ended. On the debug build, which is slower than the server, the check cut the first row of the second table from 115 and 110 to 15, 10 and 12.
  • The check decides the case of a slow dial. PostgreSQL 17.11 with ssl = on, a TCP hop that holds the TLS ClientHello of the cancel connection for 300 ms, A = pg_sleep(0.15), B = pg_sleep(1) behind it, cancel() on A after 30 ms. On c55aa7a, which asked the session before the handshake, A resolved and B rejected with 57014. On 950a49c both resolve. With A = pg_sleep(3), A rejects with 57014 and B resolves, on both builds.
  • The loops cancel faster than this server accepts connections. Without the wait, the raw client had up to 236 cancel connections open at once, and they lived for a median of 2.2 to 4.7 s. With this PR the accept queue of the server reached 85 to 201 entries, and its limit is 200. 4 of 17 runs of the first row of the second table then failed at their first connect with ERR_POSTGRES_CONNECTION_TIMEOUT after 5 s, behind the cancel connections of the run before. 40 connects with no cancel before them took 7 to 21 ms.
  • With the wait, the raw client never had more than 1 cancel connection open. B started later by a median of 92, 80 and 5 ms in the three runs (p99 0.8 to 2.8 s).

tx.close(). It calls cancel() on the queries of the transaction and then sends ROLLBACK on the same connection, with nothing between the two. 200 rounds each of sql.begin(async tx => { tx.unsafe("select pg_sleep(...)").execute(); await tx.close(); }) with a query of 20 ms and of 5 ms, debug build of a46f129, PostgreSQL 17.11: in 1 round of each 200 the CancelRequest stopped the ROLLBACK, and tx.close() rejected with 57014. sql.begin then sent COMMIT, the server answered it with the ROLLBACK tag because the transaction was aborted, and the next query on the connection ran in all 400 rounds. On the released build 367d939, where cancel() does nothing, tx.close() resolved in 100 of 100 rounds.

What other clients do, as read in their sources:

  • libpq PQcancel (fe-cancel.c), pgx PgConn.CancelRequest (pgconn/pgconn.go) and pgjdbc QueryExecutorBase.sendQueryCancel write the packet and then read until the server closes the connection. Only then does the caller continue. The comment in libpq: "Without this delay, we might issue another command only to find that our cancel zaps that command instead of the one we thought we were canceling."
  • asyncpg keeps a connection out of its pool while a cancel for it is in progress (PoolConnectionHolder.release in asyncpg/pool.py waits for it), and it ends a connection whose CancelRequest failed.
  • node-postgres Client.cancel and postgres.js cancel write the packet and do not hold the session. postgres.js returns a promise that settles when the cancel connection closes. Its README says that the race can cancel another query, and that this is fine for long queries.
  • On Bun.SQL: add ability to cancel query using AbortSignal #23175 the maintainer of Bun.SQL names this hazard ("other queries that are also executing in the same connection could also be canceled"), points to the postgres.js way, and says that he wants to look for a better solution.

The open question. Should a session write no new request while one of its cancel connections is open?

  • For: a cancel for one query then never stops a request that was not yet written. That includes the ROLLBACK of tx.close(). A session has at most 1 cancel connection open, so cancels cannot queue up at the server.
  • Against: each cancel() of a running query delays the next request of that connection until the server has closed the cancel connection. On this machine that was a median of 5 to 92 ms. The limit is the budget of the cancel connection: the connection timeout of the session, and at most 5 s. A request that is already written behind the head cannot be held back and stays exposed.
  • This PR does not build it. It changes when a session sends, so a maintainer should decide it first. It needs a count of open cancel connections on the session, a test of that count in advance() and in the writes at enqueue time, and a release on every end of the cancel connection.

A session that closes while its cancel connection dials

reserved.close() calls cancel() on each query of the reserved connection and then closes the connection. The backend still runs the query, so the CancelRequest has to go out after the session is gone. The CancelTarget holds the session itself. A session that is not connected any more always gets the packet: no other query of this client can follow on it.

A reserved connection runs pg_sleep(6), then reserved.close(). Time until pg_stat_activity shows that the backend stopped the query, release builds, 2 runs each:

build the backend stops after
main e70cca7 5987 ms, 6041 ms (the query runs to its end)
358721d, before the check at write time 160 ms, 131 ms
c55aa7a, which asked through the query 5994 ms, 6069 ms
950a49c 125 ms, 110 ms

c55aa7a reached the session through the link from the query to its connection. The close clears that link, so it found no session and sent nothing. 100 rounds of reserve, query and close on the debug build of 950a49c: 0 backends left in pg_sleep, connections 3 to 3, open file descriptors 11 to 11.

Known limit: cancel while only the Parse is on the wire

The first run of a statement with parameters writes Parse, Describe and Sync and waits for the parameter types before it writes Bind and Execute. The request is Pending in that window. cancel() rejects it locally and sends no CancelRequest: Parse normally ends within one round trip, so a cancel would mostly arrive late and stop the next query on that backend. A backend that is blocked inside Parse (a lock wait) stays blocked until the lock clears, as on main. The connection serves the next request as soon as the backend answers.

Known limit: a link-local IPv6 peer

us_socket_remote_address returns the peer address without its scope. For a session to fe80::1%eth0 the cancel connection dials fe80::1, which does not reach the peer, and cancel() does nothing, as on main. Not tested: the machine has no link-local address.

A query that is cancelled before it runs

Not in this PR. #41492 makes that change in query.ts for every adapter, with its tests. Until it merges, a query that is cancelled before it was started never settles, as on main. An earlier revision of this PR carried the same query.ts hunk. query.ts is main's again.

close() and close({ timeout }) with a running query

close({ timeout }) in src/js/bun/sql.ts waits on the queries in its scope with Promise.all(...).finally(...). A query that rejects during the wait leaves a rejected promise with no handler. On main that needs a query that fails by itself. With this PR the cancel() that the timeout calls makes a running query reject. #32149 handles that rejection for a transaction.

Against PostgreSQL 17.11, max: 1, a running pg_sleep(3) whose own promise has a handler. The first column is the released build 367d939, the second is the debug build of a46f129:

case without this PR this PR
reserved, close({ timeout: 0.3 }) query rejects with ERR_POSTGRES_CONNECTION_CLOSED, 1 unhandled rejection the same
reserved, close() query rejects with ERR_POSTGRES_CONNECTION_CLOSED, 0 unhandled the same, and the backend stops the query
transaction, close({ timeout: 0.3 }) cancel() does nothing, close waits 3 s for the query, 0 unhandled query rejects with 57014, 1 unhandled rejection
transaction, close() the query runs its 3 s and resolves, sql.begin rejects with ERR_POSTGRES_CONNECTION_CLOSED the query rejects with 57014, sql.begin rejects the same way

In all 8 runs the pool ran its next query. The third row is the reason for the first line of this description. On an earlier revision of this branch, with the sql.ts diff of #32149 applied, that case had no unhandled rejection and rolled back.

tx.close() cancels every query in the scope of the transaction, and the SAVEPOINT, RELEASE and ROLLBACK TO statements are in that scope too (run_internal_transaction_sql). One that waits behind a running query is rejected and never sent. One that the backend runs gets a CancelRequest. On main they ran to their end.

GC edge

do_cancel needs the connection, so the query wrapper caches the connection it was dispatched to. That slot is a strong edge. allow_gc, reject and on_write_fail clear it, so a settled Query that user code keeps does not pin the connection. The test a settled query does not keep its connection alive holds 40 settled queries of 10 pools. Without the clear in reject it finds 11 connections alive after GC.

A cancel connection holds a reference to its session and to the query (CancelTarget) from cancel() until it writes the packet or fails. send_startup_message and fail_with_js_value drop it. The longest hold is the budget of the cancel connection.

Merges with main

  • A dead-code sweep on main emptied BackendKeyData and removed the field on PostgresSQLConnection. This PR restores process_id, secret_key and the field, because cancel_request() needs them.
  • wire-frames.ts: main has the Parse, Bind and ParameterDescription helpers. This PR adds only pgCancelRequest and pgBackendKeyData.
  • main faac63e has usockets: tell a socket's holder it is gone exactly once, whoever closes it and whether or not it ever opened #44327: uSockets tells the holder of a socket that never opened when that socket closes. An earlier revision of this PR released the event loop for that case in ref_and_close, and had a session test for it. Both are gone: the merge takes main's ref_and_close, and main has the test.

Open PRs that touch the same code

Checked with git merge-tree against a46f129, which contains main faac63e. Each conflict is for the PR that lands second.

Tests

The server is a scripted wire server. The tests assert the exact CancelRequest bytes, and assert that none are sent where none may be sent. That needs a server that answers on demand. The last test is the exception: it runs against a real PostgreSQL server (describeWithContainer), which is the judge of the bytes.

In postgres-query-cancel.test.ts, 31 tests:

  • The running query: cancel() on an extended and on a simple query sends Int32(16) Int32(80877102) Int32(pid) Int32(secret) on a second connection and rejects with 57014 (2). It reaches a server at an IPv6 literal and on a unix socket (2).
  • TLS: on a session under verify-full, verify-ca, require and prefer, both connections send only the 8-byte SSLRequest in the clear, and the CancelRequest arrives inside TLS (4). A cancel connection that is told N sends nothing, under prefer and under require (2). One that meets a certificate the session's CA did not sign sends nothing (1). The certificate is checked against the host name of the session (1).
  • The end of the cancel connection: it closes when the server answers it like a session (1), and when the server stays silent after the packet (1). The process exits when its dial never completes (1, not on Windows and musl: the fixture loads glibc or libSystem for a raw listener).
  • The cancel key: no connection is opened when the server sent no BackendKeyData (1). A process id of 0 is sent like any other (1).
  • The query ended or the session closed during the dial: nothing is sent when the query ended, with the server holding its answer to the SSLRequest or holding the TLS handshake (2). The packet is still sent when the session closed (1).
  • The statement: a cancel during Parse does not fail the queries that share the statement (1). A cancel while only the Parse of the query is on the wire rejects it at once, and the statement is prepared for the next run (1).
  • Not the head: a queued query is rejected with no hint and the running one keeps its rows (1). The connection still pipelines afterwards (1). A pipelined query is rejected with the hint, and both replies are consumed (1). A pipelined query that the server answers with an error leaves the connection in sync (1). The queries that are pipelined behind a cancelled head get their rows (1).
  • The code of a parameter calls cancel(): the query rejects and no Bind of it reaches the server, for a first run, for a prepared statement, and with prepare: false (2).
  • GC: a settled query does not keep its connection alive (1).
  • A real server: cancel() stops a running pg_sleep, seen in pg_stat_activity, and the connection runs the next query (1).

On the released build 367d939, 29 of the 31 tests fail. The other 2 pass there because that build opens no cancel connection: the one for a server with no cancel key, and the one for the dial that never completes. The scenario of the first test for the code of a parameter stops the debug build of 950a49c with panic: pending_requests underflow. With this PR all 31 pass on the debug build (3570e33).

End to end, PostgreSQL 17.11

Debug build of a46f129. The head cancel is pg_sleep(5), cancelled after 300 ms. The times are the server's under a load average of 800:

[::1] head cancel:      rejected:57014 after 220 ms | next: 42
127.0.0.1 head cancel:  rejected:57014 after 1826 ms | next: 42
localhost head cancel:  rejected:57014 after 711 ms | next: 42
pipelined: b = rejected:ERR_POSTGRES_QUERY_CANCELLED (hint) | a = resolved:[{"x":1,"pg_sleep":""}]
queued: rejected:ERR_POSTGRES_QUERY_CANCELLED | running: kept

Release build of 950a49c, the same server with ssl = on and a certificate for localhost. ssl and the version are what pg_stat_ssl has for the session:

verify-full, localhost: session ssl=true TLSv1.3 | cancel -> 57014 after 54 ms | next query -> 42
require, 127.0.0.1:     session ssl=true TLSv1.3 | cancel -> 57014 after 312 ms | next query -> 42
require, [::1]:         session ssl=true TLSv1.3 | cancel -> 57014 after 493 ms | next query -> 42

Cost

For a query that is never cancelled: one cached slot on the query wrapper (8 bytes), written at dispatch and cleared when the query settles. There is no new allocation, syscall, promise or host function per query. encode_request reads the status of the request once per Bind. size_of::<PostgresSQLQuery>() is 64 bytes. This PR adds no field to it.

what number
release linux-x64 text 80,668,872 on main e70cca7, 80,676,296 on 950a49c (+7,424). Not measured for the commits after it: a release build did not finish on the machine, which had a load average above 1000
release linux-x64 data and bss 110,424 and 1,822,992 on both of those builds
size_of::<PostgresSQLConnection>() 672 bytes on main, 704 bytes here: 12 for the cancel key, 16 for the CancelTarget of a cancel connection, and padding
host functions of the postgres binding 3, unchanged
runtime hooks (SqlRuntimeHooks) +1 (ssl_config_clone)
per cancel() of a running query one connection to the server, one PostgresSQLConnection, and on a TLS session a copy of the TLS options
after 1000 head cancels against PostgreSQL 17.11 and a full GC (950a49c) PostgresSQLConnection objects 2 to 2, PostgresSQLQuery 2 to 2, open file descriptors 10 to 10
patched net/tls/Bun.connect calls during one cancel() 0

Not measured: instructions per query and syscalls per cancel. valgrind, perf and strace are not on the machine and cannot be installed there.

MySQL

MySQL cancel() is unchanged: it sends nothing and rejects nothing (JSMySQLQuery::do_cancel is a stub). The docs and the JSDoc of cancel() describe PostgreSQL only, and make no claim for the other adapters.

Other suites

All of test/js/sql/ on a46f129 with the debug build and a 30 s test timeout: 957 pass, 2 skip, 47 fail. 46 failures are MySQL tests that get Access denied for user 'root'@'localhost' from the local MariaDB. The other one is json/jsonb bind parameter does not leak the stringified payload, which timed out at 30 s under a load average of 800. Alone it passes in 10 s, 2 of 2 runs. rustfmt and prettier are clean. The two commits after 3570e33 change two comments and the cleanup of one test. They ran in CI only: the machine lost its build.

Self-review

A review of 950a49c raised 26 concerns. 21 are addressed in a46f129 and the commits after it:

Not changed, with the reason:

  • An explicit type for the wire position of a request in place of status. It would rewrite the state machine of advance() on main. The decision is now one match in the connection, and the three counters are recorded on the request.
  • tx.close() cancels control statements and sends ROLLBACK right behind a cancel. Measured above. The fix is the hold of the open question.
  • A pipelined query that cancel() rejects gives its pool slot back while the server still runs it, so the pool can hand that connection to the next caller, who then waits. main has the same for an undecodable row (sql(postgres): reject only the query whose row the client cannot decode #43187).
  • The cancel connection ends through fail, also after a delivery, and builds an error that nobody reads. It is one object per cancel.
  • The cancel connection copies the TLS options of the session. It is one copy per cancel.

Alternatives that were built or weighed

  • Document the plaintext node:net socket and change nothing. cancel() stays a no-op for [::1] and for servers that only accept TLS.
  • Add node:tls to the JS socket. The adapter then has a second copy of the sslmode rules that the native connection implements.
  • Pass the packet from JS to createConnection as an extra argument. This was built and measured first (11 tests passed). The cancel key is a JS value on the way, the host name is resolved a second time, and a TLS socket stayed open when the peer went silent.
  • Open the connection from the session in native code. This is what the PR does.

no test proof · iteration 7 · platform-specific test(s) that do not run on this machine, deferring to CI, which covers all platforms: test/js/sql/postgres-query-cancel.test.ts

The native cancel hook was an empty stub, so cancel() never wrote
anything: an in-flight query ran to completion and resolved with its
rows, and a query cancelled before it was dispatched never settled.

A backend running a query reads nothing from its connection until the
query finishes, so cancel() now opens a second connection and sends a
CancelRequest built from the BackendKeyData the server already handed
out. The backend answers the original connection with SQLSTATE 57014,
which rejects the query through the existing ErrorResponse path.

A query that is queued on a connection but whose bytes are not on the
wire is failed locally instead: a CancelRequest there would stop
whatever the backend is actually running. A query that was never
dispatched is rejected with ERR_POSTGRES_QUERY_CANCELLED.
@robobun
robobun requested a review from alii as a code owner July 5, 2026 10:35
@coderabbitai

coderabbitai Bot commented Jul 5, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Repository: oven-sh/bun/.coderabbit.yaml

Review profile: ASSERTIVE

Plan: Essentials

Run ID: 3a792dcb-8c8c-4fe5-9300-6ff713b5d69e

📥 Commits

Reviewing files that changed from the base of the PR and between 74fb430 and 3b664c6.

📒 Files selected for processing (11)
  • docs/runtime/sql.mdx
  • packages/bun-types/sql.d.ts
  • src/runtime/hw_exports.rs
  • src/sql/postgres/protocol/ErrorResponse.rs
  • src/sql/shared/ConnectionFlags.rs
  • src/sql_jsc/jsc.rs
  • src/sql_jsc/postgres/PostgresSQLConnection.rs
  • src/sql_jsc/postgres/PostgresSQLQuery.rs
  • test/js/sql/postgres-pending-dial-fixture.ts
  • test/js/sql/postgres-query-cancel.test.ts
  • test/js/sql/sql-connect-error-reporting.test.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 5 remain after this review.


Walkthrough

The change adds PostgreSQL query cancellation through a separate connection that sends a CancelRequest. It updates query lifecycle handling, records PostgreSQL backend key data, adds cancellation tests, and expands the SQL cancellation documentation.

Changes

PostgreSQL cancellation flow

Layer / File(s) Summary
Cancellation protocol and runtime support
src/sql/postgres/protocol/BackendKeyData.rs, src/sql/postgres/protocol/ErrorResponse.rs, src/sql/postgres/AnyPostgresError.rs, src/sql/shared/ConnectionFlags.rs, src/sql_jsc/postgres/error_jsc.rs, src/sql_jsc/jsc.rs, src/runtime/hw_exports.rs
Backend key data is retained and encoded for CancelRequest packets. Error handling recognizes SQLSTATE 57014 and maps query cancellation to ERR_POSTGRES_QUERY_CANCELLED. Runtime hooks clone SSLConfig.
CancelRequest connection lifecycle
src/sql_jsc/postgres/PostgresSQLConnection.rs
PostgreSQL connections retain backend key data and can open a separate connection to send a CancelRequest. The cancel connection uses the session’s address and TLS state and has distinct timeout and close handling.
Query cancellation handling
src/js/internal/sql/query.ts, src/runtime/api/sql.classes.ts, src/sql_jsc/jsc.rs, src/sql_jsc/postgres/PostgresSQLQuery.rs
Query handles can return a cancellation payload for adapter delivery. PostgreSQL queries cache their connection and handle cancellation differently for pending, current, and queued in-flight requests.
Cancellation tests and documentation
test/js/sql/postgres-query-cancel.test.ts, test/js/sql/postgres-pending-dial-fixture.ts, test/js/sql/sql-connect-error-reporting.test.ts, test/js/sql/wire-frames.ts, docs/runtime/sql.mdx, packages/bun-types/sql.d.ts
Tests cover query states, protocols, TLS settings, connection types, and pending dials. The documentation describes cancellation outcomes and errors.

Suggested reviewers: jarred-sumner

Priority: ➖ Normal

Merge Risk: ⚪ Minimal · up to 3b664

PostgreSQL Query.cancel() now sends a best-effort CancelRequest over a separate connection. That connection uses the same TLS protection as the session, so cancellation credentials are no longer sent in plaintext. The documentation explains the best-effort limits, including that a late cancel can affect the next query. No outstanding issues block merging.

🚥 Pre-merge checks | ✅ 4
✅ Passed checks (4 passed)
Check name Status Explanation
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Title check ✅ Passed The title clearly and concisely identifies the main change: implementing PostgreSQL support for Query.cancel().
Description check ✅ Passed The description explains the problem, implementation, behavior, limitations, and verification. It does not use the template headings, but it provides the required information in detail.

Comment @coderabbitai help to get the list of available commands.

@github-actions github-actions Bot added the claude label Jul 5, 2026
@robobun

robobun commented Jul 5, 2026 •

Copy link
Copy Markdown
Collaborator Author
Updated 7:14 PM PT - Oct 2nd, 2026

❌ @robobun, your commit 52e8500 has 2 failures in Build #123045 (All Failures):


🧪   To try this PR locally:

bunx bun-pr 33370

That installs a local version of the PR into your bun-33370 executable, so you can run:

bun-33370 --bun

@github-actions

github-actions Bot commented Jul 5, 2026

Copy link
Copy Markdown
Contributor

Found 1 issue this PR may fix:

  1. Bun.SQL: add ability to cancel query using AbortSignal #23175 - This PR implements the underlying Query.cancel() mechanism that this feature request depends on; the issue's "alternatives considered" sample even shows query.cancel()

If this is helpful, copy the block below into the PR description to auto-close this issue on merge.

Fixes #23175

🤖 Generated with Claude Code

@robobun

robobun commented Jul 5, 2026

Copy link
Copy Markdown
Collaborator Author

Not adding Fixes #23175. That issue asks for .timeout(ms) / .signal(AbortSignal) on a query, and this PR adds neither.

What it does change for that issue is the workaround its author already wrote under "alternatives considered":

const query = sql`SELECT pg_sleep(100)`;
request.signal.addEventListener("abort", () => query.cancel());
const result = await query.execute();

On main that cancel() is a no-op for Postgres, so the query runs to completion anyway. With this PR it actually stops the query on the server. A real .signal() / .timeout() API can then be built on top, so #23175 stays open.

Comment thread packages/bun-types/sql.d.ts Resolved
…running

A CancelRequest names the backend process, not a statement, so it stops
whatever that backend is executing: the request at the head of the
connection's FIFO. do_run()'s Prepared arm writes a query's Bind/Execute
as soon as can_pipeline() allows, which happens while an earlier query is
still running, so cancelling the pipelined query sent a CancelRequest
that killed the query ahead of it instead.

Check that the request is the head of the FIFO before asking the server
to stop it. A request behind the head is settled locally, but the two
cases differ: a Pending request has nothing on the wire and is failed, so
advance() discards it instead of writing it, while a pipelined request is
already on the socket and the backend will answer it no matter what, so
its promise is rejected in place and the FIFO entry stays to consume those
answers in order. Marking it failed would make advance() discard it and
the next BindComplete would land on the wrong request.
@robobun

robobun commented Jul 5, 2026

Copy link
Copy Markdown
Collaborator Author

CI status

The one hard failure on both builds so far is infrastructure, not this diff.

:darwin: 26 aarch64 - test-bun exits before running a single test:

2026-07-05 05:02:19 INFO   Searching for artifacts: "**" within step: "darwin-aarch64-build-bun"
2026-07-05 05:02:19 INFO   Found 2 artifacts. Starting to download to: .../bun/bun/release

Error: buildkite-agent artifact download timed out after 120s for step 'darwin-aarch64-build-bun'.
Refusing to continue with a partial download (would silently fall back to the wrong binary).
    at getExecPathFromBuildKite (scripts/runner.node.mjs:2182:13)

Why it is not this change:

  • The step it is downloading from, darwin-aarch64-build-bun, passed. So did every other build lane (darwin/linux/windows/freebsd x cpp/rust/bun), plus Format, Lint JavaScript, TypeScript types and cargo clippy.
  • The lane dies inside buildkite-agent artifact download, before runTests ever starts. No test of any kind ran on it.
  • It reproduced identically on two independent builds: #68532 (acec2d8) and #68546 (d920eab), same lane, same 120s timeout. The second build was a fresh push, so it was already effectively a re-roll.
  • This diff touches the Postgres wire protocol, src/js/internal/sql/* and a cached value on the query handle. None of that can affect a macOS artifact download.

The only other annotation on each build is a different test that CI itself tags flaky and retries (bun-install.test.ts on #68532, bake/dev-and-prod.test.ts on #68546). Neither touches SQL.

I have not pushed a ci: retrigger commit: a new push cancels the in-flight build, and #68546 still has ~235 jobs pending, including the shards that run test/js/sql/postgres-query-cancel.test.ts. Losing that signal to chase a green checkmark seemed like the wrong trade, especially since the previous push already demonstrated a re-roll does not clear this.

If someone with write access could re-run just the darwin 26 aarch64 - test-bun job, that should be enough. Happy to push a retrigger instead if that is preferred.

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Both prior concerns are addressed (the head-of-FIFO check + reject_in_place for pipelined queries, and the generalized JSDoc), and I found nothing new — deferring only because this touches native SQL/wire-protocol code and warrants a human look.

Extended reasoning...

Overview

Implements Query.cancel() for Postgres end to end: encodes the CancelRequest packet from stored BackendKeyData, opens a second plaintext connection via Bun.connect to deliver it, and settles never-dispatched queries locally. Touches 14 files across the shared JS query layer, the Postgres adapter, native Rust (PostgresSQLQuery, PostgresSQLConnection, BackendKeyData), the .classes.ts codegen input (adds a connection cached-value slot on the Postgres query wrapper), types/docs, and a new hermetic wire-server test suite.

Prior feedback

I previously flagged (🔴) that a pipelined Status::Binding query behind the FIFO head would cancel the wrong query, and (🟡) that the shared SQL.Query.cancel() JSDoc described only Postgres. Both are fixed in this revision: do_cancel() now checks is_current_request() and routes non-head on-wire requests through the new reject_in_place() (which leaves the FIFO entry so the backend's replies are still consumed in order), a pipelined-query test was added, and the JSDoc was generalized. Nothing outstanding.

Security risks

Low. The CancelRequest carries only the pid/secret the server itself issued in BackendKeyData; no credentials cross the plaintext side-connection (matches libpq's PQcancel). connectionInfo.hostname/port/path come from the user's own SQL config, not attacker input.

Level of scrutiny

High. This is production database code: it changes user-visible semantics (a former no-op now aborts server-side queries), adds a GC-visited JS value slot on a native class, and introduces reject_in_place() whose correctness depends on FIFO-ordering invariants and on Query.resolve() being a no-op on an already-rejected promise. The pipelined case in particular is subtle enough that a maintainer familiar with advance() / the request FIFO should confirm the desync reasoning.

Other factors

Test coverage is good and hermetic (scripted wire server asserting exact bytes and connection counts, plus the new pipelined variant). Not approving solely on scope/complexity — the change looks correct to me.

@robobun

robobun commented Jul 5, 2026

Copy link
Copy Markdown
Collaborator Author

Thanks. Since the one thing you flagged for a human is the advance() / FIFO desync reasoning behind reject_in_place(), here it is laid out so it can be checked against the code rather than taken on trust.

Why a pipelined request cannot just be marked Fail

bind_and_execute() ends every request with Flush + Sync (PostgresRequest.rs), so each pipelined query is its own sync point and the backend answers it even if the one ahead of it errored. Concretely, with a at the head and b pipelined behind it:

  1. b.cancel() marks b as Fail.
  2. a finishes. ReadyForQuery calls advance().
  3. advance()'s defer_cleanup! pops Success/Fail entries off the head, so it pops a, then sees b is Fail and pops b too. The FIFO is now empty.
  4. b's replies arrive anyway. MessageType::BindComplete does self.current().ok_or(AnyPostgresError::ExpectedRequest)?, current() is None, and the whole pooled connection fails.

What reject_in_place() does instead

It rejects the promise and touches nothing the connection still needs: status stays Binding, target stays set, and this_value stays strong. So:

  • advance() sees a non-terminal status at the head and leaves the entry alone (the Running | Binding | PartialResponse arm just advances offset), so b's replies still land on b.
  • b then finishes down the ordinary path. on_result(is_last = true) fires on_query_resolve_fn, which reaches Query.resolve(), which calls this[_resolve](x) on an already rejected promise: a no-op per the promise spec. The same path runs allow_gc() + downgrade(), so there is no new GC state to reason about and no early downgrade.

This is also why it does not reuse on_js_error(): that one sets Status::Fail, clears target, and downgrades this_value, which is exactly right for a Pending request (nothing on the wire, so advance() should discard it instead of writing it) and exactly wrong for a pipelined one.

The new test covers the desync directly: it cancels the pipelined query, feeds both queries' replies, and then runs one more query, which only succeeds if the FIFO and the protocol stayed in sync.

CI

test/js/sql/postgres-query-cancel.test.ts is now green on every platform that ran it in #68546, 5 pass / 0 fail each:

Linux x64 debian 13, ubuntu 25.04, x64-baseline, x64-asan
Linux aarch64 debian 13, ubuntu 25.04
musl alpine 3.23 x64, x64-baseline, aarch64
Windows 2019 x64, 11 aarch64

The two red lanes are unrelated:

  • darwin 26 aarch64 - test-bun dies in buildkite-agent artifact download with a 120s timeout before runTests starts, so it never ran a test. Reproduced identically on #68532 and #68546.
  • windows 2019 x64-baseline - test-bun fails napi > napi_wrap > has the right lifetime with Condition was not met after 100 GC attempts, a GC-timing assertion in a suite that never constructs a SQL object. The other annotation on that lane, bake/dev-and-prod.test.ts, CI already tags flaky and retries.

@robobun

robobun commented Jul 5, 2026

Copy link
Copy Markdown
Collaborator Author

CI: final state

#68546 has settled at 282 passed, 2 failed. Neither failure is this diff, and I have not pushed a ci: retrigger because a rebuild would not clear either one.

1. darwin 26 aarch64 - test-bun exits inside buildkite-agent artifact download with a 120s timeout, before runTests starts, so it never runs a test. The step it downloads from, darwin-aarch64-build-bun, passed.

Both builds that hit this ran on the same agent:

build sha agent hostname
#68532 acec2d8d darwin-aarch64-26.5.1-1 bingus
#68546 d920eaba darwin-aarch64-26.5.1-1 bingus

So this looks like one macOS agent that cannot pull artifacts, rather than a transient blip. A fresh build would most likely be scheduled straight back onto it, which is why I would rather not burn a full 287-job rebuild on it. Re-running just that job (once bingus is healthy) should be enough.

2. windows 2019 x64-baseline - test-bun fails napi > napi_wrap > has the right lifetime with Condition was not met after 100 GC attempts. That is a GC-timing assertion in a suite that never constructs a SQL object. The lane's other annotation, bake/dev-and-prod.test.ts, CI already tags flaky and retried.

This diff is green. test/js/sql/postgres-query-cancel.test.ts ran 5 pass / 0 fail on every platform that reached it:

Linux x64 debian 13, ubuntu 25.04, x64-baseline, x64-asan
Linux aarch64 debian 13, ubuntu 25.04
musl alpine 3.23 x64, x64-baseline, aarch64
Windows 2019 x64, 11 aarch64

Happy to push a retrigger if you would rather roll the dice on it, but my read is that a one-job re-run is the cheaper move.

The `connection` cached value a query keeps so that cancel() can reach the
connection it ran on is a strong GC edge. `allow_gc` clears it for a request
that completed, but `on_js_error` and `on_write_fail` did not, so holding a
settled Query kept its whole connection reachable: socket buffers, the
prepared-statement map and all.

Clear it on the failure paths too, through one helper shared with `allow_gc`
so the next slot added here has an obvious place to be released. `do_cancel`
reads the value before it hands off to `on_js_error`, so nothing loses its
connection early.
@robobun

robobun commented Jul 5, 2026

Copy link
Copy Markdown
Collaborator Author

Pushed 771c008, a small follow-up that tightens the lifetime of the connection cached value this PR adds to the query handle.

That slot is a strong GC edge from the query's JS wrapper to the connection's. allow_gc() clears it for a request that completed, but on_js_error() and on_write_fail() did not, so holding on to a settled (rejected) Query kept the whole connection reachable: socket buffers, the prepared-statement map, all of it. All three sites now go through one release_connection() helper, so the next cached value added here has an obvious place to be released. do_cancel() reads the slot before it hands off to on_js_error(), so nothing loses its connection early.

Being straight about the evidence: I could not make this show up as an observable leak, because a PostgresSQLConnection already survives sql.close() plus a forced GC even when no query was ever created, so heapStats() cannot see the incremental edge. The fix is on the strength of the asymmetry (success path clears it, failure paths did not) rather than a reproduction, which is why it is hygiene rather than a behavior change and ships with no new test.

The five cancel tests still pass, the full test/js/sql/ run is unchanged (586 pass, same 29 pre-existing failures from MariaDB root auth and two debug+ASAN-slow sqlite fuzz tests), and both end-to-end checks against PostgreSQL 17 still behave: the head query dies with 57014 sub-second, and a cancelled pipelined query rejects while its neighbour runs its full pg_sleep(30).

This push also starts a fresh build, which re-rolls the two unrelated red lanes from #68546 (the bingus artifact-download timeout and the napi GC flake) without me spending a throwaway retrigger commit on them.

@robobun

robobun commented Jul 5, 2026

Copy link
Copy Markdown
Collaborator Author

CI: three distinct failures, none from this diff

#68564 (771c008) is red on three things. I looked at each rather than assuming, and none of them is reachable from what this PR changes. I have still not pushed a ci: retrigger, because it cannot fix the main one.

1. darwin 26 aarch64 - test-bun — a single sick agent.

Error: buildkite-agent artifact download timed out after 120s for step 'darwin-aarch64-build-bun'.
Refusing to continue with a partial download (would silently fall back to the wrong binary).

It exits before runTests starts, so it never runs a test, and the step it downloads from (darwin-aarch64-build-bun) passed. All three builds that hit it ran on the same agent:

build sha agent hostname
#68532 acec2d8d darwin-aarch64-26.5.1-1 bingus
#68546 d920eaba darwin-aarch64-26.5.1-1 bingus
#68564 771c008 darwin-aarch64-26.5.1-1 bingus

Three for three on bingus. A rebuild gets scheduled straight back onto it, which is exactly why I have not burned a retrigger: it would be a fourth identical failure plus a junk commit. Re-running that one job (or taking bingus out) is the fix.

2. debian 13 x64-asan - test-bun, 1 shard of ~20 — a JSC termination race.

test/js/node/test/parallel/test-worker-message-port-transfer-terminate.js - SIGABRT
ASSERTION FAILED: !scope.exception() || !hasSlot
JSCJSValuePropertyInlines.h(51) : JSValue JSC::JSValue::get(JSGlobalObject *, PropertyName, PropertySlot &)

A property get running with a pending exception, in a test that terminates a worker mid message-port transfer. I did not wave this one off:

  • It ran 0/30 aborts locally under the same debug+ASAN build.
  • Build #68546 completed with two of this PR's three commits and that test passed there. The only delta into #68564 is 771c008, ten lines that clear a cached GC slot on PostgresSQLQuery's failure paths.
  • The test never constructs a SQL object and never requires internal/sql/*, so neither the new cached value nor the protocol code is reachable from it.
  • The other 19 asan shards passed.

For what it is worth, !scope.exception() || !hasSlot firing during worker termination has the shape of a missing exception check in the termination path. Probably worth its own look, but it is not this PR.

3. test/bake/dev-and-prod.test.ts is annotated flaky by CI itself and retried.

This diff is green

From #68546, the build that ran to completion, test/js/sql/postgres-query-cancel.test.ts was 5 pass / 0 fail on every platform that reached it:

Linux x64 debian 13, ubuntu 25.04, x64-baseline, x64-asan
Linux aarch64 debian 13, ubuntu 25.04
musl alpine 3.23 x64, x64-baseline, aarch64
Windows 2019 x64, 11 aarch64

Locally: the five cancel tests pass, test/js/sql/ is unchanged at 586 pass (same 29 pre-existing failures from MariaDB root auth and two debug+ASAN-slow sqlite fuzz tests), and both end-to-end checks against PostgreSQL 17 behave: the head query dies with 57014 in well under a second, and a cancelled pipelined query rejects while its neighbour runs its full pg_sleep(30).

Happy to push a retrigger if you would rather roll the dice, but with bingus at three for three I do not think it buys anything.

A query that is cancelled before it is dispatched now rejects from
#run() and #runAsync(), the same placement as #41492. cancel() no longer
rejects the promise itself. An eager reject inside cancel() makes a
cancelled query that nobody awaits an unhandled rejection, which exits
the process with code 1.

Carry #41492's sqlite tests so the sqlite and mysql adapters are covered
in this branch too. After #41492 merges, the query.ts hunks for #run()
and #runAsync() resolve as identical on rebase.
Comment thread src/js/internal/sql/postgres.ts Resolved
Comment thread src/js/internal/sql/postgres.ts Resolved
Comment thread src/js/internal/sql/postgres.ts Resolved
Comment thread src/js/internal/sql/postgres.ts Resolved
Comment thread src/js/internal/sql/postgres.ts Resolved
Comment thread src/js/internal/sql/query.ts Resolved
Comment thread src/js/internal/sql/shared.ts Resolved
Comment thread src/runtime/api/sql.classes.ts Resolved
…adline

The loop now fails after 4 s with the rows that pg_stat_activity has for
the query, in place of a test timeout with no message.
@robobun

robobun commented Sep 30, 2026

Copy link
Copy Markdown
Collaborator Author

76a436ef4c and c55aa7ab13: the findings of the last review

  • A cancel for a query that ended during the dial. Fixed in 76a436e. The cancel connection now holds the query that it stops and looks at it again when it is ready to write. It sends the CancelRequest only while the query is still the one the backend runs. With select 1 cancelled in the same tick and a second query behind it, the second query was stopped in 115 and 110 of 300 rounds before, and in 15, 10 and 12 of 300 now.
  • What remains. A query that ends after the packet is written and before the server delivers the signal. In two setups with a query that is cancelled in its last milliseconds, the next query was still stopped in 39 to 75 of 300 rounds. The runs differ a lot on this machine, so I do not claim a change for those. The description has the table, and the docs keep the sentence about the next query.
  • A test against a real server. cancel() stops a query that a real server is running uses describeWithContainer. Its poll has a deadline (c55aa7a).

Checked on the debug build:

  • The two test files: 38 pass with a 30 s test timeout. On the release build 367d939, which does not have this change, 19 of them fail.
  • All of test/js/sql/: 937 pass, 2 skip, 47 fail. 46 are MySQL tests that the local MariaDB refuses. One is a retry-count test with a 0.5 s budget that saw 1 attempt under a load average above 600. Its file passes alone, 3 of 3 runs.
  • 1000 cancels and a full GC: no connection object, query object or file descriptor is left over.

size_of::<PostgresSQLConnection>() is now 688 bytes (672 on main). The release size in the description is from 3b664c6, and I have not measured it again for these two commits.

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nothing blocking. The comments below are optional suggestions. There is no need to push a fix for them before merging.

… end of the TLS handshake

The cancel connection now holds its session and its query. It sends no
CancelRequest only when the session is still connected and its backend
runs another query by now. A session that is closed or failed has nothing
left that the packet could stop by mistake. Before, reserved.close(),
which cancels its queries and closes the connection in the same tick, got
no CancelRequest, and the backend ran the query to its end.

For a TLS session the cancel connection now decides when the handshake has
ended. Before, it decided when the handshake started, so a query that
ended during the handshake still got a CancelRequest, which stopped the
next query of that backend.

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nothing blocking. The comments below are optional suggestions. There is no need to push a fix for them before merging.

@robobun

robobun commented Sep 30, 2026

Copy link
Copy Markdown
Collaborator Author

950a49cb4a, release-build numbers, and one open question

  • TLS. The cancel connection asked the session whether its query still runs when the TLS handshake started. It now asks when the handshake has ended (on_handshake). Checked against PostgreSQL 17.11 with ssl = on and a TCP hop that holds the ClientHello of the cancel connection for 300 ms. On c55aa7a a query that nobody cancelled rejected with 57014. On 950a49c it resolves.
  • reserved.close(). c55aa7a sent no CancelRequest when the session closed during the dial, so the backend ran pg_sleep(6) to its end (5994 ms). The cancel connection now holds the session itself, and the backend stops after 110 to 125 ms.
  • Release numbers. The PR body had debug-build numbers for a CancelRequest that the server handles after its query ended. It now has release-build numbers. A loop cancels select 1 and then runs a second query. The second query, which nobody cancelled, rejected with 57014 in 45 to 149 of 300 rounds. A raw protocol client on node:net, with no use of Bun.SQL, gives 57 to 103 of 300. So the cause is the protocol on this server, and not this client: the machine is loaded, and the server needs a median of 52 ms to act on a cancel connection.
  • Open question for a maintainer. When the same raw client waits for the server to close the cancel connection before it writes the next query, the result is 0 of 300. libpq, pgx and pgjdbc wait like that. node-postgres and postgres.js do not. Should a Bun session write no new request while its cancel connection is open? The price is a delay of the next request on that connection after each cancel() of a running query, at most the budget of the cancel connection (5 s). I did not build it, because it changes when a session sends. The numbers and both sides of the trade-off are in the Notes of the PR body, section "A late CancelRequest, and the open question".

robobun added a commit that referenced this pull request Sep 30, 2026
Two other open pull requests add a ConnectionFlags member at bit 6:
IS_CANCEL_REQUEST in #33370 and ON_CONNECT_PENDING in #40913. Each pull
request inserts its line after KEEP_ALIVE_REQUESTED, so the second one
to merge gets a textual conflict there. With LIFETIME_EXCEEDED at bit 7,
the result of keeping both lines has no two members on one bit.
main closes a socket that never opened with on_connect_error (#44327), so
ref_and_close is main's, and the session test for that case is main's too.
…er cancels it

The connection encodes the Bind of a query when it converts the parameters,
and an object parameter is converted by its own code. That code can call
cancel() on the query.

- advance() takes a request out of `pending_requests` before it encodes
  the Bind, and cancel() took it out again: "pending_requests underflow".
  `RequestCounter::Pending` now records that a request is in that counter,
  so `finish_request` is idempotent for all three counters.
- `encode_request` stops when the request was rejected while its
  parameters were encoded, and the batch leaves the write buffer.
- A cancel() that arrives while `do_run` is on the stack marks the query,
  and `do_run` does not send it.
- `PostgresSQLConnection::cancel` decides what cancel() does. The query
  only finds its connection.

Also:

- The cancel key is an `Option`. A process id of 0 is a key, and a server
  that sent no BackendKeyData has none.
- `query.ts` is main's again. The query that is cancelled before it runs
  is #41492.
- The docs say what cancel() does on PostgreSQL and make no claim for the
  other adapters.
Comment thread src/sql_jsc/postgres/PostgresRequest.rs Resolved

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nothing blocking. The comments below are optional suggestions. There is no need to push a fix for them before merging.

Beyond the inline nit, I also checked that the cancel connection's CancelTarget (the RefPtrs to the session and query) is released on every terminal path: it is taken at write time in send_startup_message, cleared in fail_with_js_value for the timeout/connect-error/close paths, and the struct's own Drop covers the rest, so the refcounts balance.

Extended reasoning...

The only finding this run is a test-cleanup nit; the native cancel-connection lifecycle in src/sql_jsc/postgres/PostgresSQLConnection.rs was read for a refcount leak on the timeout and failure paths and none was found.

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code review found no issues

No high-confidence issues detected in this change.

Still open from earlier reviews (1):

  • Unresolved: 1 minor or pre-existing.

@robobun

robobun commented Oct 3, 2026 •

Copy link
Copy Markdown
Collaborator Author

52e8500d7c: merged main, fixed a panic, and made the PR smaller

  • Merged main. main has usockets: tell a socket's holder it is gone exactly once, whoever closes it and whether or not it ever opened #44327, which reports the close of a socket that never opened. The release of the event loop that this PR had for that case is gone, with its session test. The cancel connection now closes by main's rule for a failed connection.
  • Fixed: cancel() from the code of a parameter. A parameter whose toString() calls cancel() on its own query stopped a debug build with panic: pending_requests underflow. The request now records which counter it is in (RequestCounter::Pending), encode_request takes a rejected request out of the write buffer, and do_run does not send a query that was cancelled during its dispatch. PostgresSQLConnection::cancel makes the decision now.
  • Smaller. The query.ts change left this PR, because sql: reject a query that is cancelled before it runs #41492 has it. Only sql: make transaction.close({ timeout }) roll back when pending queries drain before the timeout #32149 has to merge first now. The first line of the description says why.
  • Cancel key. It is an Option. A server that sent no BackendKeyData gets no cancel connection, and a process id of 0 is sent like any other.
  • Tests. 31, up from 21: four TLS modes, prepare: false, a cancelled head with pipelined queries behind it, an error for a cancelled pipelined query, a silent server after the packet, a cancel while only the Parse is on the wire, and the GC edge. 29 of the 31 fail on the released build.
  • Docs. The cancel() text describes PostgreSQL only.
  • Not measured again: the release text size. A release build did not finish on my machine. The last number (+7,424 bytes) is from 950a49c.

New data for the open question. tx.close() cancels its running query and sends ROLLBACK right behind it. In 2 of 400 rounds the CancelRequest stopped that ROLLBACK, and tx.close() rejected with 57014. The transaction still ended rolled back. asyncpg, like libpq, pgx and pgjdbc, does not reuse a connection while a cancel for it is in progress.

@cirospaciari this is the hazard that you named on #23175. Should a session write nothing new while its cancel connection is open? I have not built it. The numbers and both sides are in the Notes of the description, section "A late CancelRequest, and the open question".

CI for 52e8500d7c. Buildkite #123045: 170 jobs passed, and every test lane that ran is green. 1 job failed: windows aarch64 - build-bun could not download the WebKit archive (HTTP 500 from the GitHub release), so its 8 test jobs did not run. No failure comes from this PR. The build before it, #122966, had no build failure, and this head differs from that one by one test file.

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code review completed

Nothing new to post: everything this review found is already covered by existing comments on this pull request or didn't merit a separate one.

Jarred-Sumner pushed a commit that referenced this pull request Oct 5, 2026
… and write nothing past a statement being parsed (#44235)

### Problem
- `Bun.SQL` (postgres): after a pipelined query fails, two queries
issued together on that connection resolve with each other's rows. Equal
column types: no error. Different column types:
`ERR_POSTGRES_UNSUPPORTED_INTEGER_SIZE` or wrong values.
- The `ErrorResponse` arm of `PostgresSQLConnection::on` released the
failed request before its `ReadyForQuery`. A statement issued in that
gap wrote its Parse at once. The late `ReadyForQuery` then made
`advance()` write the next request's Bind first.
- Behind pgdog 0.1.60, a second `ReadyForQuery` for one Sync does the
same on every run.

### Fix
- The `ErrorResponse` arm rejects through `reject_in_flight`
(`on_undecodable_row` of #43187, renamed). The promise rejects at once.
The request keeps its counter and the head of the queue until its
`ReadyForQuery`.
- `advance()` stops at a request whose statement is being parsed, as in
#20986, and a debug assertion states that rule. A reply carries no
request id: it goes to the head of the queue.
- Verified: `test/js/sql/postgres-prepared-pipeline-reorder.test.ts` (24
new tests, 19 fail on main), `sql.test.ts`, every
`test/js/sql/postgres-*.test.ts`.
- Self-reviewed: 7 concerns, 6 addressed, 1 in part (Notes).

### Background
- Bun writes several prepared queries before the first reply. The server
answers each Sync with one `ReadyForQuery`, also after an error.
- `advance()` walks the request queue. It pops finished requests and
writes queued ones.
- Considered a count of Syncs: two counter updates per query, no result
changes. Considered only the clear of `IS_READY_FOR_QUERY` from #35120:
the step-over in `advance()` stays.

### Downsides
- A new statement or simple query issued between an `ErrorResponse` and
its `ReadyForQuery` waits for that `ReadyForQuery`.
- Release binary: `.text` +256 B.

<details><summary>Notes</summary>

**Reproduction.** One connection (`max: 1`, also `sql.reserve()` and a
pool connection that carries more than one query), a real PostgreSQL,
default options:

```js
const sql = new SQL({ url, max: 1 });
const ofBob = () => sql`select owner, secret from swap_b where id = ${1}`;
const check = n => sql`select 10 / ${n}::int as q`;
await ofBob();
await check(1);
await Promise.all([ofBob(), check(0)]).catch(() => {});
const [a, b] = await Promise.all([sql`select owner, secret from swap_a where id = ${1}`, ofBob()]);
// a is the row of swap_b, b is the row of swap_a
```

The `ErrorResponse` of `check(0)` and its `ReadyForQuery` must arrive in
two reads. On loopback that happens in 35 to 86 of 100 rounds. A proxy
that forwards every byte and holds the `ReadyForQuery` until the two
reads are issued makes it 50 of 50. The tests use that proxy
(`pgHoldingProxy` in `test/js/sql/wire-frames.ts`), with no timer.

Frames after the rejection, main: `Parse(swap_a) Sync`, the held
`ReadyForQuery`, `Bind(swap_b) Sync`, `Bind(swap_a) Sync`. The queue
order is swap_a, swap_b. This branch: the held `ReadyForQuery`,
`Parse(swap_a) Sync`, `Bind(swap_a) Sync`, `Bind(swap_b) Sync`.

The queries in the gap do not have to come from the rejection handler.
Issued by a timer that was armed before the failing query, through the
same proxy, they are wrong in 10 of 10 rounds on 1.4.2 and in 0 of 10
here.

**pgdog.** pgdog 0.1.60 with its query parser on (one primary and one
replica entry for the same PostgreSQL 17) rejects a statement with a
syntax error itself. It answers the batch `Parse Describe Bind Execute
Flush Sync` with `ErrorResponse ReadyForQuery`, and then with one more
`ReadyForQuery`. The second one arrives when the Parse of the next
request is on the wire.

```js
const bad = sql`selec 2 as x`; // rejected by pgdog
const a = sql`select 'alice' as owner, ${1}::int as id`; // new to the connection
const b = sql`select 'bob' as owner, ${1}::int as id`; // prepared
await Promise.allSettled([bad, a, b]);
```

Official 1.4.2: `a` resolves with bob and `b` with alice in 50 of 50
rounds, with no proxy and no mock. This branch: 0 of 50. After the two
`ReadyForQuery`, 1.4.2 writes `Parse(alice) Describe Sync`, `Bind(bob)`,
and later `Bind(alice)`. This branch writes `Parse(alice) Describe
Sync`, and after its reply `Bind(alice)`, `Bind(bob)`. The stop in
`advance()` is the half that fixes this case.

**Why the flag was wrong.** Every `ReadyForQuery` sets
`IS_READY_FOR_QUERY`, whichever Sync it answers. With two pipelined
queries in flight, the first `ReadyForQuery` sets it while the second
Sync is not answered. `pipelined_requests > 0` is the guard for that
state. The `ErrorResponse` arm called `finish_request`, so the count
went to 0 with a `ReadyForQuery` owed. A query that fails alone twice in
a row reaches the same state: the second one is written behind the first
in the gap of the first.

**Tests.** `postgres-prepared-pipeline-reorder.test.ts` has 28 tests, 24
of them new.
- Real server through the proxy, 17 tests that fail on main: 8 shapes of
queries issued in the gap (a new statement and a prepared one, with
equal and with different column types, through `execute()`, with a
simple query, two new statements, three queries), each after a query
that failed behind another one and after a query that failed alone twice
in a row. One more on a connection reserved from a pool of 10. The shape
with two new statements does not settle on main.
- Real server, 5 tests that pass on main too: a transaction that begins
in the gap, and 4 other kinds of failing query (a simple query, a Parse
that fails with and without a parameter, a first execution without
parameters). They pin that each kind leaves the queue at its
`ReadyForQuery` and that the connection continues.
- Mock, 2 tests that fail on main. PostgreSQL sends nothing but the
`ReadyForQuery` after an `ErrorResponse`, and one `ReadyForQuery` for
each Sync. With such a server, each half of the fix alone gives every
query its own rows. So each half has a test with a peer that sends more.
- The hold: the mock sends a row after the `ErrorResponse`. With only
the hold reverted, 1 of 28 fails: the row goes to the query issued in
the gap. No real peer that does this is known.
- The stop: the mock replays the frames of pgdog. With only the stop
reverted, 1 of 28 fails, and a debug build stops at the assertion
`advance() passed a request that is not written yet`.

**Measurements.** Base is main `a4f1429148`. PostgreSQL 17.11 on
loopback, linux x64.
- Edited arms on the success path: 0 executions in 1,703 fulfilled
queries over 7 workloads (gdb counting breakpoints, debug build. Base 0
in 1,703). The calls of `advance()` from the `ReadyForQuery` arm and the
Binds written at enqueue are equal on base and branch for the 6
workloads with a fixed order. The workload with a pool of 10 differs
from run to run on both.
- Steady state, 200 queries in bursts of 10: socket writes 20 (base 20),
`advance()` entries 200 (base 200), reads 23 to 25 (base 23).
- Instructions for each pipelined query: not measured. `perf` and
`valgrind` are not in the container and have no package there. In place
of that, gdb `stepi` on the release build with symbols, 20 calls in the
middle of a burst: `advance()` 108 instructions for each call (base
108), `finish_request` 17 (base 17).
- Release binary: `.text` +256 B. `advance()` +357 B, `on_result` +29 B,
the two instances of `on()` -22 B each (`size`, `nm -S`). The debug
assertion and the comments came after this measurement. They change no
byte: `.text` and these symbol sizes are equal at `28aeaddf7` and
`21c547a52`.
- `size_of` `PostgresSQLQuery` 64 B (was 64), `PostgresSQLConnection`
672 B (was 672), `Flags` 7 B (was 7).
- For each failing query: `finish_request` at the `ErrorResponse` 0 (was
1), at the `ReadyForQuery` 1 (was 0). The shape of the report:
`advance()` entries 15 (was 15), socket writes 11 (was 12).
- Counters when the connection closes, after 7 workloads with failing
queries (50 connections): `pipelined_requests` 0,
`nonpipelinable_requests` 0, `pending_requests` 0.
- 12 shapes of queries in the gap, with the wire recorded: 0 wrong (was
6). Shapes that write before the held `ReadyForQuery`: 2 (was 12). The 2
are a prepared execute, which is still pipelined behind the failed
request. After a failed simple query a prepared execute is written after
the `ReadyForQuery` (was before).
- The script of the report, release build: 0 of 100 rounds wrong in 3
runs (base 35, 37, 39. Official 1.4.2: 86, 84, 62). With the proxy: 0 of
50 (base 50, 1.4.2 50).
- `close()` between the `ErrorResponse` and the held `ReadyForQuery`, 5
kinds of failing query and 6 ways to close: all 30 settle the same on
1.4.2 and here. A FATAL `ErrorResponse`, which the server follows with a
close and no `ReadyForQuery`, also settles the same.

**Existing suites**, debug build, local PostgreSQL: every
`test/js/sql/postgres-*.test.ts`, `sql-prepare-false`,
`sql-pool-transaction-isolation`, `sql-reserve-abort`,
`sql-onconnect-onclose-throw`, `sql-close-pending-connection`,
`wire-frames`. `postgres-string-leak` exceeds the 5 s timeout under the
debug build, on base too. In the last run the container was under load,
and subprocess tests in 4 other files passed 5 s. Each of those that I
ran again alone passed. `sql.test.ts` against the local server: 18 to 20
of 854 fail, base 23. Each case that fails on the branch fails on base
too. They need roles and an encoding that the local server does not
have, or they depend on time under the debug build. The case for #22395
passes. No run stopped at the new assertion.

**A request that fails in its Parse** stays `Pending` with its place in
`pending_requests`. The `discard_response` branch of the `ReadyForQuery`
arm calls `finish_request`, whose `Pending` arm releases that place.
`finish_request` has no edit.

**Covered by reading only.** The failure path of `on_result` needs a
command tag that fails to convert. It now keeps the request in flight
when the `ReadyForQuery` is still to come. Before, the counter of that
request was never released.

**Not changed, named for later.**
- A peer that sends a `ReadyForQuery` that answers no Sync releases a
held request one message early. The rows stay in order (the stop).
- The setter of `IS_READY_FOR_QUERY` and the early clear of
`WAITING_TO_PREPARE` at `ParseComplete` and `ParameterDescription`. The
held counters are the guard. A count of Syncs is the follow-up if the
flag must be exact. It needs a rule for a `ReadyForQuery` that answers
no Sync first: pgdog sends one, and 6 cases of
`postgres-infinity-date.test.ts` answer one Sync with two.
- Parse+Describe+Sync of a named statement and the first execution
without parameters hold no counter. The flag pair guards them.
- The arm of `advance()` for a request with no statement. It cannot be
reached: `do_run` sets the statement before each push.
- The MySQL adapter releases a request at a row it cannot decode, in the
middle of its response (`JSMySQLConnection.rs`). #43323 is open for
that.

**Open pull requests on the same code.**
- #35120 (re-prepare of invalidated statements) clears
`IS_READY_FOR_QUERY` in the `ErrorResponse` arm for every error. That
line alone closes the gap for a server that sends one `ReadyForQuery`
for each Sync. It leaves the early release and the step-over. By
reading, the pgdog case stays with that line alone. The two changes
merge with no conflict. The retry branch of #35120 releases and queues
the request again at the `ErrorResponse`, so it needs the same hold
after a rebase.
- #33370 (`Query.cancel()`) releases a `Pending` request whose Parse is
on the wire and marks it `Fail`. That is the same early release from a
second place.
- #43918 rewrites `encode_request`. This change does not touch it.

**Self-review.** The concerns taken up:
1. The first text said that no open pull request covers this gap. #35120
covers a part of it. The text above now says so.
2. #33370 was not named. It is named above.
3. The sites of the same class that stay were not listed. They are
listed above.
4. Each half was pinned only by a mock of a peer that does not exist.
Addressed in part: the stop test now replays the frames of pgdog, and
the run against the real pgdog is above. The hold test is still a mock.
5. `src/` had comments of more than one line. Each is one line now.
6. The reserved case ran on a pool of 1. It now reserves from a pool of
10: 10 sockets open and one carries the queries.
7. Nothing stated the write order in a debug build. `advance()` now
asserts that it passes no request that is not written yet.

**Credit.** The hold is the mechanism of #43187. The stop is the arm of
#20986.

</details>

<!-- robobun:evidence:begin -->

---

**[human-review]** gate passed · iteration 0 · 4 files touched

<details><summary>fails on main (without fix)</summary>

```console
ASAN without fix: 19 FAILED
$ BUN_DEBUG_QUIET_LOGS=1 bun scripts/build.ts --profile=debug --quiet test "--reporter=junit" "--reporter-outfile=/tmp/pr_gate.xml" test/js/sql/postgres-prepared-pipeline-reorder.test.ts
bun test v1.4.3 (367d939)

test/js/sql/postgres-prepared-pipeline-reorder.test.ts:
Container ready via docker-compose: postgres_plain at 127.0.0.1:5432
(pass) postgres > a prepared-statement execute does not jump a queued unwritten prepare [950.35ms]
(pass) postgres > prepared executes do not jump multiple queued unwritten prepares [371.61ms]
(pass) postgres > mixed burst of prepared and new statements returns every row in order [369.38ms]
(pass) postgres > a prepared-statement execute does not jump a queued unwritten simple query [128.05ms]
Container ready via docker-compose: postgres_plain at 127.0.0.1:5432
204 |   return `{${values.map(arrayValueSerializer.bind(this, type, isPostgresNumericType(type), isPostgresJsonType(type))).join(delimiter)}}`;
205 | }
206 | function wrapPostgresError(error) {
207 |   if (Error.isError(error)) {
208 |     return error;
209 |   return new PostgresError(error.message, error);
               ^
PostgresError: Failed to read data
 hint: "The quer
... (truncated)

release without fix: all passed
bun test v1.4.3-canary.1 (21c547a)

test/js/sql/postgres-prepared-pipeline-reorder.test.ts:
Container ready via docker-compose: postgres_plain at 127.0.0.1:5432
(pass) postgres > a prepared-statement execute does not jump a queued unwritten prepare [54.98ms]
(pass) postgres > prepared executes do not jump multiple queued unwritten prepares [48.48ms]
(pass) postgres > mixed burst of prepared and new statements returns every row in order [24.94ms]
(pass) postgres > a prepared-statement execute does not jump a queued unwritten simple query [12.04ms]
Container ready via docker-compose: postgres_plain at 127.0.0.1:5432
(pass) postgres > before the ReadyForQuery of a query that failed behind another query > a new statement with other column types, a prepared one resolve with their own rows [131.62ms]
(pass) postgres > before the ReadyForQuery of a query that failed behind another query > a new statement, a prepared one, through execute() resolve with their own rows [141.14ms]
(pass) postgres > before the ReadyForQuery of a query that failed behind another query > a new statement, a simple query resolve with their own rows [142.52ms]
(pass) postgres > before the ReadyFor
... (truncated)
```

</details>

<details><summary>passes on PR (with fix)</summary>

```console
ASAN with fix: all passed
$ BUN_DEBUG_QUIET_LOGS=1 bun scripts/build.ts --profile=debug --quiet test "--reporter=junit" "--reporter-outfile=/tmp/pr_gate.xml" test/js/sql/postgres-prepared-pipeline-reorder.test.ts
bun test v1.4.3 (367d939)

test/js/sql/postgres-prepared-pipeline-reorder.test.ts:
Container ready via docker-compose: postgres_plain at 127.0.0.1:5432
(pass) postgres > a prepared-statement execute does not jump a queued unwritten prepare [609.58ms]
(pass) postgres > prepared executes do not jump multiple queued unwritten prepares [492.29ms]
(pass) postgres > mixed burst of prepared and new statements returns every row in order [253.06ms]
(pass) postgres > a prepared-statement execute does not jump a queued unwritten simple query [157.56ms]
Container ready via docker-compose: postgres_plain at 127.0.0.1:5432
(pass) postgres > before the ReadyForQuery of a query that failed behind another query > a new statement, a prepared one resolve with their own rows [1856.81ms]
(pass) postgres > before the ReadyForQuery of a query that failed behind another query > a new statement with other column types, a prepared one resolve with their own rows [1664.26ms]
(pass) postgres > before the Rea
... (truncated)

release with fix: all passed
$ bun scripts/build.ts --profile=release
[configured] bun-profile → bun (stripped) in 7581ms (unchanged)
ninja: Entering directory `/workspace/bun/build/release'
[1/186] gen cpp.rs (cppbind)
[2/186] gen generated_host_exports.rs
generated_host_exports.rs: 121 exports (host=5, lazy=10, generic=106, rust=0); 248 extern-C blocks audited
[3/186] gen JS modules (bundle-modules)
Preprocess modules (11769ms)
Bundle modules (1818ms)
Postprocesss modules (245ms)
Bundle Functions (1012ms)
Generate Code (63ms)

[14.93s] Bundled "src/js" for production
  2613 kb
  198 internal modules
  13 native modules
  50 internal functions across 16 files
[4/74] cxx obj/unified/UnifiedSource-src_jsc_bindings-1.cpp.o
[5/74] cxx obj/unified/UnifiedSource-src_jsc_bindings-3.cpp.o
[6/74] cxx obj/unified/UnifiedSource-src_jsc_bindings-0.cpp.o
[7/74] cxx obj/unified/UnifiedSource-src_jsc_bindings-5.cpp.o
[8/74] cxx obj/unified/UnifiedSource-src_jsc_bindings-4.cpp.o
[9/74] cxx obj/src/jsc/bindings/bindings.cpp.o
[10/74] cc obj/packages/bun-usockets/src/loop.c.o
[11/74] cxx obj/unified/UnifiedSource-src_jsc_bindings_node-0.cpp.o
[12/74] cc obj/packages/bun-usockets/src/bsd.c.o
[13/74] cxx obj/un
... (truncated)
```

</details>

<details><summary>diff hotspot</summary>

```
src/sql_jsc/postgres/PostgresSQLConnection.rs      |  17 +-
 src/sql_jsc/postgres/PostgresSQLQuery.rs           |  16 +-
 .../sql/postgres-prepared-pipeline-reorder.test.ts | 278 ++++++++++++++++++++-
 test/js/sql/wire-frames.ts                         |  56 +++++
 4 files changed, 355 insertions(+), 12 deletions(-)
```

</details>

**gate history** · 1 passed · 0 rejected · iteration 0

<details><summary>evidence per changed file</summary>

```
file                                                    reads  edits  tests
src/sql_jsc/postgres/PostgresSQLConnection.rs               5      0     39
src/sql_jsc/postgres/PostgresSQLQuery.rs                    3      0     39
test/js/sql/postgres-prepared-pipeline-reorder.test.ts      2      0     38
test/js/sql/wire-frames.ts                                  2      2     40
```

</details>

<!-- robobun:evidence:end -->
Jarred-Sumner added a commit that referenced this pull request Oct 17, 2026
…quests (#45304)

### What does this PR do?

It folds 197 open pull requests on `Bun.sql` (PostgreSQL, MySQL, MariaDB, SQLite), `bun:sqlite` and `node:sqlite` into one change: 149 are replaced by it, 18 are closed without porting, 30 stay open. Most PRs were taken as a diagnosis; the files many of them patched were rewritten once. 257 files, +41,670 / -21,600: `src` +12,536 / -16,054, tests +26,903 / -5,100. CI ran the suite on Linux x64 / aarch64, musl, ASAN, macOS and Windows at this head (78e0830cdd): every job that ran passed (178; one macOS aarch64 job could not download the build, two macOS x64 jobs got no machine). Numbers marked (release) compare CI's Linux x64 release binaries of main (f841e3670) and of earlier commits of this PR, in user-space instructions unless a unit is given; the others are from a local debug + ASAN build.

### How did you verify your code works?

102 SQL and SQLite test files on a Linux x64 debug + ASAN build against PostgreSQL, MySQL and MariaDB containers: 5,918 tests pass; 8 time out on a machine at load 210 to 250, each of which passes alone or is known to depend on load. Nearly every new test was run on main first and fails there; the exceptions are guards that pin behaviour we keep. PostgreSQL parameters against main, cell by cell (value, type, mode): of 942, 726 are equal, 137 work that main rejects, 17 reject with another code, 44 are new errors, 18 stored another value (six cases: two are main's again since, four are listed). The option parser against main: 120,000 generated cases, every difference named; TLS is weaker than on main only on a unix socket (3,191), where `url` names another driver than a variable's name (14), or where the adapter's own URL rules and main read another adapter's (21); no file main opens read-only is writable. Option keys that an options object inherits are read where main reads them. On the wire against main, the startup packet and the number of round trips are the same (no parameter, one, jsonb + text + timestamptz, begin / commit; prepared and `prepare: false`); only a redundant Flush is gone. Client CPU (release, 43ad527e44): point select -48 %, 100-row select -30 %, insert -21 %. The pool, `cancel()`, MySQL pipelining and the `bun:sqlite` hooks were also run under randomized stress or differential scripts.

### Behaviour changes to look at first

`main -> now`. The rule: a visible change stays only where main is broken (crash, hang, data lost or stored wrong, security hole, against its own docs); elsewhere this PR behaves like main, and the pull request that wanted the change stays open. Every bullet was run on main, on this branch and, where there is one, on the reference clients: postgres.js, pg, mysql2, mariadb, Node 26.3's `node:sqlite`, psql 15 (not better-sqlite3). `ERR_*_X` stands for the `POSTGRES`, `MYSQL`, `SQLITE` codes.

**Waiting for the maintainer's word**

- **Integers from 2^51 to 2^53 - 1** were `float8` (MySQL: DOUBLE) -> `int8` (BIGINT). PostgreSQL stored 2^52 + 1 as 4503599627370500 in `numeric` and `4.503599627370497e+15` in `text`; now exact. The price: `select ${2 ** 52} as x` returns a string and `/ 3` divides as integers, as from 2^31 to 2^51 already. On MySQL only VARCHAR was wrong; there `* 4096` is a new errno 1690, and mysql2 and mariadb behave like main (#43293).
- **An array with an enumerable `raw` is refused.** `Object.assign([text], { raw: [text] })`, also what Babel's and swc's loose mode emit for a tagged template, ran `text` as SQL, as in postgres.js -> `TypeError`; tslib and the strict helpers (non-enumerable `raw`) still run. It closes `ids.raw = []` on a data array pasting `ids[0]` into the SQL, which only the application itself can set. The own-property half of the check closes more: on main a polluted `Array.prototype.raw = []` turns `sql([userData])` into SQL text. The price is every tagged call compiled in loose mode (#38219).
- **An untyped `sql.array()` has no cast.** `sql.array(["a", "b"])` without a type was cast to `::JSON[]`, so both examples of main's docs fail -> no cast, the server decides (#41301, #41242). Where it can't tell, main and postgres.js work and this PR doesn't: `select ${sql.array([1, 2])}` is the string `{"1","2"}`, `unnest()` 42725, `array_length()` 42804. Pass the type.
- **`prepare: false`:** an object with its own `toString()` bound to `json` / `jsonb` was that string (decimal.js: the number `1.5`) -> its JSON, as in a prepared query on main (#39452).
- **bun:sqlite `db.transaction(fn)`, the minimal fix.** When `fn` returns a native promise that is already rejected (an `async` function that throws before its first `await`), main committed -> rolls back and returns the promise. All else is as on main: an `async` callback commits at its first `await`, a `throw` behind it keeps the rows, and the docs now warn. The alternative is to refuse async callbacks outright (#45132), which also refuses what works today: `async` without an `await`, an `await` that comes last, a returned fulfilled promise or thenable.
- **bun:sqlite, not changed:** without `safeIntegers` a BigInt parameter above 64 bits keeps its low 64 bits (`2n ** 64n + 5n` binds 5), as on main; a `RangeError` for it (a third of #32841) was in and is reverted. Proposed on this PR: reject below -2^63 or above 2^64 - 1, which still lets `Bun.hash()` output bind but makes a released call throw.

**Silent: the same code gives another result**

- bun:sqlite `changes` also counted rows written by triggers, cascades, FTS5 / rtree shadow tables -> only the statement's own, like node:sqlite and SQLite's `changes()`. An insert through an INSTEAD OF trigger on a view counted what the trigger wrote -> 0. The SQLite adapter's `count` follows (#43306).
- `affectedRows` was `null` on PostgreSQL and SQLite -> rows written, 0 for a `SELECT`, so `r.affectedRows ?? r.count` gives 0 after a `SELECT` (#40434, #40432). MySQL `count` of a write: 0 -> rows affected (#41886). SQLite adapter: `lastInsertRowid` of `INSERT ... RETURNING` `null` -> the rowid; `count` of `WITH ... INSERT` 0 -> 1; `command` is the first keyword: an upsert `UPDATE` -> `INSERT`, but `with ... insert` `INSERT` -> `WITH`.
- `uuid[]`, `int4range[]`, `tsvector[]`, `reg*[]`, 35 built-in array types in all, read as the literal `"{...}"` -> arrays, like postgres.js (pg: `uuid[]` only) (#41042, #41039). Columns named `01` and `1` collapsed into one key -> each keeps its name; `row[1]` no longer finds `01` (#45096).
- Into `text`: a `Date` was `Tue Jan 02 2024 03:04:05 GMT+0000 (...)` -> ISO 8601; a plain object was `[object Object]`, as in postgres.js -> JSON, as in pg (#41976, #29010).
- `null` in `sql.array(values, "TEXT")`, `"INT"` and the rest was the string `"null"` or an error -> SQL NULL (#35111); in a `"JSON"` / `"JSONB"` array it stays the JSON value `null`, as on main. A `Buffer` element there was its hex string -> `JSON.stringify(buffer)`.
- PostgreSQL, a late mode on a statement that is already prepared: `.execute().raw()` gives text for `numeric`, `time` and binary for `int2[]`, `float8[]`, the reverse of main; `.raw()` and a late `.values()` of `numeric`, `time` rejects with `ERR_POSTGRES_UNKNOWN_FORMAT_CODE`. All else of `.raw()` is as on main (658 of 666 cells).
- `prepare: false` sends what a prepared query sends (one more round trip next to an array, an `Int32Array`, an object with its own `toString()`): `[1]` into `jsonb` was the scalar `1`, an `Int32Array` into `bytea` the bytes of the text `1,2`; an `Array` into `bytea` is now `ERR_INVALID_ARG_TYPE` (#39452).
- bun:sqlite `get()` read every row, as documented, so an error in row 2 was thrown -> one step. `SELECT 1 a, 2 b, 3 a`: `{b, a}` -> `{a: 3, b: 2}` (key order). A column named like an index (`"2023"`) now comes first in `Object.keys(row)`, as JS orders keys (#37238). `values()` / `raw()` without columns: `null` -> `[]`. node:sqlite `run()` on a `SELECT` stepped through every row -> one step. All like Node.
- SQLite's `MEMSTATUS` is off: `PRAGMA hard_heap_limit` / `soft_heap_limit` are accepted and no longer enforced, as in node:sqlite (#44197, #44187).
- PostgreSQL: a Flush after every simple Query disarmed the server's idle timers; after an extended query they already worked -> `idle_in_transaction_session_timeout` / `idle_session_timeout` end Bun's sessions on both paths (25P03, 57P05), `listen()` included (docs: `connection: { idle_session_timeout: 0 }`) (#44784).
- After `SET datestyle = 'SQL, DMY'` April 3 read as March 4, as in postgres.js -> any non-ISO style reads Invalid Date, also MDY, which main read right.
- TCP keepalive (60 s idle, 10 probes 1 s apart) on every SQL socket, no option, as in postgres.js (pg, mariadb: none): a query silent for 60 s can reject after a 10 s outage, where main resumed (not run). #44983 asked for `listen()` only.
- `then()`, `catch()`, `finally()`, `run()` started the query a microtask later -> in the call, like `execute()` (#44105). `begin()` / `reserve()` overtook older plain queries -> one queue, oldest first, like postgres.js (#45275). `sql.file(path)` ran at once -> a lazy `Query`, as typed and as in postgres.js.
- A result returned from a `begin()` / `savepoint()` callback came back as a plain `Array` without `count`, `command`, `columns` -> the result itself, like postgres.js; `assert.deepStrictEqual` with an array literal then fails (#45387).
- A statement on an ended `tx`: `ERR_*_CONNECTION_CLOSED` -> `ERR_*_INVALID_TRANSACTION_STATE`, because retry helpers rerun on "connection closed" (#43263).
- With a URL, `host` / `user` / `pass` beat `hostname` / `username` / `password`; without one they lost -> the long names always win. `?path=A` beat `{ path: B }` (also `unix://A` and `{ socket: B }`) -> the option wins, like every other option.
- MySQL / MariaDB ignored `?connect_timeout=`, `?idle_timeout=`, `?max_lifetime=`, `?max=` in the URL -> they set the options (see New).
- MySQL / MariaDB: `close()` and the timers send COM_QUIT, like mysql2 and mariadb. "Connection closed" / "failed to bind and execute query" for most client-side codes -> one sentence per code (#38468). An ERR packet the server sends unasked reaches `onclose` as the server's error, not as `ERR_MYSQL_UNEXPECTED_PACKET` (#40913).
- Driver errors: `stack` is the header line only (it had two `internal:sql/*` frames); a non-`Error` thrown while a parameter is read is no longer wrapped (#44118, #44204). PostgreSQL statement names in server logs: `P` + 40 bytes of SQL + `$` + id -> `P<id>` (#44042).

**Loud: an error where main ran**

- `PGUSERNAME` and `USERNAME` are read as the PostgreSQL user, as main's docs promise; main ignored both. `PGUSERNAME` beats `USER`. `USERNAME` counts where `USER` isn't set, as on Windows, where main logged in as `postgres` (not run there) (#26711, #26684).
- `mariadb://` without a database asked for one named `mariadb`, which no server has, and couldn't connect (1049) -> selects none, like the mariadb connector; the first unqualified table is a 1046. MySQL keeps `mysql`, as main's docs promise; the types said the user name (#44367, #44373).
- MySQL / MariaDB: `sql("db.table")` was one name `` `db.table` `` -> `` `db`.`table` ``, as documented, as on PostgreSQL and SQLite and in mysql2 (mariadb keeps one name). Helper keys (`sql({ "c.d": 7 })`) and aliases split too, so a name with a real dot can't be passed. A name taken from a user can now reach another schema (#24050).
- A query created on `reserved` / `tx` / `sp` and first awaited after `release()`, COMMIT, ROLLBACK or RELEASE ran on the pooled connection, as in postgres.js: a `select` worked, an insert that landed in another caller's transaction resolved and kept 0 rows -> rejects unsent. Typical: ``return reserved`...` `` without `await` out of a `using` block (#43261, #43263).
- `sp === tx` in `tx.savepoint(sp => ...)` -> `sp` is its own handle, like postgres.js, and ends with its savepoint; on main and in postgres.js it kept running in the transaction (#43263).
- PostgreSQL: an array or object bound to `bool` / `int4` / `float8` / `timestamp` was coerced in the client (`[]`: `true`, 0, 0, 2000-01-01), so `delete ... where ${[]}` removed every row -> sent as text, which the server rejects (22P02, 22007) unless it is valid: `[5]` into `int4` is still 5, and `['2024-01-02']` into `timestamptz`, 2000-01-01 on main, is that date (#41976, #41970).
- An Invalid Date was stored as 1970-01-01 on PostgreSQL (#41976) and MySQL -> rejected. MySQL: a function, or an object whose `toJSON()` returns undefined, was bound as `""` (MariaDB: errno 1210) -> `TypeError`, like mysql2.
- bun:sqlite: `stmt.run(new Date())`, a Map, a Promise as the only argument bound NULL, as in node:sqlite; in any other position main throws already -> `TypeError` everywhere. An `ArrayBuffer` alone bound NULL -> BLOB.
- `channelBinding: "require"` / `?channel_binding=require` on MySQL, MariaDB, SQLite was an unknown key and ignored -> `TypeError`.
- A `path` that doesn't exist was dropped and TCP dialed -> `ERR_*_CONNECTION_REFUSED` (postgres.js, pg: ENOENT) (#41570).
- `tls.checkServerIdentity` was never called -> called, and it raises an `sslmode` below `verify-ca` to `verify-full`, so a self-signed certificate without `ca` fails, as in pg and postgres.js (#42054, #41856).
- SQLite adapter: what `onconnect` / `onclose` throw was swallowed -> uncaught exception, as on the other adapters. `?mode=RO`, `?mode=readonly`, `?mode=`, `{ readOnly: true }` opened read-write -> throw (#45153, #45079).
- The guard against `BEGIN` on a pooled client also catches `START\tTRANSACTION` and `/* c */ BEGIN`, and no longer trips on `begin_work()` or copies the query (#41758, #41740).
- A nested `sql.unsafe(text, values)` behind other parameters read the wrong parameter on PostgreSQL, as in postgres.js -> `SyntaxError` (#38220).
- A simple `FETCH` from a binary PostgreSQL cursor decoded `numeric`, `time` and read `int2` / `oid` as 0, `int8` / `uuid` as garbage -> these reject with `ERR_POSTGRES_UNKNOWN_FORMAT_CODE`.
- `COPY ... TO STDOUT` without a stream resolved `[]`, `COPY ... FROM STDIN` hung and wedged the connection -> both reject with `ERR_POSTGRES_COPY_NOT_SUPPORTED` (#45332).

**Main was broken; code that leaned on it will notice**

- A pooled connection that came back inside an open or failed transaction (a reservation after `BEGIN`, `sql.unsafe("select 1; begin")`) went to the next caller, who got 25P02 or lost its writes -> the drivers keep the server's transaction status and the pool closes it. For that status to be current, a failed PostgreSQL query rejects at its ReadyForQuery, like libpq, not at the ErrorResponse. Exempt: plain queries at `max: 1`, where the docs allow `BEGIN` by hand, and a prepared XA branch.
- `idleTimeout` / `maxLifetime` closed connections under a running query, a reservation or a `begin()` transaction -> they never interrupt those, as in postgres.js; past `maxLifetime` a connection takes nothing new, finishes, closes (#30648, #30646, #25405).
- What the caller's own `catch(f)`, `then(_, f)` or `finally(f)` handler throws was swallowed -> an unhandled rejection. MySQL / MariaDB: `begin()` never settled when a statement on `tx` was only started and failed -> settles. (94 cells against main: these 32 differ.)
- Callers waiting for a connection were rejected with the close error of somebody else's connection -> the pool dials for them (#44938). A client-side auth or TLS error before the first connection was cached until restart -> every query dials.
- A second `close()` resolved while a session was still open -> all calls wait for one close, the shortest timeout wins (#43959). `close({ timeout: 0 })` waited for running queries -> closes at once, as documented (#33740, #32038).
- `tx.close()` without `await`: `begin()` resolved with nothing stored, or committed -> one ROLLBACK, no COMMIT, `begin()` rejects (#44799).
- Two `reserved.begin()` at once shared one server transaction -> the second waits. SQLite: a second `sql.begin()` failed with "cannot start a transaction within a transaction" -> it waits. Side effect: the same call awaited inside its own callback never settles, like `max: 1` on a server; use `tx.savepoint()`.
- `where id in ${sql([])}` was a syntax error on the servers -> `in (NULL)`, no row, like postgres.js. SQLite keeps `in ()` / `not in ()`.
- Statement caches were unbounded -> a connection keeps the statements it used last, 1,024 on PostgreSQL and 256 on MySQL / MariaDB (there all connections share the server's `max_prepared_stmt_count`, 16,382 by default), and sends Close / COM_STMT_CLOSE for the rest (#28980, #33190). MySQL: a failed prepare was replayed, even after `CREATE TABLE` -> every use prepares again (#33189, #42720).
- A SCRAM password that SASLprep changes costs a second login (see New), so a wrong one counts as two failed logins per query (main: `max`) and a right one as at most one per `SQL` instance: the rest of the pool waits for the first login, which fills the pool one login later for such a password only. A `password` function that returns a promise is not held: `max` each. Other passwords, md5 and cleartext roles: one login, as before (#41605).
- `$PASSWORD` was sent as the database password -> not read. `postgres:///x` was a socket if `/x` existed -> always database `x` (#41570).
- `sql("a\0b")` returned a rejected promise no `try` could catch -> throws at the call (#45160). A `resolve` / `reject` overwritten on a query with a function that throws hung `close()` -> uncaught exception; under an `uncaughtException` listener it still hangs.
- bun:test: `expect(p).resolves` / `.rejects` / `expect(() => p).toThrow()` never called `then()`, so a lazy `Query` hung `bun test` forever -> they call it once while `p` is pending, like Jest (#19130).
- MySQL / MariaDB: `lastInsertRowid` above 2^53 - 1 was rounded -> exact, a string, or a BigInt with `bigint: true` (#44646). Commands are pipelined (see New). A command of 16 MB or more failed in the client (`ERR_MYSQL_OVERFLOW`, session kept) -> it is sent; over `max_allowed_packet` the query gets the server's 1153 and the connection fails, because the server hangs up. A 0xFB reply (a request for a local file) hung the query -> fails the connection, no file is read.
- MySQL / MariaDB: prepared `TIME(n)` lost its fraction -> `"12:34:56.789"`, padded to the column's precision like `.simple()` (mysql2 and mariadb don't pad) (#31738). `.raw()` on a prepared query gave a string for TIME, a `Date` for DATE, DATETIME, TIMESTAMP -> a `Buffer`, as documented. `caching_sha2_password` over a unix socket couldn't log in -> the password goes in clear, as the server expects there and as mysql2 and mariadb do (#37819).
- bun:sqlite: `{ readonly: true, create: true }` opened read-write -> `TypeError` (#41815). `db.run("a; b; c")` / `exec()` swallowed a runtime error of any statement but the last -> throws there, the rest doesn't run (#37418, #37415, #41010). Running a `Statement` again inside its own `iterate()` loop restarted the loop forever -> the newest run wins, the older iterator throws "This iterator was invalidated" (#32917). Both like node:sqlite.
- node:sqlite: `stmt.get()` on `INSERT ... RETURNING` returned a row although the commit failed (deferred foreign key) -> throws. Node 26.3 has the bug. Undo: 6 lines in `NodeSqlite.cpp`.

**Costs**

- The first `new Bun.SQL()` of a process: 23.3 M -> 25.1 M (+7.9 %); the first bun:sqlite database +4.6 % (release).
- bun:sqlite `prepare` + `finalize`: 21,739 -> 23,284 (+7.1 %, release), because statements report their native memory to the GC: 20,000 dropped 200-parameter statements 465 -> 27 MB.
- More distinct texts than the statement cache holds are prepared again and again. PostgreSQL, 24,000 queries over N texts at `max: 4` (release, limit still 256): N = 1,000: 2.0 -> 4.7 s, client CPU 470 -> 880 ms; N = 300: 1.4 -> 1.6 s. With 1,024 (debug builds) 1,000 texts cost what 300 cost; the step lies between 1,000 and 1,100. A full cache costs the server about 41 MB per connection (41 KB per statement with a join and ten columns); main has no bound.
- A bulk insert with an `undefined` cell on PostgreSQL: +2.1 % (see Memory and performance).

### New

**`query.cancel()` works.** It was typed and documented but did nothing. A query that isn't written yet leaves the queue, is never sent and rejects with `ERR_*_QUERY_CANCELLED`. On PostgreSQL a running query with nothing else written behind it is stopped by a CancelRequest on a second connection, outside `max` (same peer, same TLS settings and certificate check, at most 5 s) and rejects with the server's 57014. The session writes nothing until the server has closed that connection, so a late cancel can't hit the next caller's query. There `reserved.close()` / `tx.close()` also stop the running query (#33370, #44625).

**COPY streams (PostgreSQL).** `query.readable()` is a `ReadableStream<Uint8Array>` for `COPY ... TO STDOUT`, `query.writable()` a `WritableStream` for `COPY ... FROM STDIN`. Bytes only (text, CSV, binary), no row encoder. Backpressure both ways. `close()` / `pipeTo()` resolve when the server has stored the rows and reject with its error; `abort()` sends CopyFail, and so does the end of the transaction, savepoint or reservation that a stream is open on: `begin()` then rejects with that error and rolls back. The query still resolves with `count`. They are web streams, not Node streams, and a `COPY` without parameters always goes out as a simple query (#23350, #15088).

**`result.columns`, `result.statement`.** PostgreSQL: `[{ name, type, table, number }]` (OIDs, like postgres.js); MySQL / MariaDB: `[{ name, type, table, length, flags }]`. `statement` is `{ string, types, columns }`. Both are built on the first read, prepared or not. The runs of a prepared statement share one object, which isn't frozen. On SQLite both stay `null`: capturing them cost a 1-row query +17 % to +34 % (main's release build) (#30037, #26809, #18866).

**Column name transforms (all adapters).** `new SQL({ transform: SQL.camel })` reads column `user_id` as `userId` and writes `user_id` for `sql({ userId })`, `sql("userId")`. Presets `SQL.camel`, `pascal`, `kebab`; one direction with `SQL.toCamel`, `SQL.fromCamel` and so on; or `{ column: fn | { from, to }, undefined: value }`. Names, directions and casing are postgres.js's. With `undefined: value` (`null` counts) a helper leaves no column out, like postgres.js. No `value` / `row` transform, so keys inside json aren't renamed (#36451, #15087).

**`sql.json(value)` (all adapters)** stores any value as JSON: a number, a boolean, `null`, an object or array on SQLite, and a JSON *string* where Bun sends a string as it is (MySQL, MariaDB, SQLite, PostgreSQL with `prepare: false`). On PostgreSQL it returns a small wrapper, elsewhere `JSON.stringify(value)`.

**SCRAM-SHA-256-PLUS, `channelBinding: "disable" | "prefer" | "require"`**, also `?channel_binding=` and `PGCHANNELBINDING`. `tls-server-end-point`, hash as in RFC 5929, RSASSA-PSS included, checked against libpq 15. `require` fails with `ERR_POSTGRES_CHANNEL_BINDING_REQUIRED` before anything derived from the password is sent. Off (`disable`) unless asked for, on the maintainer's decision: the login on the wire is main's. With `prefer`, psql's default, a login fails behind a proxy that terminates TLS but forwards the server's `-PLUS` offer (28000) and with an Ed25519 certificate (#41703).

**SASLprep, by retry.** A non-ASCII SCRAM password typed in another Unicode form than it was set in (NFD, soft hyphen) got 28P01 while psql logged in -> the first login uses the password as typed, like main; on 28P01 from a SCRAM role, if SASLprep (two `replace` and `normalize("NFKC")`, no Unicode tables) changes the string, Bun logs in once more with that form. The pool remembers which form worked; the LISTEN connection does the same (#41605).

**`tls.checkServerIdentity(hostname, cert)` (PostgreSQL, MySQL, MariaDB).** Called once per connection, after the chain verified and before anything is sent inside TLS; replaces the built-in name check. A returned object or a throw fails the connection with that value; a Promise is `ERR_INVALID_RETURN_VALUE`. Not called next to `rejectUnauthorized: false` (SQL half of #42054, #41856).

**Re-prepare after DDL (PostgreSQL).** After `ALTER TABLE`, `DEALLOCATE ALL` or `DISCARD ALL` every run of a cached statement failed forever (0A000, 26000) -> it is prepared again under a new name and the old one closed. The query is re-sent only when nothing is written behind it (a re-send would reorder writes) and outside a transaction block; otherwise it rejects with the server's error and the next run works. 20 concurrent runs after `ADD COLUMN`: main rejects 20 and every later run; now 19 at `max: 1`, 15 at `max: 5`, then none (#35120, #29484).

**`bun --hot` keeps database connections (PostgreSQL, MySQL).** Every save opened up to `max` new connections and never closed the old ones (2 4 6 8 10 12 sessions at `max: 2`) -> a `new SQL()` with equal settings takes over the previous load's idle connections when it would dial. Settings are compared by value; a function counts as changed. A pool of an earlier load closes only when nobody asked it for a connection during a whole load: a replaced pool lives one reload longer, a pool kept on `globalThis` and used is never touched. Session state (`SET`, temporary tables) survives, `onconnect` runs again for a reused connection. A module-level `sql.listen()` shares one LISTEN connection across loads (#25623, #23215).

**MySQL / MariaDB pipelining.** `.simple()` queries and queries whose statement is already prepared go out without waiting for earlier replies; an error fails only its own query. Nothing is written behind a text with a `;` until it has ended, and a packet out of sequence fails the connection. Main's docs promise this; it sent one command at a time. Undo: `BUN_FEATURE_FLAG_DISABLE_SQL_AUTO_PIPELINING=1`. 4 executes through a proxy that holds each reply 30 ms took 124 ms on main, now 31 ms on both servers, 1 write instead of 4 (release) (#44022).

**MySQL: `sha256_password`** was documented, but every login failed with errno 1045.

**Arrays as PostgreSQL array parameters.** `where id = any(${[1, 2]})` (08P01) and `sql({ tags: ["a"] })` into a `text[]` failed -> a JS array or an `Int32Array` bound to a built-in array type goes as an array literal, with NULLs and nesting, also with `prepare: false`. The other typed arrays stay `bytea`; `sql.array(new Float32Array([1.5]))`, which main rejects, puts them into an array column. Into `text`, an untyped position or a user-defined type an array stays `String(value)` (`a,b`), as on main and in postgres.js (pg: `{"a","b"}`), so an array of an enum needs `sql.array(values, "mood")`. A plain array into `json[]` / `jsonb[]` follows `sql.array(values, "JSONB")`: nested arrays are dimensions, `null` is the JSON value, `undefined` is SQL NULL, `sql.json([1, 2])` is one element (that half of #33579, #29551).

**MySQL / MariaDB `foundRows: true`**, also `?foundRows=true`: `CLIENT_FOUND_ROWS`, so `affectedRows` counts rows matched, not rows changed, the default of mysql2 and mariadb. Off by default, as on main (#30848, #30843).

**libpq URL keys and variables.** `?connect_timeout=`, `?sslrootcert=` ... went to the server, which refused the connection, and `?password=` went out in the startup packet. Now read: `host`, `port`, `user`, `password`, `dbname`, `connect_timeout`, `idle_timeout`, `max_lifetime`, `max`, `prepare`, `channel_binding`, `sslrootcert`, `sslcert`, `sslkey`, `sslpassword`. Keys that only tune libpq (`keepalives*`, `target_session_attrs` ...) are dropped. Keys that restrict the connection (`require_auth`, `sslcrl` ...) still go to the server, which refuses them. New variables: `PGUSERNAME`, `USERNAME`, `PGAPPNAME`, `PGOPTIONS`, `PGCONNECT_TIMEOUT`, `PGCHANNELBINDING`.

**bun:sqlite: `db.function()`, `db.aggregate()`**, better-sqlite3's signatures (options `varargs`, `deterministic`, `directOnly`, `safeIntegers`); `inverse` makes a window function. What a callback throws comes out of `get()` / `all()` / `run()` unchanged. A BigInt result outside 64 bits follows the function's `safeIntegers`, like a parameter (#8558, #25703, #1474, #5051).

**bun:sqlite: `db.onInsert`, `db.onUpdate`, `db.onDelete`** `= function (database, tableName, rowid, schemaName)`; `null` removes it. What a hook throws is an uncaught exception at once, and the statement goes on. While a function, aggregate or hook runs, every other call on that `Database`, `close()` included, throws "This database connection is busy executing a query". No commit hook (#12631, #4175). **Small:** `db[Symbol.for("sqlite-type")]` (#22109), `stmt.reader`, `stmt.readonly` (#16469), `stmt.declaredTypes` before the first run.

### Fixed

What is listed above isn't repeated. A line without `->` names a symptom that is gone.

#### Pool and lifecycle

- A pool that lost connections dialed nothing while one was ready (it stayed at 4 of 5 for ever and ran 3 parallel queries on 1 backend) -> it grows back, one dial per waiting caller that no dial in flight covers.
- `execute()` / `begin()` inside `onclose` got the dead connection ("connection must be a PostgresSQLConnection") -> it has left the pool and the waiting callers are redialed for before `onclose` runs (#43958, #44938, #45039).
- A connection the server killed in the read that finished the handshake got `onclose`, then `onconnect`, and stayed in the pool: every later query failed, `close()` hung -> `onconnect` never comes after `onclose`, both drivers (#40913, #45039, #42804).
- `close({ timeout: 2 ** 31 })` overflowed `setTimeout` and killed the queries after 1 ms -> clamped (#32100, #32096). `close()`, then `close({ timeout: 0 })`, left a held reservation running (#43959).
- A replaced `Promise.prototype.finally` could wedge the pool -> a private promise; the connection is released before the caller's reactions run (#44315).
- `q.cancel(); await q` never settled -> rejects (#44799).
- The connect-retry budget read `Date.now()`: endless under `setSystemTime()`, short on a clock step -> monotonic clock (#37960).
- A `password` function that throws `undefined` left the query pending forever. `` sql`a; b`.values().simple() `` ignored `simple()`. `query.active` was always false.
- PostgreSQL: a FATAL error for the running query left the connection in the pool until the FIN, and a session ended while idle reached `onclose` as `ERR_POSTGRES_EXPECTED_REQUEST` -> fails at once with the server's error, e.g. 57P01 (#40913).
- `onconnect` / `onclose` never fired for the `sql.listen()` connection (#41051, #41050).
- `bun --sql-preconnect` with a refused connection ran the script, then exited 1, against the docs -> exit 0.

#### Handles, transactions, savepoints

- `sql.begin(tx => Promise.all([...]))` with one failing task: the other tasks' later statements ran after ROLLBACK in autocommit, so rows of a rejected `begin()` or `savepoint()` stayed -> they reject, on all four databases (#43263).
- `tx.unsafe()`, `tx.file()`, `reserved.unsafe()`, `reserved.file()`, `notify()`, `commitDistributed()` ignored the handle's state and ran after its end (#43249, #43261). `` tx`...`.values() `` on an ended handle threw `.values is not a function` -> a `Query` that rejects when run (#43257).
- `tx.close({ timeout })` whose queries finished in time committed -> rolls back (#44799, #32148); `reserved.close({ timeout })` then lost the pool slot. `close({ timeout: -1 })` left the handle unusable (#32100). A handled failing query was reported again as unhandled.
- `close()` or a lost connection started or rejected identifiers, fragments and unstarted queries, and a handle retained them all -> a query is tracked from start to settle (#44932).
- `tx.close()` and the end of the callback could both end the transaction -> one end. Now that `cancel()` works, `close()` spares Bun's own BEGIN / COMMIT / SAVEPOINT (#44799, #44625).
- Connection lost under a `begin()` whose callback doesn't return: later `begin()`, `reserve()`, `close()` hung -> the slot goes back at the loss (#43205). `reserved.unsafe()` then ran on the pool's next connection (#45039).
- `reserved.release()` during a running `reserved.begin()`: the nested COMMIT committed the next caller's work -> the connection goes back after the transaction (#43255).
- `tx.savepoint(sp => [q1, q2])` sent RELEASE before the queries (#43263). `tx.savepoint("audit", fn)` sent `SAVEPOINT s0` -> `s0_audit` (#45111). A failed ROLLBACK lost the callback's error -> it is the `cause` (#41817).
- The `begin()` callback saw no `AsyncLocalStorage` store on a cold pool, another request's on a busy one -> its caller's (#43652).
- A `reserve()` handle dropped without `release()` kept its connection forever -> released when collected (#35117).
- `sql instanceof Bun.SQL` threw -> true for every handle; `class X extends Bun.SQL {}` threw at the definition -> `new X()` throws "Bun.SQL cannot be subclassed" (#42637). `new Bun.sql(url, { tls: true })` dropped the options and connected in plaintext (#45118).
- SQLite: a failed COMMIT left the transaction open and every later `begin()` failed -> rolled back. After `INSERT OR ROLLBACK`, `RAISE(ROLLBACK)`, `SQLITE_FULL` the rest of the callback ran in autocommit -> nothing more runs (#45065). `close()` didn't reject a running `begin()` (#43116).

#### Options, URLs, environment

- `{ filename: "./dev.db" }` without `adapter` dialed PostgreSQL on host `.`; `SQLITE_URL=x.db` opened `postgres://x.db` (#44483). A server's URL in `filename`, or `hostname`, `port` ... next to it, still make it a connection string. `{ adapter: "sqlite", url }` opened `:memory:` (that half of #38427).
- `{ adapter: "sqlite" }` next to a server `DATABASE_URL` used it as the file name -> `:memory:`. `{ adapter: "mysql" }` without a host next to `DATABASE_URL=postgres://...` dialed that host and timed out -> `MYSQL_URL`, else defaults, and then with the TLS level the passed-over URL asks for, as on main (`tls: false` or `ssl: "..."` replaces it); such a URL without a host fills in as on main (#45080).
- `hostname`, `host`, `path`, `socket` or five explicit PostgreSQL fields next to `DATABASE_URL=:memory:` or another SQLite URL opened SQLite -> the server. `{ url: "postgres://..." }` next to `MYSQL_URL` ran the MySQL driver on it and timed out -> the scheme of `url` wins over the name of a variable (those parts of #41586).
- SQLite: `?mode=rw` created the file; `?mode=rw&mode=ro`, a `mode=ro` next to a `#` (`?mode=ro#x`, `?a=b#mode=ro`), `?mode=ro` + `{ readonly: undefined }`, `{ readwrite: false }` opened read-write -> read-only (#38417, #45079, #45153). `bigint: true` did nothing -> `safeIntegers` (#41816).
- `socket:` and `?socket=`, both documented, did nothing -> aliases of `path`. `mysql://user:pass@/db?socket=...` threw `Invalid URL` -> URLs without a host parse (#37807, #23954).
- A host that starts with `/` (`hostname`, `PGHOST`, `?host=`, `%2F...`) went to DNS -> socket directory. `sslmode=require` on a PostgreSQL unix socket failed -> ignored there, like libpq.
- PostgreSQL: a `path` that is a directory was dialed as it is -> `<directory>/.s.PGSQL.<port>`. The pathname of `unix:///run/a.sock` was also the database `run/a.sock` -> the default database. `SQLITE://` / `FILE:` in `filename` or in a variable were `Invalid URL` or PostgreSQL -> SQLite, as in the string form. A NUL in `path` was dropped and TCP dialed -> rejected.
- `console.log(sql.options)` printed the password, `tls.key`, `tls.passphrase` -> `[REDACTED]` (#41725). `sql.options.sslMode = "require"` meant `disable` -> the next query rejects (#43818).

#### Query building

- ``where ${[sql`a`, sql`or b`]}`` bound one parameter and matched every row on PostgreSQL -> the fragments are joined. ``sql({ ts: sql`now()` })``, `sql({ n: sql.array(a, "INT4") })` failed -> work.
- The MySQL update helper knew one spelling of `ON DUPLICATE KEY UPDATE` -> any (#32040, #32035). Keywords inside strings and comments confused helpers. Each helper copied and lower-cased the whole text so far (#43789).
- `Buffer` / `Uint8Array` elements in `sql.array` stored garbage -> `\x` hex; a typed array stored `{NaN,NaN}` -> its numbers (#36241).
- `sql({ "-1": 1 })` threw. An identifier used in another client's query was quoted for the wrong dialect (#24050). `sql.unsafe(text, values)` read the caller's array when the query ran.
- `globalThis.Array = ...` before the first use of `Bun.SQL` threw "The superclass is not a constructor" (#32558).

#### PostgreSQL protocol, types, errors

- Every pattern of NULLs in a statement's parameters prepared another statement, and none was ever closed, so backends grew to several GB -> the cache key is the text plus the declared types, NULL fits any (#28980).
- A statement name could end inside a multi-byte character, and two texts with the same first 40 bytes could share one (42P05) (#44042). A text that ends in NUL put the stream out of step; extended batches sent a Flush before Sync (#44784).
- An `int4[]` / `float4[]` with a NULL or more than one dimension was rejected on a binary path (`NULLS_IN_ARRAY_NOT_SUPPORTED_YET`, `MULTIDIMENSIONAL_ARRAY_NOT_SUPPORTED_YET`) -> a plain `Array`, `null` for NULL, `float4` elements widened. The elements decide, not the header's has-nulls flag, which the server leaves set after the last NULL is gone (those parts of #45211, #45062).
- A `numeric` of 131,069+ digits read `""` or `"-"` when sent in binary -> to decode, `numeric` and `time` are asked for in text and their binary decoders are deleted (#45014); `int2[]` and `float8[]` are asked for in binary. The values are the same.
- Text arrays had a parser with its own number, JSON, date and bytea decoders -> a tokenizer that hands each element to the scalar decoder. Fixed by it: explicit bounds, `'[0:2]={1,2,3}'`, `indkey::int2[]` (#43335, #43332); `1e-07`, `1e+20` in float arrays, `12345678901`, `1e5`, `[null]` in `json[]`, `-0` (#43336, #45305); `json[]` nested over 100 deep.
- BC dates were Invalid Date, dates past year 9999 were read in local time on the text paths -> one parser, same instant under every `TZ`.
- 65,536 parameters, and on MySQL the second run of a failed prepare or a wrong parameter count, rejected with a plain object (no `stack`, not `instanceof Error`) (#44118, #43992, #43993). A failing query stayed pending forever when `Error.prepareStackTrace` threw -> `stack` is made on the first read (#44204).
- `PostgresError.column` / `.line` held a position in Bun's own source when the server sent none -> absent (#45151, #45064). `detail`, `hint`, `constraint` ... were UTF-16 bytes read as text when non-ASCII. `severity` was translated on a server with another `lc_messages`.
- The Bind format code came from the list of types Bun can decode, so `numeric`, `float4`, `time` were announced binary and sent as text (08P01) -> binary only where value and type match (`bool`, `int4`, `float8`, `bytea`, `timestamp(tz)`); the rest is text (#41976).
- `Date` into `date` / `time` failed (#41976, #29010). `prepare: false` sent a `Date` as `toString()` and an object as `[object Object]` (#39452, #29010, #30221, #39450). decimal.js / Temporal values into `numeric`, `time` failed; `URL`, `DataView` threw; a bigint outside int64 failed -> `numeric`.
- A CopyBothResponse hung the query -> "Streaming replication is not supported".
- Ten codes that nothing can produce any more are gone: six `ERR_POSTGRES_*` (`*_NOT_SUPPORTED_YET`, `UNSUPPORTED_NUMERIC_FORMAT`, `INVALID_QUERY_BINDING`, `OVERFLOW`, `INVALID_BYTE_SEQUENCE_FOR_ENCODING`), four `ERR_MYSQL_*` (`INVALID_QUERY_BINDING`, `*LOCAL_INFILE*`, `PASSWORD_REQUIRED`).

#### PostgreSQL authentication and TLS

- `?channel_binding=` was forwarded as a startup parameter (42704). A server that offers no known mechanism got a SCRAM-SHA-256 answer anyway -> `ERR_POSTGRES_SASL_NO_KNOWN_MECHANISM`. A mandatory extension (`m=`) is rejected before the proof (#41703).
- A SCRAM iteration count out of bounds failed with `ERR_POSTGRES_INVALID_MESSAGE` "Failed to read data" -> `ERR_POSTGRES_SASL_ITERATION_COUNT_OUT_OF_RANGE` with the count and the bounds (the error of #38133). A GSSAPI / SSPI request showed an unfilled format string -> "GSSAPI authentication is not supported".
- Over TLS the StartupMessage (user, database) was queued when the handshake started -> written once chain and identity are accepted.
- A TLS 1.2 server that renegotiates reports a second handshake: both drivers sent their login again, and the next query got the reply to it -> ignored after the first.

#### MySQL / MariaDB

- Two queries on one connection could resolve with each other's rows when a parameter's `toJSON` started a query (#32005). `BUN_FEATURE_FLAG_DISABLE_SQL_AUTO_PIPELINING=1` hung every prepared query (#44022).
- One INSERT with K nullable columns was up to 2^K server statements, and statements piled up until the server ran out of memory (a production report is on #33190) (#33190, #28980).
- `caching_sha2_password`: the scramble hashed 21 bytes (nonce + NUL), so fast authentication always failed: plain TCP needed `allowPublicKeyRetrieval: true` at every login, not just the first; a password of 20+ bytes failed with errno 1045 -> 20-byte nonce (#33504, #28161, #26195).
- A length that points past its packet's end hung the query or decoded the next packet as data (a phantom row) -> `ERR_MYSQL_MALFORMED_PACKET` (#35118).
- A `Date` before 1970 was rejected -> years 0 to 9999 (#31209). Prepared `TIMEDIFF()`, `SEC_TO_TIME(3661.25)` lost their fraction (#31738). MariaDB: every object or array parameter failed with errno 1210 (#37125). `DataView` was rejected.
- An idle connection that got a query didn't ref the event loop: exit 0 with the query in flight, or a spinning core under top-level await (#38163, #27102). A short `maxLifetime` with a slow handshake rejected the first query.
- Every `close()` counted as an aborted client on the server (`Aborted_clients` +3 after 3 closes -> +0).

#### SQLite adapter

- A valid `SELECT` resolved `[]` (`'%"%'` in the text, `/*c*/select`, `select*from`, `values (...)`), and `INSERT ... SELECT`, `WITH ... INSERT` reported `count` 0 -> the adapter asks SQLite whether the statement returns columns instead of tokenizing (#33583, #30811).
- A text whose first statement returns rows (`sql.unsafe("SELECT 1; INSERT ...")`, a migration file that starts with a `PRAGMA`) ran only that statement -> every statement runs; the result is the first statement's rows. Only the first statement can have parameters: a later one that has any is refused, where main bound NULL or skipped it.
- Named parameters on a nested `sql.unsafe()` were dropped and NULL was bound: `delete ... where name is not ${sql.unsafe("$o", { $o: "bob" })}` emptied the table -> `SyntaxError`. `sql.unsafe("... = ?", 0)` (also `""`, `false`, `0n`) bound NULL -> binds the value. PostgreSQL: a fragment with a second argument that is no array, in front of a parameter, sent `$NaN` -> works (those parts of #44745, #44867).
- More than about 640,000 rows rejected with `RangeError: Maximum call stack size exceeded` (#38438). `sql.flush()` threw -> no-op (#41816).
- Through the adapter too: multi-statement errors (#37418), `byteOffset` (#45229); a NUL in a file name throws from `new SQL()` (#37006).

#### bun:sqlite

- `{}`, `{ create: false }`, `{ readonly: false }`, `{ readwrite: false }` failed with `SQLITE_MISUSE`, `{ create: false, strict: true }` created the file -> the mode comes from `readonly`, `create`, `readwrite` only (#44908, #32422, #9410, #15876).
- `SQLiteError.byteOffset` counted from the failing statement -> from the start of the text (#45229).
- A kept statement returned rows with the old keys, or values under wrong keys, after `ALTER TABLE` (#32841, #1332); `stmt.columnNames` / `declaredTypes` still update at the next run, as in Node. `SELECT 1`: `row["1"]` was `undefined` (#37238, #18326).
- `{ name: 1 }` for `$name` bound NULL (default), `{ $name: 1 }` threw (strict) -> both work (#13409, #18456). Strict `$1` read key `0` (#37240).
- UTF-16 strings: a lone surrogate read back as three U+FFFD, a leading U+FEFF was dropped, a leading U+FFFE byte-swapped the rest (#32841). A whole number from 2^51 on was stored as REAL (#43281). `db.prepare(sql, "x")` ignored the binding (#25472, #45367); a lone value is still dropped unless the statement has one parameter. A bind that threw in `prepare()` kept the file open after `close()` until a GC.
- `break` out of `iterate()` left the cursor open (`SQLITE_LOCKED`, "database is locked") -> reset (#32917).
- A NUL byte in a file name, extension path or schema name cut the string short -> throws (#37006, part of #38514). `Database.setCustomSQLite()` returned `true` where it does nothing (#36371).
- A bind failure was a plain `Error` -> `SQLiteError`. SQL text over 1e9 bytes failed as a whole -> the limit is per statement. System-library builds asked `dlopen` for `sqlite3` -> `libsqlite3.so.0` (#26629).

#### node:sqlite

- `db.close()` / `using db` kept the file and `-wal` / `-shm` open until every `StatementSync` was collected (`EBUSY` on Windows) -> `close()` finalizes the connection's statements and releases the file at once, like Node (#40005, #41890, #40001).
- `stmt.get()` built a new Structure per call (#44103, #44084). A `Proxy` (Vue `reactive()`, MobX), a module namespace or a `String` object as named parameters bound NULL to everything. `applyChangeset()` errors had an `errstr` Node's don't have (#34453).

#### Crashes and memory safety

- PostgreSQL: a query started from a parameter's `toString()` / `toJSON()` on the same connection panicked (`@intCast`) with `prepare: false`, or gave 08P01 plus two queries that never settle -> parameters are converted first, writing Bind runs no JS, and the nested query runs behind the outer one (#43918).
- `sql.options.idleTimeout = -1` (or `"abc"`, `{}`) panicked at the next connection, both drivers (#43818). `run()` on the private PostgreSQL query handle with a missing argument panicked (SQL half of #44897).
- MySQL: a later parameter's `toJSON` that shrank an earlier resizable `ArrayBuffer` segfaulted -> bytes are read after all user code ran (MySQL half of #38289, #38277).
- bun:sqlite: `db.fileControl(op, null)` segfaulted, `(op)` threw -> storage Bun owns (#44089, covers #36301). A `Database` could be closed under its own running `serialize()` (#41611). `RAISE(ABORT, '')` hit a debug assertion (part of #43797).
- bun:sqlite, node:sqlite: a 2^30-character string aborted the process -> `RangeError` (parts of #42868).

#### Memory and performance

- GC cells per awaited `select 1` (release): PostgreSQL 84 -> 28, MySQL 76 -> 27, SQLite 52 -> 33 (whole PR; #44105, #44315). Per cached PostgreSQL query: 47,770 -> 23,291 instructions (-51 %).
- A bulk insert of 1,000 x 10, end to end (release, 43ad527e44, the union of keys still in): PostgreSQL -38.0 %, MySQL -52.6 %; with one `undefined` cell +2.1 % and -15.7 %.
- The PostgreSQL read buffer was never compacted while reads ended inside a message (rows larger than a socket read): a 1,000 MiB COPY stream grew RSS by 1,235 MB without the fix. Now (release): 255 MiB/s, peak RSS 59 MiB.
- bun:sqlite (release): `all()` per row, `get` by key and an insert of 3 ints cost 4,613, 8,375 and 4,489 on main, now 3,225, 6,502 and 3,381; 29 of 31 cases are cheaper. Rows of 63+ columns made one Structure per row -> one per statement, 1,665 -> 310 per cell (#31669); an `exec()` of 80,000 statements 5.34 -> 0.11 s of CPU (#45207).
- bun:sqlite: the `Database` is a GC cell that owns its connection (#41611), so dropped `deserialize()` databases and failed opens (#34898) no longer pile up: 40,000 of the first +3,016 -> +3.9 MB. #28911's `db.query()` loop 953 -> 92 MB; text over 64 KB isn't cached (#28912, #28911). Workers shared SQLite's malloc mutex -> configured once per process, `MEMSTATUS` off and `MULTITHREAD` (#44197).
- node:sqlite (release): a 5-column `get()` 13,458 -> 4,077 (#44103); all 10 cases are cheaper.

#### Tests and CI

- **The PostgreSQL test containers crash-restarted under load** (57P03 "the database system is in recovery mode"). We infer: docker kills the `sh -c pg_isready` health check at its 5 s timeout, the postmaster (PID 1) adopts the orphan and takes its exit 2 for a crashed backend. `test/docker/docker-compose.yml` now has an exec-form check and `init: true`.
- `sql-tls-ip-literal-host.test.ts` failed 16 of 108 runs on main (mock on 127.0.0.1, client dialed `::1`) -> 0.
- `postgres_auth` had the md5 and SCRAM verifiers swapped and no test used it -> fixed; the login tests are in `test/js/sql/postgres-auth.test.ts`.
- MariaDB runs the whole `sql-mysql.test.ts` matrix. `prestart-map.mjs` is complete (#35912, #44043), and `test/internal/prestart-map.test.ts` fails when a test's container is missing. The `isDockerEnabled()` wrappers are gone, so `BUN_TEST_SERVICE_*` overrides run the suites (#37123, SQL part of #39850).
- Ported test-only PRs: #36948 #37114 #38221 #40193 #40194 #40537 #40633 #41104 #41176 #42587 #44035 #44850.

#### Docs and types

- `docs/runtime/sql.mdx` was rewritten.
- Types: ``await sql`...` `` carries the result metadata (`SQL.ResultMetadata`) (#40434, #30037); `release()` is `Promise<void>` (#43255); `SavepointSQL` has `savepoint()`; bun:sqlite options accept `undefined` under `exactOptionalPropertyTypes` (#45079).
- `onconnect` / `onclose` were documented as receiving a client -> an error or `null` (#38625, #38634). `timestamp` decodes as UTC (#39881, #39879). Multi-statement files are atomic on PostgreSQL only (#41744). Also #41813 (SQLite codes, placeholders, MySQL DDL), #44998 (what a savepoint holds), #44373 (defaults), #42206 (SQL half), #41094.
- bun:sqlite: examples call `db.run()`, not the deprecated `db.exec()` (#24482); typings and docs for `safeIntegers()` (#26627), `isFinalized`, `toJSON()`, `clearQueryCache()`; `get()` / `all()` without arguments reuse the last bound values (#31747, #26622).

### Found and not fixed

"Also on main" is marked (m).

- **Worth a close read:** `signature_digest_nid` in `src/boringssl_sys/boringssl.rs` is new unsafe FFI over a certificate the peer chooses, and `on_handshake` now runs user code.
- **node:sqlite, macOS:** #45171 (read-only open of a WAL database whose sidecars are gone) isn't fixed and gets easier to hit, because every `close()` is now a real close.
- **Options, decided by the maintainer: as on main.** `NODE_TLS_REJECT_UNAUTHORIZED=0` also switches off `sslmode=verify-ca` / `verify-full` (#41589). `new SQL({ hostname })` takes the other fields of an environment URL, its user and password too (#41586). A `TLS_*` URL is taken as written: `?sslmode=disable` or `tls: false` make it plaintext. `PGDATABASE` / `MYSQL_DATABASE` / `MARIADB_DATABASE` beat the URL's database (#45276, #45287). The hardening was in this PR, is out again, and stays open in those pull requests.
- **Pool (m):** no lazy or `min`-sized pool (#30631, #30632, #30636), no `AbortSignal` (#23175). Queries assigned to a connection but not sent yet die with it (#44924). At `max: 1` with a `BEGIN` by hand, `idleTimeout` / `maxLifetime` can close the connection between two statements (documented). Other callers' queries already sent behind a query that leaves a transaction open are rolled back with it.
- **`--hot`:** a kept pool that nobody asks for a connection during a whole load has its idle connections closed and dials again on demand. An uncleared `setInterval` of an earlier load that queries makes its old pool fill again (m). `listen()` callbacks of earlier loads keep running (m).
- **cancel():** a running PostgreSQL query with another one written behind it rejects at once but runs to its end on the server, as on main. MySQL / MariaDB (m): a query on the wire runs to its end. No `KILL QUERY` is sent: it names a session, and a late kill hit the session's next query in 34 % to 88 % of our tries, depending on server and set-up (#44625).
- **MariaDB XA**, `max > 1` (m): the connection that prepared a branch answers other callers with 1399, and `commitDistributed()` elsewhere gets 1397. New: `reserved.beginDistributed()` directly followed by `reserved.release()` closes the connection.
- **PostgreSQL (m):** `real`, `int4[]` and `float4[]` follow the wire format: `0.1` / `Array` in text, `0.10000000149011612` / a typed array in binary (#41888, #45211). A string bound to `json` / `jsonb` is stored as a JSON string when prepared, like postgres.js, and sent as it is with `prepare: false`, like pg; so `${JSON.stringify(obj)}` stores a string (#28819, #40944). Arrays of user-defined types read as the literal `"{a,b}"` (#41040), composites as `"(1,q)"` (#20379). A fractional number into `numeric` keeps 15 digits, a bare number into `json` / `money` fails (42804). `prepare: false`: a `Date` into `time`, `json`, `jsonb` is rejected.
- **PostgreSQL auth:** `prefer` doesn't stop a server from asking for a cleartext or md5 password; `require` does. (m): the SCRAM iteration count must be within 4096..10,000,000, deliberate hardening; libpq, postgres.js and pg accept any count >= 1. Parity is the range check in the SASLContinue arm of `PostgresSQLConnection.rs` (#38133).
- **MySQL:** `sha256_password` over a unix socket still needs `allowPublicKeyRetrieval: true`. (m): FLOAT reads `0.1` from `.simple()`, `0.10000000149011612` prepared, like mysql2 (#41888); BIGINT above 2^31 is a string; after `USE` a cached text still runs in the OLD database, silently; a multi-statement text that `KILL QUERY` hits between two statements never settles (`maxLifetime` bounds it).
- **SQLite:** on every adapter `transform.undefined` skips `sql.unsafe()` values. `db.prepare("a; b").run()` runs only `a`, like node:sqlite (documented).
- **Not reproduced on Linux, no claim:** #24130 #24845 #24434 #23305 #30494 #16844 #17173 #23654 #32099.

### Decisions reversed while writing this

- `--hot` was first going to close the old load's connections; the maintainer overruled it. "Close when the settings changed" then closed pools the program still used; now use decides.
- The MySQL statement cache was going to be keyed on the text alone, like mysql2 and mariadb. MySQL >= 8.0.22 settles a parameter's type at its first non-NULL value, so `WHERE name = ${"bob"}` after `${5}` returned wrong rows: one statement per text and set of non-NULL types.
- Ed25519 under `prefer` was going to fall back to unbound SCRAM, as in #41703; psql 15 fails, and a fallback lets whoever picks the certificate switch the binding off.
- `SQLITE_DEFAULT_WAL_SYNCHRONOUS=1` (#20662) was in and is reverted: an upgrade must not lower the durability of a COMMIT.
- On the maintainer's decision: a bulk insert takes the first row's keys as its columns, as on main and in postgres.js, not the union of all rows' keys (half of #35111); `int4[]` / `float4[]` and `real` follow the wire format, not one form on every path (#45211, #41888); `console.log(rows)`, `Object.keys(rows)` and a spread list `count`, `command`, `lastInsertRowid`, `affectedRows`, as on main (#38443; `columns` and `statement`, new, are not listed); MySQL's default database stays `mysql`.
- Five more are main's again, because main works there and nobody asked: a failing query that nobody handles no longer ends the process; the first query fills the pool to `max` (the lazy pool, #30636); a caller whose dial is refused waits for a connection that is reserved or in a transaction; PostgreSQL `.raw()` returns main's bytes, not text; in `sql.array(values, "JSON" | "JSONB")` `null` is the JSON value and a nested array a dimension.
- Taken out before the merge, because main works there. Values: a string into `json` / `jsonb` sent as it is (#40944), a JS array into `text` as an array literal, `Infinity` untyped, typed arrays by the server's type, `foundRows: true` by default, `not in (NULL)` for an empty list on SQLite, the result mode fixed at `execute()`. Errors: for an `async` `db.transaction()` callback (#45132), `parts.map(sql.unsafe)`, `sql.unsafe(text, 0)` (#44745, #44867), `new Database(path, true)`, `{ readonly: true, create: true }` on the SQLite adapter, `prepare: false` on MariaDB. Options: `?` inside a plain SQLite file name (#38427), `new SQL("")` reading the environment.

### From outside contributors

PRs by people, team members included. Every item is reimplemented from the idea unless it says otherwise.

- #40913 @dylan-conway: his mechanism as it is (`onconnect` at the end of the read, only if still connected), ported by hand to both drivers. Also the error of his #38514.
- #25623 @eriklangille: the diagnosis in #23215 and the goal, reuse across `--hot` reloads. Other mechanism: connections move between pools in `pool.ts`, no GC hook.
- #23350 @gohryt: the request for COPY and the scenarios to test. Other API.
- #36451 @pjb3: the `transform` option on all adapters, with postgres.js's directions, applied to the row shape.
- #8558 @nikeee, #25703 @jdjkelly: user-defined functions; the name `function`, option names, arity rule, test ideas.
- #12631 @jecquas: `sqlite3_update_hook`, in the shape its review suggested.
- #31669 @alii: one cached Structure for rows wider than 62 columns. #31209, #31738 @alii: `Date` parameters before 1970, fractional seconds of binary TIME.
- #43789 @ralyodio: the diagnosis that `detectCommand` copies and lower-cases the whole text per helper. #45151 @RubenPari: the cause (every JSC `Error` has its own `line` / `column`) and the `delete`.
- #26711 @RajeshKumar11: `PGUSERNAME`. #45287 @wahajahmed010 (the URL's database above `PGDATABASE`) stays open: decided as on main.
- #22109 @himself65: `Symbol.for("sqlite-type")`. #26627 @0xh3x: `safeIntegers()` typings. #31747 @Artoria2e5: the JSDoc correction. #24482 @jobansd: `exec` -> `run`, the same 15 edits. #41094 @deepshekhardas: trailing spaces.
- Not taken, with thanks (reasons below): #26503 @S4N-T0S, #31751 @EffortlessSteven, #27442 @sosukesuzuki (cases of both are tests now), #22934 @nektro, #16884 @chrisbenincasa, #25836 @alimd, #26880 @theshadow27, #31078 @countradooku, #25403 @abelcha, #44854 and #44860 @deepshekhardas.
- Not in this set: #41890 @steipete (only statements a `StatementSync` owns may be finalized), #28161 @kernoeb (found the 21-byte nonce first). Reports and measurements: @bompus (#44084, #44187), @gerardp (#35120, his burst script is a test), @Dex4Sure (#38163), @filipesarturi (#33190), @KilianB (#30037).

### Replaces

#8558 #12631 #22109 #23350 #24482 #25623 #25703 #26627 #26711 #28912 #30037 #30648 #30848 #31209 #31669 #31738 #31747 #32040 #32100 #32422 #32558 #32841 #32917 #33189 #33190 #33370 #33504 #33579 #33583 #33740 #34453 #34898 #35111 #35117 #35118 #35120 #35912 #36241 #36301 #36371 #36451 #36948 #37006 #37114 #37123 #37125 #37238 #37240 #37418 #37807 #37819 #37960 #38163 #38219 #38220 #38221 #38417 #38438 #38468 #38625 #38634 #39452 #39881 #40005 #40193 #40194 #40434 #40537 #40633 #40913 #41042 #41051 #41094 #41104 #41176 #41301 #41570 #41605 #41611 #41703 #41725 #41744 #41758 #41813 #41815 #41816 #41817 #41886 #41970 #41976 #42587 #42637 #43116 #43205 #43249 #43255 #43257 #43261 #43263 #43281 #43293 #43306 #43335 #43336 #43652 #43789 #43818 #43918 #43958 #43959 #44022 #44035 #44042 #44043 #44089 #44103 #44105 #44118 #44197 #44204 #44315 #44373 #44483 #44625 #44646 #44784 #44799 #44850 #44908 #44932 #44938 #44983 #44998 #45014 #45065 #45079 #45080 #45096 #45111 #45118 #45151 #45153 #45160 #45207 #45229 #45305 #45332 #45367 #45387

### Closed without porting

- #16884: the compile option is already on main
- #22934: those suppressions are already gone (#30875)
- #25403: would make the private adapter interface public
- #25836: part landed in #43649, two lines mistype
- #26503: four claims already fixed on main; default `sslmode` stays `disable`
- #26880: superseded by the author's own #26884
- #27442: already fixed on main (#35246)
- #31078: nothing can call `interrupt()` while a statement runs
- #31751: no observable bug on a real server
- #34435: `numeric` is read as text; binary decoder deleted
- #34673: its Structure slots are never freed on eviction
- #35738: the mock repeats a real-server test
- #35753: duplicate export already removed (#44614)
- #37544: main already holds statements in `RefPtr` (#40516)
- #37620: its leak was fixed on main (#40238)
- #44040: superseded by #44105's synchronous start
- #44854: makes the page's spelling less consistent
- #44860: makes the guide's wording less consistent

### Left open

- #26884: backup API is a product decision
- #30636: main's docs promise the eager fill; a lazy pool is a product decision
- #34281: `mkdir -p` on open is a product decision
- #34863: `AsyncDatabase` is a product decision
- #36712: the `better-sqlite3` alias is a product decision
- #37013: SQL part obsolete since #44618; the rest is not SQL
- #38133: the SCRAM floor is kept; only its better error is here
- #38289: MySQL half is here; `Bun.Image` is not SQL
- #38427: its `url` half is here; the `?` half changes what main opens
- #38443: `console.log(rows)` keeps showing the four properties, as on main, decided
- #38514: bun:sqlite part is here; the rest is not SQL
- #39850: SQL gates are here; the rest is not SQL
- #40250: the SQL code it repairs is deleted here; the rest is not SQL
- #40944: main works, like postgres.js; the change breaks stored data
- #41586: two parts are here; the rest is decided: as on main (Limits)
- #41589: decided: as on main (Limits)
- #41888: `real` follows the wire format, as on main, decided
- #42054: SQL half is here; the Redis half is not
- #42206: SQL half is here; the `nodejs-compat` half is not
- #42868: SQLite parts are here; the rest is not SQL
- #43797: SQLite half is here; the V8 addon half is not
- #44745: its SQLite part is here; `parts.map(sql.unsafe)` works on main and in postgres.js
- #44867: its SQLite part is here; on the servers `sql.unsafe(text, 0)` runs on main
- #44897: SQL half is here; the node:http2 half is not
- #44924: handing unsent requests back can half-commit at `max: 1`; needs a maintainer's yes
- #44962: SQLite 3.54.0 should merge, and revert, alone
- #45132: an `async` callback without `await` works on main
- #45211: NULLs and dimensions on the binary paths are here; typed arrays stay, decided
- #45287: decided: as on main (Limits)
- #45437: a source break in the types, on its own

### Partly addressed

- #39877: a bare key binds; an unknown key in default mode still binds NULL (`strict: true` throws).
- #43113: not reproduced; the one route found to its errors (an open `iterate()` cursor) is closed.
- #19130, #40077: `expect()` no longer hangs on a lazy `Query`; #19130's own script (Windows) didn't hang on Linux, #40077's other items are untouched.
- #27102: the process no longer exits with a query in flight; its `CONNECTION_CLOSED` under load wasn't reproduced. #38277: MySQL half only.
- #15088: its COPY item. #15087: `SQL.toCamel` and friends cover its SQL use. #18866: `columns` and `statement`, not `state`. #23175: `cancel()` works, no `signal`. #16665: `new Bun.sql(url, options)` applies the options.
- #39450: Date and object are fixed; a Date into `time` / `json` with `prepare: false` still differs.
- #28819, #40942: not changed, see Limits; `sql.json()` and the docs now say how to store each kind of value.
- #26629: changed by reading, no such build was made. #16717: documented (macOS reports Apple's version). #26369: already fixed on main (#44618).
- #44187: memory statistics and the connection mutex are gone; scaling like Node was measured on a loaded box only.
- #20662: not changed; the docs give the `PRAGMA synchronous = NORMAL` tip.
- #24662: async support isn't added; only a promise that is already rejected at the return rolls back, and the docs warn.
- #45276: not changed, decided as on main (Limits).

### Issues fixed

Fixes #1332.
Fixes #1474.
Fixes #4175.
Fixes #5051.
Fixes #9410.
Fixes #13409.
Fixes #15876.
Fixes #16469.
Fixes #18326.
Fixes #18456.
Fixes #23215.
Fixes #23954.
Fixes #24050.
Fixes #25405.
Fixes #25472.
Fixes #26195.
Fixes #26622.
Fixes #26684.
Fixes #26809.
Fixes #28911.
Fixes #28980.
Fixes #29010.
Fixes #29484.
Fixes #29551.
Fixes #30221.
Fixes #30646.
Fixes #30811.
Fixes #30843.
Fixes #32005.
Fixes #32035.
Fixes #32038.
Fixes #32096.
Fixes #32148.
Fixes #37415.
Fixes #39879.
Fixes #40001.
Fixes #40432.
Fixes #41010.
Fixes #41039.
Fixes #41050.
Fixes #41242.
Fixes #41740.
Fixes #41856.
Fixes #42720.
Fixes #42804.
Fixes #44084.
Fixes #44367.
Fixes #45039.
Fixes #45062.
Fixes #45064.
Fixes #45275.
@Jarred-Sumner

Copy link
Copy Markdown
Collaborator

do_cancel was an empty stub and BackendKeyData threw the key away, so a cancelled pg_sleep ran on and resolved. #45304 implements cancel() with the design of this PR, on top of a rewritten request dispatcher.

Kept: the connection decides by wire position. A query that is not written leaves the queue and rejects with ERR_POSTGRES_QUERY_CANCELLED. The running head, when nothing that was not cancelled is written behind it, gets a CancelRequest on a second connection made by open(): to the session's peer address, through TLS when the session has TLS, and the key never reaches JS. A query written behind the head rejects with the hint. A 57014 during Parsing resets the statement.

The open question got libpq's answer. The session writes nothing until the server has closed the cancel connection, so a late signal cannot hit the next caller's query on a pooled connection.

What differs: without BackendKeyData, or when the request cannot be delivered, the query rejects locally with the hint instead of running on. A cancel while only the Parse is on the wire rejects at once. A query that still waits for a pool connection leaves the pool's queue, and q.cancel(); await q rejects instead of hanging.

test/js/sql/postgres-connection.test.ts has two "cancel()" groups: a scripted server for the exact bytes, TLS and "the session writes nothing until the server has closed the second connection", and real servers, with "cancel() stops a query on a verify-full session" on postgres_tls. Most of the 31 tests of postgres-query-cancel.test.ts were kept in substance, rewritten on one scripted server. The FFI full-backlog fixture was dropped.

One more rule: a CancelRequest names a backend, so it can stop the query that is already written behind the cancelled head when the head ends just as the signal arrives. Running such a victim again doubled a write in our tests (a CALL that commits), so no request goes out unless everything written on that connection was cancelled. Otherwise cancel() rejects locally and the server finishes, as on main ("of a query with another one written behind it asks for nothing, and that one runs once"). #32149 is closed, and its successor #44799 is in #45304 too. Queries are not AsyncDisposable (@alii's question). #23175 (AbortSignal) stays open, now with a cancel() to build on.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants