@homeofthings/sqlite3 6.3.1 → 6.4.0

package/README.md

@@ -20,7 +20,7 @@ Asynchronous, non-blocking [SQLite3](https://sqlite.org/) bindings for [Node.js]
  - [Extension support](https://github.com/gms1/node-sqlite3/wiki/API#databaseloadextensionpath-callback), including bundled support for the [json1 extension](https://www.sqlite.org/json1.html)
  - Big test suite
  - Written in modern C++ and tested for memory leaks
- - Bundles SQLite v3.51.3, or you can build using a local SQLite
+ - Bundles SQLite v3.53.0, or you can build using a local SQLite
 
 # Installing
 
@@ -245,6 +245,34 @@ npm install @homeofthings/sqlite3 --build-from-source --sqlite_libname=sqlcipher
 npm test
 ```
 
+# Benchmarks
+
+## Driver Comparison
+
+The `tools/benchmark-drivers` directory contains a comprehensive benchmark suite comparing different SQLite drivers for Node.js:
+
+```bash
+cd tools/benchmark-drivers
+npm install
+node index.js
+```
+
+This compares `@homeofthings/sqlite3` against other popular SQLite drivers:
+- `better-sqlite3` - Synchronous, high-performance
+- `node:sqlite` - Built-in Node.js SQLite (v22.6.0+)
+
+See [tools/benchmark-drivers/README.md](tools/benchmark-drivers/README.md) for details.
+
+**Key insight**: Async drivers like `@homeofthings/sqlite3` show lower raw throughput but provide better event loop availability, allowing other operations to proceed concurrently. Sync drivers block the event loop completely.
+
+## Internal Benchmarks
+
+Internal performance benchmarks are available in `tools/benchmark-internal`:
+
+```bash
+node tools/benchmark-internal/run.js
+```
+
 # Contributors
 
 * [Daniel Lockyer](https://github.com/daniellockyer)
@@ -269,7 +297,9 @@ Thanks to [Orlando Vazquez](https://github.com/orlandov),
 [Eric Fredricksen](https://github.com/grumdrig) and
 [Ryan Dahl](https://github.com/ry) for their SQLite bindings for node, and to mraleph on Freenode's #v8 for answering questions.
 
-This module was originally created by [Mapbox](https://mapbox.com/) & is now maintained by [Ghost](https://ghost.org).
+This module was originally created by [Mapbox](https://mapbox.com/), then it was taken over by [Ghost](https://ghost.org), but was then deprecated without prior notice, so that the original is no longer maintained. See [TryGhost/node-sqlite3](https://github.com/TryGhost/node-sqlite3)
+
+I still hope that it will eventually be taken over by a larger organization, but in the meantime, I'm trying to maintain this fork here.
 
 # Changelog
 

package/deps/common-sqlite.gypi

@@ -1,6 +1,6 @@
 {
   'variables': {
-      'sqlite_version%':'3510300',
+      'sqlite_version%':'3530000',
       "toolset%":'',
   },
   'target_defaults': {

package/lib/promise/database.js

@@ -324,9 +324,18 @@ class SqliteDatabase {
     /**
    * Run callback inside a database transaction
    *
+   * IMPORTANT: SQLite provides isolation between different database connections,
+   * but NOT between operations on the same connection. If you need concurrent
+   * transactions with proper isolation, use separate SqliteDatabase instances.
+   *
+   * Note: This uses BEGIN IMMEDIATE TRANSACTION which acquires a write lock
+   * immediately. If another connection holds a write lock, this will fail
+   * with SQLITE_BUSY error.
+   *
    * @template T
    * @param {() => Promise<T>} callback - The callback to run in transaction
    * @returns {Promise<T>} A promise that resolves to the callback result
+   * @see https://www.sqlite.org/isolation.html
    */
     async transactionalize(callback) {
         await this.beginTransaction();
@@ -341,7 +350,10 @@ class SqliteDatabase {
     }
 
     /**
-   * Begin a transaction
+   * Begin a transaction using BEGIN IMMEDIATE TRANSACTION
+   *
+   * This acquires a write lock immediately, preventing deadlocks by
+   * failing fast if another connection holds the lock (SQLITE_BUSY).
    *
    * @returns {Promise<SqlRunResult>}
    */

package/lib/promise/statement.js

@@ -60,6 +60,10 @@ class SqliteStatement {
     /**
    * Finalizes a prepared statement (freeing any resource used by this statement)
    *
+   * IMPORTANT: You MUST finalize all prepared statements before closing the database.
+   * If you attempt to close a database with unfinalized statements, you will get:
+   * SQLITE_BUSY: unable to close due to unfinalised statements
+   *
    * @returns {Promise<void>}
    */
     finalize() {

package/lib/sqlite3.d.ts

@@ -265,7 +265,22 @@ export class SqliteDatabase {
     serialize(callback?: () => void): void;
     parallelize(callback?: () => void): void;
 
+    /**
+     * Run callback inside a database transaction.
+     *
+     * IMPORTANT: SQLite provides isolation between different database connections,
+     * but NOT between operations on the same connection. For concurrent transactions
+     * with proper isolation, use separate SqliteDatabase instances.
+     *
+     * Uses BEGIN IMMEDIATE TRANSACTION which acquires a write lock immediately.
+     * @see https://www.sqlite.org/isolation.html
+     */
     transactionalize<T>(callback: () => Promise<T>): Promise<T>;
+
+    /**
+     * Begin a transaction using BEGIN IMMEDIATE TRANSACTION.
+     * Acquires write lock immediately - fails with SQLITE_BUSY if lock unavailable.
+     */
     beginTransaction(): Promise<void>;
     commitTransaction(): Promise<void>;
     rollbackTransaction(): Promise<void>;
@@ -300,6 +315,11 @@ export class SqliteStatement {
         callback?: (err: Error | null, row: T) => void,
     ): Promise<number>;
 
+    /**
+     * Finalizes the statement.
+     * IMPORTANT: You MUST finalize all prepared statements before closing the database.
+     * Otherwise you will get SQLITE_BUSY: unable to close due to unfinalised statements
+     */
     finalize(): Promise<void>;
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@homeofthings/sqlite3",
   "description": "Asynchronous, non-blocking SQLite3 bindings",
-  "version": "6.3.1",
+  "version": "6.4.0",
   "homepage": "https://github.com/gms1/node-sqlite3",
   "author": {
     "name": "Mapbox",
@@ -52,7 +52,7 @@
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "eslint": "^10.2.0",
-    "globals": "^17.4.0",
+    "globals": "^17.5.0",
     "mocha": "11.7.5",
     "nyc": "^18.0.0",
     "prebuild": "13.0.1",