araujogui · Jul 1, 2026 · Jul 3, 2026 · Jul 4, 2026 · Jul 4, 2026
diff --git a/doc/api/sqlite.md b/doc/api/sqlite.md
@@ -997,6 +997,15 @@ objects. If the prepared statement does not return any results, this method
 returns an empty array. The prepared statement [parameters are bound][] using
 the values in `namedParameters` and `anonymousParameters`.
 
+### `statement.close()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+Finalizes the prepared statement. An exception is thrown if the statement is
+already finalized. This method is a wrapper around [`sqlite3_finalize()`][].
+
 ### `statement.columns()`
 
 <!-- YAML
@@ -1202,6 +1211,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
@@ -1682,6 +1700,7 @@ callback function to indicate what type of operation is being authorized.
 [`sqlite3_deserialize()`]: https://sqlite.org/c3ref/deserialize.html
 [`sqlite3_exec()`]: https://www.sqlite.org/c3ref/exec.html
 [`sqlite3_expanded_sql()`]: https://www.sqlite.org/c3ref/expanded_sql.html
+[`sqlite3_finalize()`]: https://www.sqlite.org/c3ref/finalize.html
 [`sqlite3_get_autocommit()`]: https://sqlite.org/c3ref/get_autocommit.html
 [`sqlite3_last_insert_rowid()`]: https://www.sqlite.org/c3ref/last_insert_rowid.html
 [`sqlite3_load_extension()`]: https://www.sqlite.org/c3ref/load_extension.html

diff --git 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,21 @@ inline bool StatementSync::IsFinalized() {
   return statement_ == nullptr;
 }
 
+void StatementSync::Close(const FunctionCallbackInfo<Value>& args) {
+  StatementSync* stmt;
+  ASSIGN_OR_RETURN_UNWRAP(&stmt, args.This());
+  Environment* env = Environment::GetCurrent(args);
+  THROW_AND_RETURN_ON_BAD_STATE(
+      env, stmt->IsFinalized(), "statement has been finalized");
+  stmt->Close();
+}
+
+void StatementSync::Dispose(const FunctionCallbackInfo<Value>& args) {
+  StatementSync* stmt;
+  ASSIGN_OR_RETURN_UNWRAP(&stmt, args.This());
+  stmt->Close();
+}
+
 inline int StatementSync::ResetStatement() {
   reset_generation_++;
   return sqlite3_reset(statement_);
@@ -3629,6 +3645,8 @@ Local<FunctionTemplate> StatementSync::GetConstructorTemplate(
         isolate, tmpl, "setReadBigInts", StatementSync::SetReadBigInts);
     SetProtoMethod(
         isolate, tmpl, "setReturnArrays", StatementSync::SetReturnArrays);
+    SetProtoMethod(isolate, tmpl, "close", StatementSync::Close);
+    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
@@ -278,6 +278,8 @@ 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 Close(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 +291,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-named-parameters.js b/test/parallel/test-sqlite-named-parameters.js
@@ -118,6 +118,22 @@ suite('StatementSync.prototype.setAllowUnknownNamedParameters()', () => {
       message: /The "enabled" argument must be a boolean/,
     });
   });
+
+  test('throws if the statement is already finalized', (t) => {
+    using db = new DatabaseSync(':memory:');
+    const setup = db.exec(
+      'CREATE TABLE data(key INTEGER PRIMARY KEY, val INTEGER) STRICT;'
+    );
+    t.assert.strictEqual(setup, undefined);
+    const stmt = db.prepare('INSERT INTO data (key, val) VALUES ($k, $v)');
+    stmt.close();
+    t.assert.throws(() => {
+      stmt.setAllowUnknownNamedParameters(true);
+    }, {
+      code: 'ERR_INVALID_STATE',
+      message: /statement has been finalized/,
+    });
+  });
 });
 
 suite('options.allowUnknownNamedParameters', () => {

diff --git a/test/parallel/test-sqlite-statement-sync.js b/test/parallel/test-sqlite-statement-sync.js
@@ -76,6 +76,18 @@ suite('StatementSync.prototype.get()', () => {
       __proto__: null, key: 'key1', val: 'val1',
     });
   });
+
+  test('throws if the statement is already finalized', (t) => {
+    using db = new DatabaseSync(':memory:');
+    const stmt = db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+    stmt.close();
+    t.assert.throws(() => {
+      stmt.get();
+    }, {
+      code: 'ERR_INVALID_STATE',
+      message: /statement has been finalized/,
+    });
+  });
 });
 
 suite('StatementSync.prototype.all()', () => {
@@ -129,6 +141,18 @@ suite('StatementSync.prototype.all()', () => {
       { __proto__: null, key: 'key1', val: 'val1' },
     ]);
   });
+
+  test('throws if the statement is already finalized', (t) => {
+    using db = new DatabaseSync(':memory:');
+    const stmt = db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+    stmt.close();
+    t.assert.throws(() => {
+      stmt.all();
+    }, {
+      code: 'ERR_INVALID_STATE',
+      message: /statement has been finalized/,
+    });
+  });
 });
 
 suite('StatementSync.prototype.iterate()', () => {
@@ -295,6 +319,18 @@ suite('StatementSync.prototype.iterate()', () => {
     stmt2.get();
     it.next();
   });
+
+  test('throws if the statement is already finalized', (t) => {
+    using db = new DatabaseSync(':memory:');
+    const stmt = db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+    stmt.close();
+    t.assert.throws(() => {
+      stmt.iterate();
+    }, {
+      code: 'ERR_INVALID_STATE',
+      message: /statement has been finalized/,
+    });
+  });
 });
 
 suite('StatementSync.prototype.run()', () => {
@@ -394,6 +430,18 @@ suite('StatementSync.prototype.run()', () => {
     const stmt = db.prepare('INSERT INTO data (key, val) VALUES (?1, ?2)');
     t.assert.deepStrictEqual(stmt.run(1, 2), { changes: 1, lastInsertRowid: 1 });
   });
+
+  test('throws if the statement is already finalized', (t) => {
+    using db = new DatabaseSync(':memory:');
+    const stmt = db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+    stmt.close();
+    t.assert.throws(() => {
+      stmt.run();
+    }, {
+      code: 'ERR_INVALID_STATE',
+      message: /statement has been finalized/,
+    });
+  });
 });
 
 suite('StatementSync.prototype.sourceSQL', () => {
@@ -408,6 +456,16 @@ suite('StatementSync.prototype.sourceSQL', () => {
     const stmt = db.prepare(sql);
     t.assert.strictEqual(stmt.sourceSQL, sql);
   });
+
+  test('throws if the statement is already finalized', (t) => {
+    using db = new DatabaseSync(':memory:');
+    const stmt = db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+    stmt.close();
+    t.assert.throws(() => stmt.sourceSQL, {
+      code: 'ERR_INVALID_STATE',
+      message: /statement has been finalized/,
+    });
+  });
 });
 
 suite('StatementSync.prototype.expandedSQL', () => {
@@ -427,6 +485,16 @@ suite('StatementSync.prototype.expandedSQL', () => {
     );
     t.assert.strictEqual(stmt.expandedSQL, expanded);
   });
+
+  test('throws if the statement is already finalized', (t) => {
+    using db = new DatabaseSync(':memory:');
+    const stmt = db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+    stmt.close();
+    t.assert.throws(() => stmt.expandedSQL, {
+      code: 'ERR_INVALID_STATE',
+      message: /statement has been finalized/,
+    });
+  });
 });
 
 suite('StatementSync.prototype.setReadBigInts()', () => {
@@ -496,6 +564,18 @@ suite('StatementSync.prototype.setReadBigInts()', () => {
       [`${Number.MAX_SAFE_INTEGER} + 1`]: 2n ** 53n,
     });
   });
+
+  test('throws if the statement is already finalized', (t) => {
+    using db = new DatabaseSync(':memory:');
+    const stmt = db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+    stmt.close();
+    t.assert.throws(() => {
+      stmt.setReadBigInts(true);
+    }, {
+      code: 'ERR_INVALID_STATE',
+      message: /statement has been finalized/,
+    });
+  });
 });
 
 suite('StatementSync.prototype.setReturnArrays()', () => {
@@ -514,6 +594,18 @@ suite('StatementSync.prototype.setReturnArrays()', () => {
       message: /The "returnArrays" argument must be a boolean/,
     });
   });
+
+  test('throws if the statement is already finalized', (t) => {
+    using db = new DatabaseSync(':memory:');
+    const stmt = db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+    stmt.close();
+    t.assert.throws(() => {
+      stmt.setReturnArrays(true);
+    }, {
+      code: 'ERR_INVALID_STATE',
+      message: /statement has been finalized/,
+    });
+  });
 });
 
 suite('StatementSync.prototype.get() with array output', () => {
@@ -732,6 +824,18 @@ suite('StatementSync.prototype.setAllowBareNamedParameters()', () => {
       message: /The "allowBareNamedParameters" argument must be a boolean/,
     });
   });
+
+  test('throws if the statement is already finalized', (t) => {
+    using db = new DatabaseSync(':memory:');
+    const stmt = db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+    stmt.close();
+    t.assert.throws(() => {
+      stmt.setAllowBareNamedParameters(true);
+    }, {
+      code: 'ERR_INVALID_STATE',
+      message: /statement has been finalized/,
+    });
+  });
 });
 
 suite('options.readBigInts', () => {
@@ -978,3 +1082,71 @@ suite('options.allowBareNamedParameters', () => {
     );
   });
 });
+
+
+suite('StatementSync.prototype.close()', () => {
+  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');
+    t.assert.strictEqual(stmt.close(), undefined);
+    t.assert.throws(() => stmt.get(), {
+      code: 'ERR_INVALID_STATE',
+      message: /statement has been finalized/,
+    });
+  });
+
+  test('throws if the statement is already finalized', (t) => {
+    using db = new DatabaseSync(':memory:');
+    const stmt = db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+    stmt.close();
+    t.assert.throws(() => {
+      stmt.close();
+    }, {
+      code: 'ERR_INVALID_STATE',
+      message: /statement has been finalized/,
+    });
+  });
+});
+
+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();
+  });
+});