Skip to content

sql: close() gives the queries that started before it to the pool first - #44040

Closed
robobun wants to merge 7 commits into
robobun/530aba27/sql-close-escalatefrom
robobun/f2d11453/sql-close-drains-same-tick-queries
Closed

robobun wants to merge 7 commits into
robobun/530aba27/sql-close-escalatefrom
robobun/f2d11453/sql-close-drains-same-tick-queries

Conversation

@robobun

@robobun robobun commented Sep 26, 2026 •

Copy link
Copy Markdown
Collaborator

Part of #43887

Problem

  • The docs promise await sql.close(); // await all queries to finish (docs/runtime/sql.mdx:976, packages/bun-types/sql.d.ts:683). A query that starts in the tick of close() rejects with ERR_*_CONNECTION_CLOSED and is never sent.
  • then(), catch(), finally() and run() give the query to the pool one promise job later (#runAsync, src/js/internal/sql/query.ts). close() looks for pending queries at once.
  • No user reported this. A fuzz run found it. Workaround: query.execute().

Fix

Background

Downsides

  • For a started query, close() now opens a pool that has no connection: up to max sockets and password() calls, and a wait of up to connectionTimeout.
  • q.then(); sql.close(); q.cancel() on a connected pool now sends the query.
  • A pool query runs 36 to 38 more bytecode instructions. .bun_builtins grows by 2,003 B.
Notes

Guarantee.

  • Runs: a pool query on which then(), catch(), finally(), run() or execute() was called before close(), end() or Symbol.asyncDispose. Also the statement of sql.commitDistributed() and sql.rollbackDistributed().
  • Still rejected: a query that starts after close(). A query that only await, Promise.all(), Promise.race() or Promise.resolve() starts, because they call then() in a later promise job. Promise.all([q, sql.close()]), where close() runs before Promise.all touches the query.
  • close({ timeout: 0 }) closes at once and sends nothing.
  • postgres.js 3.3.5 gives the same results for q.then(); sql.end(), for a start after end(), and for a query that only await starts. Measured against a local PostgreSQL on Node.js and on Bun.

Open decisions for a maintainer (asked on #43887).

  • Which design: this PR, sql: start a query in the call of then(), catch(), finally() and run() #44105, or no change.
  • SQLite: close() runs no started query while the callback of a sql.begin() has its transaction open. The statement would run inside that transaction, and close() rolls the transaction back. The query rejects as before. If the answer is "run it anyway", the exception and its test go away.
  • SQLite: SQLiteAdapter.close() ignored timeout before. It now reads a timeout that is loosely equal to 0 as "do not run the started queries". It validates nothing.

Mechanism.

  • The list is linked through the queries ([_nextStarted]). Its two ends are on the adapter (firstStarted, lastStarted). A start allocates nothing. A close() visits only the queries of its own pool.
  • After the one job, the query takes itself out of the list. Promise jobs run in the order in which they were queued, so the query is the first one in the list. A debug build asserts it.
  • The one job is now await undefined. To await a promise reads promise.constructor, and code of the caller can run there (an accessor on Promise.prototype). It could start a query inside the start of another query.
  • handOffStartedQueries(adapter) sets the status bit handedOff and calls the handler of the query. When the one job of that query ends, the query sees the bit and does nothing more.
  • A query of a transaction or of a reserved connection runs on that connection and never enters the list.
  • A hand-off can run code of the caller (a function-valued password), and that code can call close(). BaseSQLAdapter.close() reads closed after the hand-off. When the hand-off closed the pool, it returns the pending close of sql: a later close() waits for the pending close, for at most its timeout #43959. SQLiteAdapter.close() reads _closed again after the hand-off.
  • SQLiteAdapter.close() reads options.timeout before it reads _closed. A getter can call close() there.
  • SQLite reads db.inTransaction only when a query is in the list, and inside try. Bun.ModuleGraph.dispose() closes the database under the adapter, and the read then throws.
  • SQLite: when the database did not open, the hand-off rejects the started query with the error of the open (SQLITE_CANTOPEN), as execute() does.
  • sql.commitDistributed() and sql.rollbackDistributed() ended in return await sql.unsafe(...). That starts the query one promise job after the call. They now call .then() on the query, which starts it in the call.

Measurements. Release builds of the base branch (#43959) and of this PR from the same tree. Only four files in src/js differ.

Measurement Base PR
Bytecode that runs in #runAsync for each pool query 60 92, or 94 when other starts are in the list
The same for each query of a transaction or a reserved connection 60 69
Bytecode that runs in the field initializer of Query, every query 38 42
Heap cells for each await q: SQLite, PostgreSQL, MySQL 45, 83, 76 44, 82, 75
Heap cells for each q.execute(): SQLite, PostgreSQL, MySQL 43, 82, 75 43, 82, 75
Heap cells for each await tx\...``: SQLite, PostgreSQL, MySQL 68, 71, 64 67, 70, 63
Microtask jobs for each await q: SQLite, PostgreSQL 5, 11 5, 11
Microtask jobs for each q.execute(): SQLite, PostgreSQL 4, 10 4, 10
Heap after GC, after a burst of 200,000 starts 2.26 MB 2.27 MB
Bytecode size of #runAsync 90 instructions, 547 B 133 instructions, 779 B
Bundled query.js, shared.js, sqlite.js, sql.js 96,639 B 98,642 B
Binary .text 58,137,948 B 58,137,948 B
Binary .bun_builtins 2,614,884 B 2,616,887 B
  • So each pool query runs 36 more instructions (32 + 4), or 38 in a burst. A query of a transaction runs 13 more. A query that execute() starts runs 4 more.
  • The promise that each start saves is the one that Promise.$resolve() made.
  • Executed bytecode: the basic blocks on the path of each case, from BUN_JSC_dumpGeneratedBytecodes=1.
  • Heap cells: heapStats().objectTypeCounts, slope between 500 and 1,500 queries, types with an integer slope.
  • Microtask jobs: gdb counting breakpoint on JSC::runInternalMicrotask, slope between 1,000 and 2,000 queries.
  • Wall-clock and CPU time are not usable. The host had a load average of 130 to 600 on 16 cores during the runs. perf, valgrind, strace, bloaty and hyperfine are not installed in the build container, so there are no counts of native instructions or of syscalls.

What changes besides the bug. Each row has a test.

Case Base This PR
A started query, a pool with no connection, close() Rejected. password() not called Resolves. password() called max times, onconnect and onclose in pairs
The same, and the server never answers ERR_*_CONNECTION_CLOSED at once ERR_*_CONNECTION_TIMEOUT after connectionTimeout
The same, and the port refuses the connection ERR_*_CONNECTION_CLOSED ERR_*_CONNECTION_REFUSED
q.then(); sql.close(); q.cancel(), connected pool ERR_*_QUERY_CANCELLED, not sent Sent, resolves
The same, a pool with no connection ERR_*_QUERY_CANCELLED, not sent ERR_*_QUERY_CANCELLED, not sent
A function-valued password, when close() opens the pool Not called Called in the async context of close()
close({ timeout }) that expires, with a started query Rejected, not sent Sent, then rejected when the timeout ends
A started query, a transaction or a reservation has the only connection Rejected Runs after them. Settle order: query, then close()

A pool has no connection when it never connected, and also after idleTimeout closed its connections.

Tests.

  • The pins are the tests that pass with and without the fix. They pin the promise job in which execute(), then(), catch(), finally() and run() reach the database and settle. The other ways to start a query are pinned relative to then(). Each pin fails when its property is broken. If sql: start a query in the call of then(), catch(), finally() and run() #44105 is the choice, these pins go away with this PR.
  • PostgreSQL and MySQL use a real server (describeWithContainer, postgres_plain and mysql_plain) in a new file, sql-close-started-queries.test.ts. Each test writes rows with an id of its own, and a second pool reads them after the close. Three cases per driver need a mock: a timeout that expires with a sent query, a server that never answers, a refused connection.
  • The two test files: 386 pass with the PR. 75 fail on the base: 26 in sqlite-sql.test.ts and 49 in sql-close-started-queries.test.ts.
  • test/js/sql/: the same tests fail with the PR and on the base in this container. Two leak fixtures time out in a debug build, and the local MariaDB words two error messages differently from MySQL.
  • test/integration/bun-types/bun-types.test.ts: 21 pass.

Self-review. Two reviews, 25 concerns, 21 addressed.

  • The first review found two defects in an earlier head, and both have a test now: a statement could run twice when Promise.prototype.constructor was replaced, and close() threw after Bun.ModuleGraph.dispose().
  • The second review proposed the other design (sql: start a query in the call of then(), catch(), finally() and run() #44105). It also found two defects in this one, and both have a test now: onclose fired twice on SQLite when a getter for timeout called close(), and a started query got ERR_SQLITE_CONNECTION_CLOSED in place of the error of an open that failed.
  • Rejected: .execute() in sql.commitDistributed() and sql.rollbackDistributed(). Measured on PostgreSQL: with .execute(), a call inside onclose fails with "connection must be a PostgresSQLConnection", and a wrapped sql.unsafe that returns a plain promise throws TypeError. .then() keeps both cases as they are.
  • Open: a close() inside onclose with a started query. The hand-off reaches the connection that is still closing, and the query rejects with "connection must be a PostgresSQLConnection". The base rejects it with ERR_POSTGRES_CONNECTION_CLOSED. With sql: finish the pool slot's close transition before calling the user's onclose #43958 applied the query runs on a new connection, so sql: finish the pool slot's close transition before calling the user's onclose #43958 must merge first.
  • Open: two test gaps. No test reaches the hand-off on a pool whose connections idleTimeout or maxLifetime closed. Seven clauses have no test that fails without them, for example the two halves of the guard in BaseSQLAdapter.close().
  • Open: the decision to hand off is written in BaseSQLAdapter.close() and in SQLiteAdapter.close(). The review asks for one place.

Other PRs.

Not in this PR.


[human-review] gate passed · iteration 1 · 8 files touched

fails on main (without fix)
ASAN without fix: 75 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/sql-close-started-queries.test.ts test/js/sql/sqlite-sql.test.ts
bun test v1.4.3 (367d939d9)

test/js/sql/sqlite-sql.test.ts:
(pass) Connection & Initialization > common default connection strings > should parse common connection strings [69.15ms]
(pass) Connection & Initialization > should connect to in-memory SQLite database [11.01ms]
(pass) Connection & Initialization > should connect to file-based SQLite database [44.62ms]
(pass) Connection & Initialization > should handle connection with options object [131.72ms]
(pass) Connection & Initialization > onconnect and onclose callbacks are invoked for SQLite [16.95ms]
(pass) Connection & Initialization > onconnect receives Error when open fails (readonly non-existent) [28.20ms]
(pass) Connection & Initialization > should create database file if it doesn't exist [35.07ms]
(pass) Connection & Initialization > should work with relative paths [35.94ms]
(pass) Connection & Initialization > Environment Variable Handling > should use DATABASE_URL for SQLite when it's a SQLite URL [
... (truncated)

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

test/js/sql/sqlite-sql.test.ts:
(pass) Connection & Initialization > common default connection strings > should parse common connection strings [2.29ms]
(pass) Connection & Initialization > should connect to in-memory SQLite database [0.42ms]
(pass) Connection & Initialization > should connect to file-based SQLite database [1.53ms]
(pass) Connection & Initialization > should handle connection with options object [2.63ms]
(pass) Connection & Initialization > onconnect and onclose callbacks are invoked for SQLite [0.53ms]
(pass) Connection & Initialization > onconnect receives Error when open fails (readonly non-existent) [0.84ms]
(pass) Connection & Initialization > should create database file if it doesn't exist [15.37ms]
(pass) Connection & Initialization > should work with relative paths [14.34ms]
(pass) Connection & Initialization > Environment Variable Handling > should use DATABASE_URL for SQLite when it's a SQLite URL [22.85ms]
(pass) Connection & Initialization > Environment Variable Handling > should handle DATABASE_URL with :memory: [0.71ms]
(pass) Connection & Initialization > Environment Variable Handling > should han
... (truncated)
passes on PR (with fix)
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/sql-close-started-queries.test.ts test/js/sql/sqlite-sql.test.ts
bun test v1.4.3 (367d939d9)

test/js/sql/sqlite-sql.test.ts:
(pass) Connection & Initialization > common default connection strings > should parse common connection strings [120.29ms]
(pass) Connection & Initialization > should connect to in-memory SQLite database [22.67ms]
(pass) Connection & Initialization > should connect to file-based SQLite database [71.49ms]
(pass) Connection & Initialization > should handle connection with options object [152.37ms]
(pass) Connection & Initialization > onconnect and onclose callbacks are invoked for SQLite [16.37ms]
(pass) Connection & Initialization > onconnect receives Error when open fails (readonly non-existent) [201.38ms]
(pass) Connection & Initialization > should create database file if it doesn't exist [69.67ms]
(pass) Connection & Initialization > should work with relative paths [64.03ms]
(pass) Connection & Initialization > Environment Variable Handling > should use DATABASE_URL for SQLite when it's a SQLite URL
... (truncated)

release with fix: all passed
$ bun scripts/build.ts --profile=release
[configured] bun-profile → bun (stripped) in 3901ms (unchanged)
ninja: Entering directory `/workspace/bun/build/release'
[1/209] gen JS modules (bundle-modules)
Preprocess modules (9441ms)
Bundle modules (696ms)
Postprocesss modules (173ms)
Bundle Functions (1243ms)
Generate Code (54ms)

[11.62s] Bundled "src/js" for production
  2599 kb
  197 internal modules
  13 native modules
  50 internal functions across 16 files
[2/90] build.rs build_script_build
[3/90] rustc bun_core 
[4/90] rustc bun_platform 
[5/90] rustc bun_safety 
[6/90] cxx obj/src/jsc/bindings/BunProcess.cpp.o
[7/90] rustc bun_boringssl_sys 
[8/90] rustc bun_zlib_sys 
[9/90] rustc bun_base64 
[10/90] rustc bun_cares_sys 
[11/90] rustc bun_errno 
[12/90] rustc bun_ptr 
[13/90] rustc bun_brotli 
[14/90] rustc bun_clap 
[15/90] rustc bun_zstd 
[16/90] rustc bun_picohttp 
[17/90] rustc bun_output 
[18/90] rustc bun_shell_parser 
warning: `feature(generic_const_exprs)` is not supported with the next-generation trait solver
 --> src/shell_parser/lib.rs:1:30
  |
1 | #![feature(adt_const_params, generic_const_exprs, allocator_api)]
  |                              ^^
... (truncated)
diff hotspot
docs/runtime/sql.mdx                          |  12 +
 packages/bun-types/sql.d.ts                   |   9 +
 src/js/bun/sql.ts                             |   6 +-
 src/js/internal/sql/query.ts                  |  51 +-
 src/js/internal/sql/shared.ts                 |  11 +
 src/js/internal/sql/sqlite.ts                 |  45 +-
 test/js/sql/sql-close-started-queries.test.ts | 522 +++++++++++++++++++++
 test/js/sql/sqlite-sql.test.ts                | 647 +++++++++++++++++++++++++-
 8 files changed, 1297 insertions(+), 6 deletions(-)

gate history · 1 passed · 1 rejected · iteration 1

evidence per changed file
file                                           reads  edits  tests
docs/runtime/sql.mdx                               3      4     87
packages/bun-types/sql.d.ts                        2      2     80
src/js/bun/sql.ts                                  2      0     88
src/js/internal/sql/query.ts                      11      9     85
src/js/internal/sql/shared.ts                      4      1     83
src/js/internal/sql/sqlite.ts                      3      2     82
test/js/sql/sql-close-started-queries.test.ts      0      0      4
test/js/sql/sqlite-sql.test.ts                     9     10     78

A query is lazy. execute() gives it to the pool at once. then(), catch(),
finally() and run() give it to the pool one promise job later. `await query`
gives it to the pool two promise jobs later.

No test covered this timing. No test covered the job in which each start
settles, the order of the starts, cancel() in the tick of the start, run(),
the unhandledRejection events of a failed query, a start inside onclose, or
the async context that a function-valued password observes.

These tests pass with no change to src.
SQLite tests are in sqlite-sql.test.ts. PostgreSQL and MySQL tests use a
real server (describeWithContainer). Each test has a table of its own, and
a second pool reads the table after the close. A row shows that the server
got the statement.

Three cases per driver need a mock: a close({ timeout }) that expires with
a sent query, a server that never answers, and a refused connection.

The "Query start" pins keep the exact promise job only for execute(),
then(), catch(), finally() and run(). The other ways to start a query are
pinned relative to then().

The docs and the JSDoc of close() say which queries close() waits for.
@robobun

robobun commented Sep 26, 2026 •

Copy link
Copy Markdown
Collaborator Author

Status

Draft. It is one of two designs for #43887. The decision that it needs is in #43887 (comment). The other design is #44105, which is smaller and which I recommend.

How to reproduce

No server is necessary:

import { SQL } from "bun";
const sql = new SQL("sqlite://:memory:");
await sql`create table t (x)`;
const inserted = sql`insert into t values (1) returning x`.then(
  rows => rows[0].x,
  e => e.code,
);
await sql.close();
console.log(await inserted);

PostgreSQL and MySQL behave the same with ERR_POSTGRES_CONNECTION_CLOSED and ERR_MYSQL_CONNECTION_CLOSED. The tests for them use a real server.

PR: #44040

Comment thread src/js/internal/sql/query.ts Resolved
Comment thread src/js/internal/sql/shared.ts Resolved
Comment thread src/js/internal/sql/sqlite.ts Resolved
The PostgreSQL and MySQL tests of close() and of the start of a lazy query
are now in sql-close-started-queries.test.ts. The tests of a block share
one table. Each test writes rows with an id of its own.

sql-close-pending-connection.test.ts and sql-onconnect-onclose-throw.test.ts
are as on the base again.
@robobun

robobun commented Sep 27, 2026 •

Copy link
Copy Markdown
Collaborator Author
Updated 7:14 AM PT - Sep 27th, 2026

✅ @robobun, your commit 46b61c2b6e38560be9fb2be9ac42575fcf8bffb8 passed in Build #121250! 🎉


🧪   To try this PR locally:

bunx bun-pr 44040

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

bun-44040 --bun

@robobun

robobun commented Sep 28, 2026

Copy link
Copy Markdown
Collaborator Author

@robobun wake up!!

@Jarred-Sumner

Copy link
Copy Markdown
Collaborator

@robobun wake up!!

@robobun

robobun commented Sep 28, 2026

Copy link
Copy Markdown
Collaborator Author

@Jarred-Sumner This PR is complete and CI is green. It is a draft only because it needs one decision from a maintainer.

It is the second of two fixes for #43887. The first one is #44105, and I recommend #44105: it is smaller (source +8 -51, against +115 -5 here), and each query gets cheaper. The comparison and the steps to merge are in #44105 (comment).

@Jarred-Sumner

Copy link
Copy Markdown
Collaborator

A query started with then() in the tick of close() was rejected unsent, although the docs say that close() waits for all queries. #45304 fixes that bug with the other of the two designs, #44105, which this draft itself recommends. So this one is closed without porting.

This design keeps the cause, the one promise job that #runAsync() waits between "started" and "handed to the pool", and compensates for it: a linked list through the queries ([_nextStarted]), firstStarted / lastStarted on every adapter, a handedOff status bit, and a second copy of the decision in SQLiteAdapter.close() with an exception for an open begin(). By its own count that is +115 source lines and 36 to 38 more bytecode instructions per pool query.

#44105 deletes the wait. The query reaches the pool in the call of then(), catch(), finally() or run(), so close() has nothing to collect and every query gets cheaper.

The guarantee is the same. A query that was started before close() is sent, and close() waits for it. A query that only await or Promise.all() starts is still rejected, because they call then() in a later job. "%s: a close() that follows in the same tick waits for it" in test/js/sql/sql-pool.test.ts checks the five ways to start a query on PostgreSQL, MySQL and MariaDB.

Nothing from src was taken. The 30 pins fix the promise job in which each start reaches the database, and that delay no longer exists. That is the choice #45304 makes for the question in #43887.

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.

2 participants