sql: start a query in the call of then(), catch(), finally() and run()

docs/runtime/sql.mdx

@@ -980,6 +980,14 @@ await sql.close({ timeout: 0 }); // close all connections from the pool immediat
 
 `timeout` is in seconds. With `timeout: 0`, or when the timeout expires, queries that are still in flight reject with the adapter's `ERR_*_CONNECTION_CLOSED` error.
 
+`sql.close()` waits for the queries of the pool that started before the call. A query starts in the call of `.then()`, `.catch()`, `.finally()` or `.execute()`. `await query` and `Promise.all([query])` call `.then()` in a later microtask. When `close()` follows them in the same tick, it comes before the start, and the query rejects with the adapter's `ERR_*_CONNECTION_CLOSED` error. The same applies to a library that awaits the query in an async function of its own.
+
+```ts
+sql`INSERT INTO users ${sql(alice)}`.catch(report); // started, close() waits for it
+const inserted = (async () => await sql`INSERT INTO users ${sql(bob)}`)(); // not started yet
+await sql.close(); // `inserted` rejects
+```
+
 ---
 
 ## Reserved Connections

packages/bun-types/sql.d.ts

@@ -683,6 +683,12 @@ declare module "bun" {
      * Closes the database connection. With `timeout: 0` it closes
      * immediately; with no timeout it waits for all queries to finish first.
      *
+     * It waits for the queries of the pool that started before the call. A
+     * query starts in the call of `.then()`, `.catch()`, `.finally()` or
+     * `.execute()`. `await query` calls `.then()` in a later microtask, so
+     * a `close()` that follows it in the same tick comes before the start,
+     * and the query rejects.
+     *
      * @param options Optional `timeout` in seconds
      *
      * @example

src/js/bun/sql.ts

@@ -993,7 +993,8 @@ const SQL = function SQL(
     }
 
     const sqlQuery = pool.getRollbackDistributedSQL(name);
-    return await sql.unsafe(sqlQuery);
+    // then() starts the query in this call. `await` alone starts it one promise job later.
+    return await sql.unsafe(sqlQuery).then();
   };
 
   sql.commitDistributed = async function (name: string) {
@@ -1006,7 +1007,8 @@ const SQL = function SQL(
     }
 
     const sqlQuery = pool.getCommitDistributedSQL(name);
-    return await sql.unsafe(sqlQuery);
+    // then() starts the query in this call. `await` alone starts it one promise job later.
+    return await sql.unsafe(sqlQuery).then();
   };
 
   sql.beginDistributed = (name: string, fn: TransactionCallback) => {

src/js/internal/sql/query.ts

@@ -128,38 +128,6 @@ class Query<T, Handle extends BaseQueryHandle<any>> extends PublicPromise<T> {
     }
   }
 
-  async #runAsync() {
-    const { [_handler]: handler, [_queryStatus]: status } = this;
-
-    if (
-      status &
-      (SQLQueryStatus.executed | SQLQueryStatus.error | SQLQueryStatus.cancelled | SQLQueryStatus.invalidHandle)
-    ) {
-      return;
-    }
-
-    if (this[_flags] & SQLQueryFlags.notTagged) {
-      this.reject(this[_adapter].notTaggedCallError());
-      return;
-    }
-
-    this[_queryStatus] |= SQLQueryStatus.executed;
-    const handle = this.#getQueryHandle();
-
-    if (!handle) {
-      return this;
-    }
-
-    await Promise.$resolve();
-
-    try {
-      return handler(this, handle);
-    } catch (err) {
-      this[_queryStatus] |= SQLQueryStatus.error;
-      this.reject(err as Error);
-    }
-  }
-
   get active() {
     return (this[_queryStatus] & SQLQueryStatus.active) != 0;
   }
@@ -240,7 +208,7 @@ class Query<T, Handle extends BaseQueryHandle<any>> extends PublicPromise<T> {
       throw this[_adapter].notTaggedCallError();
     }
 
-    await this.#runAsync();
+    this.#run();
     return this;
   }
 
@@ -271,23 +239,12 @@ class Query<T, Handle extends BaseQueryHandle<any>> extends PublicPromise<T> {
     return this;
   }
 
-  #runAsyncAndCatch() {
-    const runPromise = this.#runAsync();
-
-    if ($isPromise(runPromise) && runPromise !== this) {
-      runPromise.catch(() => {
-        // Error is already handled via this.reject() in #runAsync
-        // This catch is just to prevent unhandled rejection warnings
-      });
-    }
-  }
-
   then<TResult1 = T, TResult2 = never>(
     onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null,
     onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null,
   ): Promise<TResult1 | TResult2>;
   then() {
-    this.#runAsyncAndCatch();
+    this.#run();
 
     const result = super.$then.$apply(this, arguments);
 
@@ -305,7 +262,7 @@ class Query<T, Handle extends BaseQueryHandle<any>> extends PublicPromise<T> {
       throw this[_adapter].notTaggedCallError();
     }
 
-    this.#runAsyncAndCatch();
+    this.#run();
 
     const result = super.catch.$apply(this, arguments);
     $pokePromiseAsHandled(result);
@@ -318,7 +275,7 @@ class Query<T, Handle extends BaseQueryHandle<any>> extends PublicPromise<T> {
       throw this[_adapter].notTaggedCallError();
     }
 
-    this.#runAsyncAndCatch();
+    this.#run();
 
     return super.finally.$apply(this, arguments);
   }