[bun:sqlite] Support sqlite3_file_control, better closing behavior,…

… implement Disposable (#10262)

* [bun:sqlite] Support `sqlite_file_control`, better closing behavior, support `using` statements

* docs+flaky test

* Simplify the implementation

docs/api/sqlite.md

@@ -62,7 +62,7 @@ const db = new Database("mydb.sqlite", { create: true });
 You can also use an import attribute to load a database.
 
 ```ts
-import db from "./mydb.sqlite" with {"type": "sqlite"};
+import db from "./mydb.sqlite" with { "type": "sqlite" };
 
 console.log(db.query("select * from users LIMIT 1").get());
 ```
@@ -74,16 +74,39 @@ import { Database } from "bun:sqlite";
 const db = new Database("./mydb.sqlite");
 ```
 
-### `.close()`
+### `.close(throwOnError: boolean = false)`
 
-To close a database:
+To close a database connection, but allow existing queries to finish, call `.close(false)`:
 
 ```ts
 const db = new Database();
-db.close();
+// ... do stuff
+db.close(false);
 ```
 
-Note: `close()` is called automatically when the database is garbage collected. It is safe to call multiple times but has no effect after the first.
+To close the database and throw an error if there are any pending queries, call `.close(true)`:
+
+```ts
+const db = new Database();
+// ... do stuff
+db.close(true);
+```
+
+Note: `close(false)` is called automatically when the database is garbage collected. It is safe to call multiple times but has no effect after the first.
+
+### `using` statement
+
+You can use the `using` statement to ensure that a database connection is closed when the `using` block is exited.
+
+```ts
+import { Database } from "bun:sqlite";
+
+{
+  using db = new Database("mydb.sqlite");
+  using query = db.query("select 'Hello world' as message;");
+  console.log(query.get()); // => { message: "Hello world" }
+}
+```
 
 ### `.serialize()`
 
@@ -128,6 +151,8 @@ db.exec("PRAGMA journal_mode = WAL;");
 
 {% details summary="What is WAL mode" %}
 In WAL mode, writes to the database are written directly to a separate file called the "WAL file" (write-ahead log). This file will be later integrated into the main database file. Think of it as a buffer for pending writes. Refer to the [SQLite docs](https://www.sqlite.org/wal.html) for a more detailed overview.
+
+On macOS, WAL files may be persistent by default. This is not a bug, it is how macOS configured the system version of SQLite.
 {% /details %}
 
 ## Statements
@@ -387,6 +412,25 @@ db.loadExtension("myext");
 
 {% /details %}
 
+### .fileControl(cmd: number, value: any)
+
+To use the advanced `sqlite3_file_control` API, call `.fileControl(cmd, value)` on your `Database` instance.
+
+```ts
+import { Database, constants } from "bun:sqlite";
+
+const db = new Database();
+// Ensure WAL mode is NOT persistent
+// this prevents wal files from lingering after the database is closed
+db.fileControl(constants.SQLITE_FCNTL_PERSIST_WAL, 0);
+```
+
+`value` can be:
+
+- `number`
+- `TypedArray`
+- `undefined` or `null`
+
 ## Reference
 
 ```ts

packages/bun-types/sqlite.d.ts

@@ -24,7 +24,7 @@
  * | `null` | `NULL` |
  */
 declare module "bun:sqlite" {
-  export class Database {
+  export class Database implements Disposable {
     /**
      * Open or create a SQLite3 database
      *
@@ -257,7 +257,20 @@ declare module "bun:sqlite" {
      *
      * Internally, this calls `sqlite3_close_v2`.
      */
-    close(): void;
+    close(
+      /**
+       * If `true`, then the database will throw an error if it is in use
+       * @default false
+       *
+       * When true, this calls `sqlite3_close` instead of `sqlite3_close_v2`.
+       *
+       * Learn more about this in the [sqlite3 documentation](https://www.sqlite.org/c3ref/close.html).
+       *
+       * Bun will automatically call close by default when the database instance is garbage collected.
+       * In The future, Bun may default `throwOnError` to be true but for backwards compatibility, it is false by default.
+       */
+      throwOnError?: boolean,
+    ): void;
 
     /**
      * The filename passed when `new Database()` was called
@@ -304,6 +317,8 @@ declare module "bun:sqlite" {
      */
     static setCustomSQLite(path: string): boolean;
 
+    [Symbol.dispose](): void;
+
     /**
      * Creates a function that always runs inside a transaction. When the
      * function is invoked, it will begin a new transaction. When the function
@@ -427,6 +442,17 @@ declare module "bun:sqlite" {
      * ```
      */
     static deserialize(serialized: NodeJS.TypedArray | ArrayBufferLike, isReadOnly?: boolean): Database;
+
+    /**
+     * See `sqlite3_file_control` for more information.
+     * @link https://www.sqlite.org/c3ref/file_control.html
+     */
+    fileControl(op: number, arg?: ArrayBufferView | number): number;
+    /**
+     * See `sqlite3_file_control` for more information.
+     * @link https://www.sqlite.org/c3ref/file_control.html
+     */
+    fileControl(zDbName: string, op: number, arg?: ArrayBufferView | number): number;
   }
 
   /**
@@ -455,7 +481,7 @@ declare module "bun:sqlite" {
    * // => undefined
    * ```
    */
-  export class Statement<ReturnType = unknown, ParamsType extends SQLQueryBindings[] = any[]> {
+  export class Statement<ReturnType = unknown, ParamsType extends SQLQueryBindings[] = any[]> implements Disposable {
     /**
      * Creates a new prepared statement from native code.
      *
@@ -633,6 +659,11 @@ declare module "bun:sqlite" {
      */
     finalize(): void;
 
+    /**
+     * Calls {@link finalize} if it wasn't already called.
+     */
+    [Symbol.dispose](): void;
+
     /**
      * Return the expanded SQL string for the prepared statement.
      *
@@ -766,6 +797,187 @@ declare module "bun:sqlite" {
      * @constant 0x04
      */
     SQLITE_PREPARE_NO_VTAB: number;
+
+    /**
+     * @constant 1
+     */
+    SQLITE_FCNTL_LOCKSTATE: number;
+    /**
+     * @constant 2
+     */
+    SQLITE_FCNTL_GET_LOCKPROXYFILE: number;
+    /**
+     * @constant 3
+     */
+    SQLITE_FCNTL_SET_LOCKPROXYFILE: number;
+    /**
+     * @constant 4
+     */
+    SQLITE_FCNTL_LAST_ERRNO: number;
+    /**
+     * @constant 5
+     */
+    SQLITE_FCNTL_SIZE_HINT: number;
+    /**
+     * @constant 6
+     */
+    SQLITE_FCNTL_CHUNK_SIZE: number;
+    /**
+     * @constant 7
+     */
+    SQLITE_FCNTL_FILE_POINTER: number;
+    /**
+     * @constant 8
+     */
+    SQLITE_FCNTL_SYNC_OMITTED: number;
+    /**
+     * @constant 9
+     */
+    SQLITE_FCNTL_WIN32_AV_RETRY: number;
+    /**
+     * @constant 10
+     *
+     * Control whether or not the WAL is persisted
+     * Some versions of macOS configure WAL to be persistent by default.
+     *
+     * You can change this with code like the below:
+     * ```ts
+     * import { Database } from "bun:sqlite";
+     *
+     * const db = Database.open("mydb.sqlite");
+     * db.fileControl(constants.SQLITE_FCNTL_PERSIST_WAL, 0);
+     * // enable WAL
+     * db.exec("PRAGMA journal_mode = WAL");
+     * // .. do some work
+     * db.close();
+     * ```
+     *
+     */
+    SQLITE_FCNTL_PERSIST_WAL: number;
+    /**
+     * @constant 11
+     */
+    SQLITE_FCNTL_OVERWRITE: number;
+    /**
+     * @constant 12
+     */
+    SQLITE_FCNTL_VFSNAME: number;
+    /**
+     * @constant 13
+     */
+    SQLITE_FCNTL_POWERSAFE_OVERWRITE: number;
+    /**
+     * @constant 14
+     */
+    SQLITE_FCNTL_PRAGMA: number;
+    /**
+     * @constant 15
+     */
+    SQLITE_FCNTL_BUSYHANDLER: number;
+    /**
+     * @constant 16
+     */
+    SQLITE_FCNTL_TEMPFILENAME: number;
+    /**
+     * @constant 18
+     */
+    SQLITE_FCNTL_MMAP_SIZE: number;
+    /**
+     * @constant 19
+     */
+    SQLITE_FCNTL_TRACE: number;
+    /**
+     * @constant 20
+     */
+    SQLITE_FCNTL_HAS_MOVED: number;
+    /**
+     * @constant 21
+     */
+    SQLITE_FCNTL_SYNC: number;
+    /**
+     * @constant 22
+     */
+    SQLITE_FCNTL_COMMIT_PHASETWO: number;
+    /**
+     * @constant 23
+     */
+    SQLITE_FCNTL_WIN32_SET_HANDLE: number;
+    /**
+     * @constant 24
+     */
+    SQLITE_FCNTL_WAL_BLOCK: number;
+    /**
+     * @constant 25
+     */
+    SQLITE_FCNTL_ZIPVFS: number;
+    /**
+     * @constant 26
+     */
+    SQLITE_FCNTL_RBU: number;
+    /**
+     * @constant 27
+     */
+    SQLITE_FCNTL_VFS_POINTER: number;
+    /**
+     * @constant 28
+     */
+    SQLITE_FCNTL_JOURNAL_POINTER: number;
+    /**
+     * @constant 29
+     */
+    SQLITE_FCNTL_WIN32_GET_HANDLE: number;
+    /**
+     * @constant 30
+     */
+    SQLITE_FCNTL_PDB: number;
+    /**
+     * @constant 31
+     */
+    SQLITE_FCNTL_BEGIN_ATOMIC_WRITE: number;
+    /**
+     * @constant 32
+     */
+    SQLITE_FCNTL_COMMIT_ATOMIC_WRITE: number;
+    /**
+     * @constant 33
+     */
+    SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE: number;
+    /**
+     * @constant 34
+     */
+    SQLITE_FCNTL_LOCK_TIMEOUT: number;
+    /**
+     * @constant 35
+     */
+    SQLITE_FCNTL_DATA_VERSION: number;
+    /**
+     * @constant 36
+     */
+    SQLITE_FCNTL_SIZE_LIMIT: number;
+    /**
+     * @constant 37
+     */
+    SQLITE_FCNTL_CKPT_DONE: number;
+    /**
+     * @constant 38
+     */
+    SQLITE_FCNTL_RESERVE_BYTES: number;
+    /**
+     * @constant 39
+     */
+    SQLITE_FCNTL_CKPT_START: number;
+    /**
+     * @constant 40
+     */
+    SQLITE_FCNTL_EXTERNAL_READER: number;
+    /**
+     * @constant 41
+     */
+    SQLITE_FCNTL_CKSM_FILE: number;
+    /**
+     * @constant 42
+     */
+    SQLITE_FCNTL_RESET_CACHE: number;
   };
 
   /**