fix queue processing deadlock

reported here:
TryGhost#1838

Author: gms1

memory-bank/decisionLog.md

@@ -2,6 +2,46 @@
 
 ## Technical Decisions
 
+### 2026-04-10: Queue Processing Deadlock Fix
+
+**Decision**: Track `pending` counter to detect synchronous operations in `Database::Process()`
+
+**Rationale**:
+- Bug: When using `db.serialize()`, synchronous operations like `configure()` would cause subsequent operations to get stuck in the queue indefinitely
+- Root cause: `Process()` loop breaks after exclusive operations, but synchronous operations don't increment `pending`, leaving `locked=true` with no async work pending
+- Solution detects synchronous completion by checking if `pending` counter changed during callback execution
+
+**Implementation**:
+```cpp
+// Track pending before callback to detect synchronous operations
+unsigned int before_pending = pending;
+call->callback(call->baton);
+
+// If operation was synchronous (pending unchanged) and we're in exclusive mode,
+// reset locked and continue processing the queue.
+if (locked && pending == before_pending) {
+    locked = false;
+    continue;
+}
+```
+
+**Files Changed**:
+- `src/database.cc`: Modified `Database::Process()` function
+- `test/serialization.test.js`: Added test cases for queue processing bug
+
+**Affected Synchronous Operations**:
+- `SetLimit` - SQLite limit configuration
+- `SetBusyTimeout` - Busy timeout setting
+- `RegisterTraceCallback` - Trace callback registration
+- `RegisterProfileCallback` - Profile callback registration
+- `RegisterUpdateCallback` - Update hook registration
+- `Work_Wait` - Wait operation
+
+**References**:
+- GitHub Issue: https://github.com/TryGhost/node-sqlite3/issues/1838
+
+---
+
 ### 2026-03-29: Security Hardening Implementation
 
 **Decision**: Implement platform-specific security hardening flags in binding.gyp

memory-bank/progress.md

@@ -1,6 +1,15 @@
 # Progress Log
 
-## 2026-04-04: 
+## 2026-04-10:
+
+### fixed: queue processing deadlock in serialized mode
+  - Fixed bug where operations get stuck in queue when using `db.serialize()` with synchronous operations
+  - Issue: https://github.com/TryGhost/node-sqlite3/issues/1838
+  - Modified `Database::Process()` in `src/database.cc` to detect synchronous operations
+  - Added test cases in `test/serialization.test.js`
+  - Solution: Track `pending` counter before/after callback to detect synchronous completion
+
+## 2026-04-04:
 
 ### fixed: potential crash during shutdown
   please see [microsoft/vscode-node-sqlite3/issues/67](https://github.com/microsoft/vscode-node-sqlite3/issues/67)

src/database.cc

@@ -14,7 +14,7 @@ Napi::FunctionReference Database::constructor;
 Napi::Object Database::Init(Napi::Env env, Napi::Object exports) {
     Napi::HandleScope scope(env);
     // declare napi_default_method here as it is only available in Node v14.12.0+
-    auto napi_default_method = static_cast<napi_property_attributes>(napi_writable | napi_configurable); 
+    auto napi_default_method = static_cast<napi_property_attributes>(napi_writable | napi_configurable);
 
     auto t = DefineClass(env, "Database", {
         InstanceMethod("close", &Database::Close, napi_default_method),
@@ -81,8 +81,21 @@ void Database::Process() {
         queue.pop();
         std::unique_ptr<Call> call(c);
         locked = call->exclusive;
+
+        // Track pending before callback to detect synchronous operations
+        unsigned int before_pending = pending;
         call->callback(call->baton);
 
+        // If operation was synchronous (pending unchanged) and we're in exclusive mode,
+        // reset locked and continue processing the queue.
+        // Synchronous operations don't increment pending, so if pending is unchanged
+        // and locked is true, the operation completed synchronously.
+        if (locked && pending == before_pending) {
+            locked = false;
+            // Continue processing - don't break
+            continue;
+        }
+
         if (locked) break;
     }
 }
@@ -340,7 +353,7 @@ Napi::Value Database::Configure(const Napi::CallbackInfo& info) {
     REQUIRE_ARGUMENTS(2);
 
     Napi::Function handle;
-    if (info[0].StrictEquals( Napi::String::New(env, "trace"))) {    
+    if (info[0].StrictEquals( Napi::String::New(env, "trace"))) {
        auto* baton = new Baton(db, handle);
         db->Schedule(RegisterTraceCallback, baton);
     }

test/serialization.test.js

@@ -102,3 +102,80 @@ describe('serialize(fn)', function() {
 
     after(function(done) { db.close(done); });
 });
+
+describe('serialize() queue processing with synchronous operations', function () {
+    var db;
+
+    beforeEach(function (done) {
+        db = new sqlite3.Database(':memory:', done);
+    });
+
+    afterEach(function (done) {
+        db.close(done);
+    });
+
+    it('should process queued operations after configure in serialized mode', function (done) {
+    // This test reproduces the bug where operations get stuck in the queue
+    // when db.configure() is called during serialized mode with pending async work.
+    // See: https://github.com/TryGhost/node-sqlite3/issues/1838
+
+        var LONG_QUERY = `WITH recursive recur(n)
+            AS (SELECT 1
+            UNION ALL
+            SELECT n + 1
+            FROM recur where n < 1000000
+            )
+            SELECT n FROM recur;`;
+
+        var executed = false;
+
+        db.serialize();
+
+        // Start a long-running async operation
+        db.exec(LONG_QUERY);
+
+        // Queue a synchronous configure operation
+        db.configure('limit', sqlite3.LIMIT_ATTACHED, 1);
+
+        // Queue another operation - this should execute after configure
+        db.exec("SELECT 1", function (err) {
+            if (err) return done(err);
+            executed = true;
+        });
+
+        // Give enough time for the bug to manifest
+        setTimeout(function () {
+            if (executed) {
+                done();
+            } else {
+                done(new Error('Queue processing deadlock: SELECT 1 callback was never called'));
+            }
+        }, 2000);
+    });
+
+    it('should process multiple configure calls in serialized mode', function (done) {
+        var executed = false;
+
+        db.serialize();
+
+        db.exec("CREATE TABLE test (id INTEGER PRIMARY KEY, value TEXT)");
+        db.exec("INSERT INTO test VALUES (1, 'one')");
+
+        // Multiple configure calls should all be processed
+        db.configure('limit', sqlite3.LIMIT_ATTACHED, 1);
+        db.configure('busyTimeout', 1000);
+
+        db.exec("SELECT * FROM test", function (err, rows) {
+            if (err) return done(err);
+            executed = true;
+        });
+
+        setTimeout(function () {
+            if (executed) {
+                done();
+            } else {
+                done(new Error('Queue processing deadlock: SELECT callback was never called'));
+            }
+        }, 1000);
+    });
+});