From 3f967fc3edf0d610133be4f0ddebef12f9abecd9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Guilherme=20Ara=C3=BAjo?= <arauujogui@gmail.com>
Date: Wed, 1 Jul 2026 11:18:34 -0300
Subject: [PATCH] sqlite: add StatementSync.prototype[Symbol.dispose]()
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This extends explicit resource management support to prepared
statements, allowing a StatementSync to be deterministically
finalized via a `using` declaration, mirroring the existing
DatabaseSync and Session dispose methods.

Signed-off-by: Guilherme Araújo <arauujogui@gmail.com>
---
 doc/api/sqlite.md                           |  9 +++++
 src/node_sqlite.cc                          | 20 ++++++++--
 src/node_sqlite.h                           |  2 +
 test/parallel/test-sqlite-statement-sync.js | 43 +++++++++++++++++++++
 4 files changed, 70 insertions(+), 4 deletions(-)

diff --git a/doc/api/sqlite.md b/doc/api/sqlite.md
index 850358ff43aa86..e4830b9835dd0d 100644
--- a/doc/api/sqlite.md
+++ b/doc/api/sqlite.md
@@ -1202,6 +1202,15 @@ added: v22.5.0
 The source SQL text of the prepared statement. This property is a
 wrapper around [`sqlite3_sql()`][].
 
+### `statement[Symbol.dispose]()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+Finalizes the prepared statement. If the prepared statement is already
+finalized, then this is a no-op.
+
 ## Class: `SQLTagStore`
 
 <!-- YAML
diff --git a/src/node_sqlite.cc b/src/node_sqlite.cc
index 049fd786126fce..cb9361c7867a3d 100644
--- a/src/node_sqlite.cc
+++ b/src/node_sqlite.cc
@@ -1037,10 +1037,7 @@ void DatabaseSync::FinalizeStatements() {
 }
 
 void DatabaseSync::UntrackStatement(StatementSync* statement) {
-  auto it = statements_.find(statement);
-  if (it != statements_.end()) {
-    statements_.erase(it);
-  }
+  statements_.erase(statement);
 }
 
 inline bool DatabaseSync::IsOpen() {
@@ -2578,6 +2575,10 @@ StatementSync::StatementSync(Environment* env,
 }
 
 StatementSync::~StatementSync() {
+  Close();
+}
+
+void StatementSync::Close() {
   if (!IsFinalized()) {
     db_->UntrackStatement(this);
     Finalize();
@@ -2598,6 +2599,16 @@ inline bool StatementSync::IsFinalized() {
   return statement_ == nullptr;
 }
 
+void StatementSync::Dispose(const FunctionCallbackInfo<Value>& args) {
+  StatementSync* stmt;
+  ASSIGN_OR_RETURN_UNWRAP(&stmt, args.This());
+  v8::TryCatch try_catch(args.GetIsolate());
+  stmt->Close();
+  if (try_catch.HasCaught()) {
+    CHECK(try_catch.CanContinue());
+  }
+}
+
 inline int StatementSync::ResetStatement() {
   reset_generation_++;
   return sqlite3_reset(statement_);
@@ -3625,6 +3636,7 @@ Local<FunctionTemplate> StatementSync::GetConstructorTemplate(
         isolate, tmpl, "setReadBigInts", StatementSync::SetReadBigInts);
     SetProtoMethod(
         isolate, tmpl, "setReturnArrays", StatementSync::SetReturnArrays);
+    SetProtoDispose(isolate, tmpl, StatementSync::Dispose);
     env->set_sqlite_statement_sync_constructor_template(tmpl);
   }
   return tmpl;
diff --git a/src/node_sqlite.h b/src/node_sqlite.h
index e7281ed266af5d..ff370f1e77e2e4 100644
--- a/src/node_sqlite.h
+++ b/src/node_sqlite.h
@@ -278,6 +278,7 @@ class StatementSync : public BaseObject {
       const v8::FunctionCallbackInfo<v8::Value>& args);
   static void SetReadBigInts(const v8::FunctionCallbackInfo<v8::Value>& args);
   static void SetReturnArrays(const v8::FunctionCallbackInfo<v8::Value>& args);
+  static void Dispose(const v8::FunctionCallbackInfo<v8::Value>& args);
   v8::MaybeLocal<v8::Value> ColumnToValue(const int column);
   v8::MaybeLocal<v8::Name> ColumnNameToName(const int column);
   bool GetCachedColumnNames(v8::LocalVector<v8::Name>* keys);
@@ -289,6 +290,7 @@ class StatementSync : public BaseObject {
 
  private:
   ~StatementSync() override;
+  void Close();
   BaseObjectPtr<DatabaseSync> db_;
   sqlite3_stmt* statement_;
   bool return_arrays_ = false;
diff --git a/test/parallel/test-sqlite-statement-sync.js b/test/parallel/test-sqlite-statement-sync.js
index aa7a3a73ae6649..37e31e88001d6a 100644
--- a/test/parallel/test-sqlite-statement-sync.js
+++ b/test/parallel/test-sqlite-statement-sync.js
@@ -909,3 +909,46 @@ suite('options.allowBareNamedParameters', () => {
     );
   });
 });
+
+
+suite('StatementSync.prototype[Symbol.dispose]()', () => {
+  test('finalizes an open statement', (t) => {
+    using db = new DatabaseSync(':memory:');
+    db.exec('CREATE TABLE storage(key TEXT, val TEXT)');
+    const stmt = db.prepare('SELECT * FROM storage');
+    stmt[Symbol.dispose]();
+    t.assert.throws(() => stmt.get(), {
+      code: 'ERR_INVALID_STATE',
+      message: /statement has been finalized/,
+    });
+  });
+
+  test('does not throw on an already-finalized statement', () => {
+    using db = new DatabaseSync(':memory:');
+    const stmt = db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+    stmt[Symbol.dispose]();
+    stmt[Symbol.dispose]();
+  });
+
+  test('works with a using declaration', (t) => {
+    using db = new DatabaseSync(':memory:');
+    db.exec('CREATE TABLE storage(key TEXT, val TEXT)');
+    let captured;
+    {
+      using stmt = db.prepare('SELECT * FROM storage');
+      captured = stmt;
+      t.assert.deepStrictEqual(stmt.all(), []);
+    }
+    t.assert.throws(() => captured.get(), {
+      code: 'ERR_INVALID_STATE',
+      message: /statement has been finalized/,
+    });
+  });
+
+  test('closing the database after dispose does not double-finalize', () => {
+    using db = new DatabaseSync(':memory:');
+    const stmt = db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+    stmt[Symbol.dispose]();
+    db.close();
+  });
+});