sqlite: add StatementSync.prototype.close()

Signed-off-by: Guilherme Araújo <arauujogui@gmail.com>
PR-URL: #64232
Reviewed-By: René <contact.9a5d6388@renegade334.me.uk>

Author: araujogui

doc/api/sqlite.md

@@ -989,6 +989,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
@@ -1683,6 +1692,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

src/node_sqlite.cc

@@ -2656,6 +2656,15 @@ inline bool StatementSync::IsFinalized() {
 }
 
 voidStatementSync::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();
+}
+
+voidStatementSync::Dispose(const FunctionCallbackInfo<Value>& args) {
  StatementSync* stmt;
 ASSIGN_OR_RETURN_UNWRAP(&stmt, args.This());
  stmt->Close();
@@ -3694,7 +3703,8 @@ Local<FunctionTemplate> StatementSync::GetConstructorTemplate(
  isolate, tmpl, "setReadBigInts", StatementSync::SetReadBigInts);
 SetProtoMethod(
  isolate, tmpl, "setReturnArrays", StatementSync::SetReturnArrays);
-SetProtoDispose(isolate, tmpl, StatementSync::Close);
+SetProtoMethod(isolate, tmpl, "close", StatementSync::Close);
+SetProtoDispose(isolate, tmpl, StatementSync::Dispose);
  env->set_sqlite_statement_sync_constructor_template(tmpl);
  }
 return tmpl;

src/node_sqlite.h

@@ -285,6 +285,7 @@ class StatementSync : public BaseObject {
 staticvoidSetReadBigInts(const v8::FunctionCallbackInfo<v8::Value>& args);
 staticvoidSetReturnArrays(const v8::FunctionCallbackInfo<v8::Value>& args);
 staticvoidClose(const v8::FunctionCallbackInfo<v8::Value>& args);
+staticvoidDispose(const v8::FunctionCallbackInfo<v8::Value>& args);
  v8::MaybeLocal<v8::Value> ColumnToValue(constint column);
  v8::MaybeLocal<v8::Name> ColumnNameToName(constint column);
 boolGetCachedColumnNames(v8::LocalVector<v8::Name>* keys);

test/parallel/test-sqlite-named-parameters.js

@@ -109,6 +109,22 @@ suite('StatementSync.prototype.setAllowUnknownNamedParameters()', () => {
 message: /The"enabled"argumentmustbeaboolean/,
 });
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+constsetup=db.exec(
+'CREATE TABLE data(key INTEGER PRIMARY KEY, val INTEGER) STRICT;'
+);
+t.assert.strictEqual(setup,undefined);
+conststmt=db.prepare('INSERT INTO data (key, val) VALUES ($k, $v)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.setAllowUnknownNamedParameters(true);
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('options.allowUnknownNamedParameters',()=>{

test/parallel/test-sqlite-statement-sync.js

@@ -67,6 +67,18 @@ suite('StatementSync.prototype.get()', () => {
 __proto__: null,key: 'key1',val: 'val1',
 });
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.get();
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.all()',()=>{
@@ -120,6 +132,18 @@ suite('StatementSync.prototype.all()', () => {
 {__proto__: null,key: 'key1',val: 'val1'},
 ]);
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.all();
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.iterate()',()=>{
@@ -286,6 +310,18 @@ suite('StatementSync.prototype.iterate()', () => {
 stmt2.get();
 it.next();
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.iterate();
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.run()',()=>{
@@ -385,6 +421,18 @@ suite('StatementSync.prototype.run()', () => {
 conststmt=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)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.run();
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.sourceSQL',()=>{
@@ -399,6 +447,16 @@ suite('StatementSync.prototype.sourceSQL', () => {
 conststmt=db.prepare(sql);
 t.assert.strictEqual(stmt.sourceSQL,sql);
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>stmt.sourceSQL,{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.expandedSQL',()=>{
@@ -418,6 +476,16 @@ suite('StatementSync.prototype.expandedSQL', () => {
 );
 t.assert.strictEqual(stmt.expandedSQL,expanded);
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>stmt.expandedSQL,{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.setReadBigInts()',()=>{
@@ -487,6 +555,18 @@ suite('StatementSync.prototype.setReadBigInts()', () => {
 [`${Number.MAX_SAFE_INTEGER} + 1`]: 2n**53n,
 });
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.setReadBigInts(true);
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.setReturnArrays()',()=>{
@@ -505,6 +585,18 @@ suite('StatementSync.prototype.setReturnArrays()', () => {
 message: /The"returnArrays"argumentmustbeaboolean/,
 });
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.setReturnArrays(true);
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.get() with array output',()=>{
@@ -723,6 +815,18 @@ suite('StatementSync.prototype.setAllowBareNamedParameters()', () => {
 message: /The"allowBareNamedParameters"argumentmustbeaboolean/,
 });
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.setAllowBareNamedParameters(true);
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('options.readBigInts',()=>{
@@ -971,6 +1075,31 @@ suite('options.allowBareNamedParameters', () => {
 });
 
 
+suite('StatementSync.prototype.close()',()=>{
+test('finalizes an open statement',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+db.exec('CREATE TABLE storage(key TEXT, val TEXT)');
+conststmt=db.prepare('SELECT * FROM storage');
+t.assert.strictEqual(stmt.close(),undefined);
+t.assert.throws(()=>stmt.get(),{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.close();
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
+});
+
 suite('StatementSync.prototype[Symbol.dispose]()',()=>{
 test('finalizes an open statement',(t)=>{
 usingdb=newDatabaseSync(':memory:');

doc/api/sqlite.md

@@ -989,6 +989,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
@@ -1683,6 +1692,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

src/node_sqlite.cc

@@ -2656,6 +2656,15 @@ inline bool StatementSync::IsFinalized() {
 }
 
 voidStatementSync::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();
+}
+
+voidStatementSync::Dispose(const FunctionCallbackInfo<Value>& args) {
  StatementSync* stmt;
 ASSIGN_OR_RETURN_UNWRAP(&stmt, args.This());
  stmt->Close();
@@ -3694,7 +3703,8 @@ Local<FunctionTemplate> StatementSync::GetConstructorTemplate(
  isolate, tmpl, "setReadBigInts", StatementSync::SetReadBigInts);
 SetProtoMethod(
  isolate, tmpl, "setReturnArrays", StatementSync::SetReturnArrays);
-SetProtoDispose(isolate, tmpl, StatementSync::Close);
+SetProtoMethod(isolate, tmpl, "close", StatementSync::Close);
+SetProtoDispose(isolate, tmpl, StatementSync::Dispose);
  env->set_sqlite_statement_sync_constructor_template(tmpl);
  }
 return tmpl;

src/node_sqlite.h

@@ -285,6 +285,7 @@ class StatementSync : public BaseObject {
 staticvoidSetReadBigInts(const v8::FunctionCallbackInfo<v8::Value>& args);
 staticvoidSetReturnArrays(const v8::FunctionCallbackInfo<v8::Value>& args);
 staticvoidClose(const v8::FunctionCallbackInfo<v8::Value>& args);
+staticvoidDispose(const v8::FunctionCallbackInfo<v8::Value>& args);
  v8::MaybeLocal<v8::Value> ColumnToValue(constint column);
  v8::MaybeLocal<v8::Name> ColumnNameToName(constint column);
 boolGetCachedColumnNames(v8::LocalVector<v8::Name>* keys);

test/parallel/test-sqlite-named-parameters.js

@@ -109,6 +109,22 @@ suite('StatementSync.prototype.setAllowUnknownNamedParameters()', () => {
 message: /The"enabled"argumentmustbeaboolean/,
 });
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+constsetup=db.exec(
+'CREATE TABLE data(key INTEGER PRIMARY KEY, val INTEGER) STRICT;'
+);
+t.assert.strictEqual(setup,undefined);
+conststmt=db.prepare('INSERT INTO data (key, val) VALUES ($k, $v)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.setAllowUnknownNamedParameters(true);
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('options.allowUnknownNamedParameters',()=>{

test/parallel/test-sqlite-statement-sync.js

@@ -67,6 +67,18 @@ suite('StatementSync.prototype.get()', () => {
 __proto__: null,key: 'key1',val: 'val1',
 });
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.get();
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.all()',()=>{
@@ -120,6 +132,18 @@ suite('StatementSync.prototype.all()', () => {
 {__proto__: null,key: 'key1',val: 'val1'},
 ]);
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.all();
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.iterate()',()=>{
@@ -286,6 +310,18 @@ suite('StatementSync.prototype.iterate()', () => {
 stmt2.get();
 it.next();
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.iterate();
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.run()',()=>{
@@ -385,6 +421,18 @@ suite('StatementSync.prototype.run()', () => {
 conststmt=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)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.run();
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.sourceSQL',()=>{
@@ -399,6 +447,16 @@ suite('StatementSync.prototype.sourceSQL', () => {
 conststmt=db.prepare(sql);
 t.assert.strictEqual(stmt.sourceSQL,sql);
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>stmt.sourceSQL,{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.expandedSQL',()=>{
@@ -418,6 +476,16 @@ suite('StatementSync.prototype.expandedSQL', () => {
 );
 t.assert.strictEqual(stmt.expandedSQL,expanded);
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>stmt.expandedSQL,{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.setReadBigInts()',()=>{
@@ -487,6 +555,18 @@ suite('StatementSync.prototype.setReadBigInts()', () => {
 [`${Number.MAX_SAFE_INTEGER} + 1`]: 2n**53n,
 });
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.setReadBigInts(true);
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.setReturnArrays()',()=>{
@@ -505,6 +585,18 @@ suite('StatementSync.prototype.setReturnArrays()', () => {
 message: /The"returnArrays"argumentmustbeaboolean/,
 });
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.setReturnArrays(true);
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.get() with array output',()=>{
@@ -723,6 +815,18 @@ suite('StatementSync.prototype.setAllowBareNamedParameters()', () => {
 message: /The"allowBareNamedParameters"argumentmustbeaboolean/,
 });
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.setAllowBareNamedParameters(true);
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('options.readBigInts',()=>{
@@ -971,6 +1075,31 @@ suite('options.allowBareNamedParameters', () => {
 });
 
 
+suite('StatementSync.prototype.close()',()=>{
+test('finalizes an open statement',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+db.exec('CREATE TABLE storage(key TEXT, val TEXT)');
+conststmt=db.prepare('SELECT * FROM storage');
+t.assert.strictEqual(stmt.close(),undefined);
+t.assert.throws(()=>stmt.get(),{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.close();
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
+});
+
 suite('StatementSync.prototype[Symbol.dispose]()',()=>{
 test('finalizes an open statement',(t)=>{
 usingdb=newDatabaseSync(':memory:');

doc/api/sqlite.md

@@ -989,6 +989,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
@@ -1683,6 +1692,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

src/node_sqlite.cc

@@ -2656,6 +2656,15 @@ inline bool StatementSync::IsFinalized() {
 }
 
 voidStatementSync::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();
+}
+
+voidStatementSync::Dispose(const FunctionCallbackInfo<Value>& args) {
  StatementSync* stmt;
 ASSIGN_OR_RETURN_UNWRAP(&stmt, args.This());
  stmt->Close();
@@ -3694,7 +3703,8 @@ Local<FunctionTemplate> StatementSync::GetConstructorTemplate(
  isolate, tmpl, "setReadBigInts", StatementSync::SetReadBigInts);
 SetProtoMethod(
  isolate, tmpl, "setReturnArrays", StatementSync::SetReturnArrays);
-SetProtoDispose(isolate, tmpl, StatementSync::Close);
+SetProtoMethod(isolate, tmpl, "close", StatementSync::Close);
+SetProtoDispose(isolate, tmpl, StatementSync::Dispose);
  env->set_sqlite_statement_sync_constructor_template(tmpl);
  }
 return tmpl;

src/node_sqlite.h

@@ -285,6 +285,7 @@ class StatementSync : public BaseObject {
 staticvoidSetReadBigInts(const v8::FunctionCallbackInfo<v8::Value>& args);
 staticvoidSetReturnArrays(const v8::FunctionCallbackInfo<v8::Value>& args);
 staticvoidClose(const v8::FunctionCallbackInfo<v8::Value>& args);
+staticvoidDispose(const v8::FunctionCallbackInfo<v8::Value>& args);
  v8::MaybeLocal<v8::Value> ColumnToValue(constint column);
  v8::MaybeLocal<v8::Name> ColumnNameToName(constint column);
 boolGetCachedColumnNames(v8::LocalVector<v8::Name>* keys);

test/parallel/test-sqlite-named-parameters.js

@@ -109,6 +109,22 @@ suite('StatementSync.prototype.setAllowUnknownNamedParameters()', () => {
 message: /The"enabled"argumentmustbeaboolean/,
 });
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+constsetup=db.exec(
+'CREATE TABLE data(key INTEGER PRIMARY KEY, val INTEGER) STRICT;'
+);
+t.assert.strictEqual(setup,undefined);
+conststmt=db.prepare('INSERT INTO data (key, val) VALUES ($k, $v)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.setAllowUnknownNamedParameters(true);
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('options.allowUnknownNamedParameters',()=>{

test/parallel/test-sqlite-statement-sync.js

@@ -67,6 +67,18 @@ suite('StatementSync.prototype.get()', () => {
 __proto__: null,key: 'key1',val: 'val1',
 });
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.get();
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.all()',()=>{
@@ -120,6 +132,18 @@ suite('StatementSync.prototype.all()', () => {
 {__proto__: null,key: 'key1',val: 'val1'},
 ]);
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.all();
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.iterate()',()=>{
@@ -286,6 +310,18 @@ suite('StatementSync.prototype.iterate()', () => {
 stmt2.get();
 it.next();
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.iterate();
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.run()',()=>{
@@ -385,6 +421,18 @@ suite('StatementSync.prototype.run()', () => {
 conststmt=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)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.run();
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.sourceSQL',()=>{
@@ -399,6 +447,16 @@ suite('StatementSync.prototype.sourceSQL', () => {
 conststmt=db.prepare(sql);
 t.assert.strictEqual(stmt.sourceSQL,sql);
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>stmt.sourceSQL,{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.expandedSQL',()=>{
@@ -418,6 +476,16 @@ suite('StatementSync.prototype.expandedSQL', () => {
 );
 t.assert.strictEqual(stmt.expandedSQL,expanded);
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>stmt.expandedSQL,{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.setReadBigInts()',()=>{
@@ -487,6 +555,18 @@ suite('StatementSync.prototype.setReadBigInts()', () => {
 [`${Number.MAX_SAFE_INTEGER} + 1`]: 2n**53n,
 });
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.setReadBigInts(true);
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.setReturnArrays()',()=>{
@@ -505,6 +585,18 @@ suite('StatementSync.prototype.setReturnArrays()', () => {
 message: /The"returnArrays"argumentmustbeaboolean/,
 });
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.setReturnArrays(true);
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.get() with array output',()=>{
@@ -723,6 +815,18 @@ suite('StatementSync.prototype.setAllowBareNamedParameters()', () => {
 message: /The"allowBareNamedParameters"argumentmustbeaboolean/,
 });
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.setAllowBareNamedParameters(true);
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('options.readBigInts',()=>{
@@ -971,6 +1075,31 @@ suite('options.allowBareNamedParameters', () => {
 });
 
 
+suite('StatementSync.prototype.close()',()=>{
+test('finalizes an open statement',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+db.exec('CREATE TABLE storage(key TEXT, val TEXT)');
+conststmt=db.prepare('SELECT * FROM storage');
+t.assert.strictEqual(stmt.close(),undefined);
+t.assert.throws(()=>stmt.get(),{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.close();
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
+});
+
 suite('StatementSync.prototype[Symbol.dispose]()',()=>{
 test('finalizes an open statement',(t)=>{
 usingdb=newDatabaseSync(':memory:');

doc/api/sqlite.md

@@ -989,6 +989,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
@@ -1683,6 +1692,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

src/node_sqlite.cc

@@ -2656,6 +2656,15 @@ inline bool StatementSync::IsFinalized() {
 }
 
 voidStatementSync::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();
+}
+
+voidStatementSync::Dispose(const FunctionCallbackInfo<Value>& args) {
  StatementSync* stmt;
 ASSIGN_OR_RETURN_UNWRAP(&stmt, args.This());
  stmt->Close();
@@ -3694,7 +3703,8 @@ Local<FunctionTemplate> StatementSync::GetConstructorTemplate(
  isolate, tmpl, "setReadBigInts", StatementSync::SetReadBigInts);
 SetProtoMethod(
  isolate, tmpl, "setReturnArrays", StatementSync::SetReturnArrays);
-SetProtoDispose(isolate, tmpl, StatementSync::Close);
+SetProtoMethod(isolate, tmpl, "close", StatementSync::Close);
+SetProtoDispose(isolate, tmpl, StatementSync::Dispose);
  env->set_sqlite_statement_sync_constructor_template(tmpl);
  }
 return tmpl;

src/node_sqlite.h

@@ -285,6 +285,7 @@ class StatementSync : public BaseObject {
 staticvoidSetReadBigInts(const v8::FunctionCallbackInfo<v8::Value>& args);
 staticvoidSetReturnArrays(const v8::FunctionCallbackInfo<v8::Value>& args);
 staticvoidClose(const v8::FunctionCallbackInfo<v8::Value>& args);
+staticvoidDispose(const v8::FunctionCallbackInfo<v8::Value>& args);
  v8::MaybeLocal<v8::Value> ColumnToValue(constint column);
  v8::MaybeLocal<v8::Name> ColumnNameToName(constint column);
 boolGetCachedColumnNames(v8::LocalVector<v8::Name>* keys);

test/parallel/test-sqlite-named-parameters.js

@@ -109,6 +109,22 @@ suite('StatementSync.prototype.setAllowUnknownNamedParameters()', () => {
 message: /The"enabled"argumentmustbeaboolean/,
 });
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+constsetup=db.exec(
+'CREATE TABLE data(key INTEGER PRIMARY KEY, val INTEGER) STRICT;'
+);
+t.assert.strictEqual(setup,undefined);
+conststmt=db.prepare('INSERT INTO data (key, val) VALUES ($k, $v)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.setAllowUnknownNamedParameters(true);
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('options.allowUnknownNamedParameters',()=>{

test/parallel/test-sqlite-statement-sync.js

@@ -67,6 +67,18 @@ suite('StatementSync.prototype.get()', () => {
 __proto__: null,key: 'key1',val: 'val1',
 });
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.get();
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.all()',()=>{
@@ -120,6 +132,18 @@ suite('StatementSync.prototype.all()', () => {
 {__proto__: null,key: 'key1',val: 'val1'},
 ]);
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.all();
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.iterate()',()=>{
@@ -286,6 +310,18 @@ suite('StatementSync.prototype.iterate()', () => {
 stmt2.get();
 it.next();
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.iterate();
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.run()',()=>{
@@ -385,6 +421,18 @@ suite('StatementSync.prototype.run()', () => {
 conststmt=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)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.run();
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.sourceSQL',()=>{
@@ -399,6 +447,16 @@ suite('StatementSync.prototype.sourceSQL', () => {
 conststmt=db.prepare(sql);
 t.assert.strictEqual(stmt.sourceSQL,sql);
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>stmt.sourceSQL,{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.expandedSQL',()=>{
@@ -418,6 +476,16 @@ suite('StatementSync.prototype.expandedSQL', () => {
 );
 t.assert.strictEqual(stmt.expandedSQL,expanded);
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>stmt.expandedSQL,{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.setReadBigInts()',()=>{
@@ -487,6 +555,18 @@ suite('StatementSync.prototype.setReadBigInts()', () => {
 [`${Number.MAX_SAFE_INTEGER} + 1`]: 2n**53n,
 });
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.setReadBigInts(true);
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.setReturnArrays()',()=>{
@@ -505,6 +585,18 @@ suite('StatementSync.prototype.setReturnArrays()', () => {
 message: /The"returnArrays"argumentmustbeaboolean/,
 });
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.setReturnArrays(true);
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.get() with array output',()=>{
@@ -723,6 +815,18 @@ suite('StatementSync.prototype.setAllowBareNamedParameters()', () => {
 message: /The"allowBareNamedParameters"argumentmustbeaboolean/,
 });
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.setAllowBareNamedParameters(true);
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('options.readBigInts',()=>{
@@ -971,6 +1075,31 @@ suite('options.allowBareNamedParameters', () => {
 });
 
 
+suite('StatementSync.prototype.close()',()=>{
+test('finalizes an open statement',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+db.exec('CREATE TABLE storage(key TEXT, val TEXT)');
+conststmt=db.prepare('SELECT * FROM storage');
+t.assert.strictEqual(stmt.close(),undefined);
+t.assert.throws(()=>stmt.get(),{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.close();
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
+});
+
 suite('StatementSync.prototype[Symbol.dispose]()',()=>{
 test('finalizes an open statement',(t)=>{
 usingdb=newDatabaseSync(':memory:');

doc/api/sqlite.md

@@ -989,6 +989,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
@@ -1683,6 +1692,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

src/node_sqlite.cc

@@ -2656,6 +2656,15 @@ inline bool StatementSync::IsFinalized() {
 }
 
 voidStatementSync::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();
+}
+
+voidStatementSync::Dispose(const FunctionCallbackInfo<Value>& args) {
  StatementSync* stmt;
 ASSIGN_OR_RETURN_UNWRAP(&stmt, args.This());
  stmt->Close();
@@ -3694,7 +3703,8 @@ Local<FunctionTemplate> StatementSync::GetConstructorTemplate(
  isolate, tmpl, "setReadBigInts", StatementSync::SetReadBigInts);
 SetProtoMethod(
  isolate, tmpl, "setReturnArrays", StatementSync::SetReturnArrays);
-SetProtoDispose(isolate, tmpl, StatementSync::Close);
+SetProtoMethod(isolate, tmpl, "close", StatementSync::Close);
+SetProtoDispose(isolate, tmpl, StatementSync::Dispose);
  env->set_sqlite_statement_sync_constructor_template(tmpl);
  }
 return tmpl;

src/node_sqlite.h

@@ -285,6 +285,7 @@ class StatementSync : public BaseObject {
 staticvoidSetReadBigInts(const v8::FunctionCallbackInfo<v8::Value>& args);
 staticvoidSetReturnArrays(const v8::FunctionCallbackInfo<v8::Value>& args);
 staticvoidClose(const v8::FunctionCallbackInfo<v8::Value>& args);
+staticvoidDispose(const v8::FunctionCallbackInfo<v8::Value>& args);
  v8::MaybeLocal<v8::Value> ColumnToValue(constint column);
  v8::MaybeLocal<v8::Name> ColumnNameToName(constint column);
 boolGetCachedColumnNames(v8::LocalVector<v8::Name>* keys);

test/parallel/test-sqlite-named-parameters.js

@@ -109,6 +109,22 @@ suite('StatementSync.prototype.setAllowUnknownNamedParameters()', () => {
 message: /The"enabled"argumentmustbeaboolean/,
 });
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+constsetup=db.exec(
+'CREATE TABLE data(key INTEGER PRIMARY KEY, val INTEGER) STRICT;'
+);
+t.assert.strictEqual(setup,undefined);
+conststmt=db.prepare('INSERT INTO data (key, val) VALUES ($k, $v)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.setAllowUnknownNamedParameters(true);
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('options.allowUnknownNamedParameters',()=>{

test/parallel/test-sqlite-statement-sync.js

@@ -67,6 +67,18 @@ suite('StatementSync.prototype.get()', () => {
 __proto__: null,key: 'key1',val: 'val1',
 });
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.get();
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.all()',()=>{
@@ -120,6 +132,18 @@ suite('StatementSync.prototype.all()', () => {
 {__proto__: null,key: 'key1',val: 'val1'},
 ]);
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.all();
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.iterate()',()=>{
@@ -286,6 +310,18 @@ suite('StatementSync.prototype.iterate()', () => {
 stmt2.get();
 it.next();
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.iterate();
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.run()',()=>{
@@ -385,6 +421,18 @@ suite('StatementSync.prototype.run()', () => {
 conststmt=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)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.run();
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.sourceSQL',()=>{
@@ -399,6 +447,16 @@ suite('StatementSync.prototype.sourceSQL', () => {
 conststmt=db.prepare(sql);
 t.assert.strictEqual(stmt.sourceSQL,sql);
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>stmt.sourceSQL,{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.expandedSQL',()=>{
@@ -418,6 +476,16 @@ suite('StatementSync.prototype.expandedSQL', () => {
 );
 t.assert.strictEqual(stmt.expandedSQL,expanded);
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>stmt.expandedSQL,{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.setReadBigInts()',()=>{
@@ -487,6 +555,18 @@ suite('StatementSync.prototype.setReadBigInts()', () => {
 [`${Number.MAX_SAFE_INTEGER} + 1`]: 2n**53n,
 });
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.setReadBigInts(true);
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.setReturnArrays()',()=>{
@@ -505,6 +585,18 @@ suite('StatementSync.prototype.setReturnArrays()', () => {
 message: /The"returnArrays"argumentmustbeaboolean/,
 });
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.setReturnArrays(true);
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.get() with array output',()=>{
@@ -723,6 +815,18 @@ suite('StatementSync.prototype.setAllowBareNamedParameters()', () => {
 message: /The"allowBareNamedParameters"argumentmustbeaboolean/,
 });
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.setAllowBareNamedParameters(true);
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('options.readBigInts',()=>{
@@ -971,6 +1075,31 @@ suite('options.allowBareNamedParameters', () => {
 });
 
 
+suite('StatementSync.prototype.close()',()=>{
+test('finalizes an open statement',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+db.exec('CREATE TABLE storage(key TEXT, val TEXT)');
+conststmt=db.prepare('SELECT * FROM storage');
+t.assert.strictEqual(stmt.close(),undefined);
+t.assert.throws(()=>stmt.get(),{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.close();
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
+});
+
 suite('StatementSync.prototype[Symbol.dispose]()',()=>{
 test('finalizes an open statement',(t)=>{
 usingdb=newDatabaseSync(':memory:');

doc/api/sqlite.md

@@ -989,6 +989,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
@@ -1683,6 +1692,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

src/node_sqlite.cc

@@ -2656,6 +2656,15 @@ inline bool StatementSync::IsFinalized() {
 }
 
 voidStatementSync::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();
+}
+
+voidStatementSync::Dispose(const FunctionCallbackInfo<Value>& args) {
  StatementSync* stmt;
 ASSIGN_OR_RETURN_UNWRAP(&stmt, args.This());
  stmt->Close();
@@ -3694,7 +3703,8 @@ Local<FunctionTemplate> StatementSync::GetConstructorTemplate(
  isolate, tmpl, "setReadBigInts", StatementSync::SetReadBigInts);
 SetProtoMethod(
  isolate, tmpl, "setReturnArrays", StatementSync::SetReturnArrays);
-SetProtoDispose(isolate, tmpl, StatementSync::Close);
+SetProtoMethod(isolate, tmpl, "close", StatementSync::Close);
+SetProtoDispose(isolate, tmpl, StatementSync::Dispose);
  env->set_sqlite_statement_sync_constructor_template(tmpl);
  }
 return tmpl;

src/node_sqlite.h

@@ -285,6 +285,7 @@ class StatementSync : public BaseObject {
 staticvoidSetReadBigInts(const v8::FunctionCallbackInfo<v8::Value>& args);
 staticvoidSetReturnArrays(const v8::FunctionCallbackInfo<v8::Value>& args);
 staticvoidClose(const v8::FunctionCallbackInfo<v8::Value>& args);
+staticvoidDispose(const v8::FunctionCallbackInfo<v8::Value>& args);
  v8::MaybeLocal<v8::Value> ColumnToValue(constint column);
  v8::MaybeLocal<v8::Name> ColumnNameToName(constint column);
 boolGetCachedColumnNames(v8::LocalVector<v8::Name>* keys);

test/parallel/test-sqlite-named-parameters.js

@@ -109,6 +109,22 @@ suite('StatementSync.prototype.setAllowUnknownNamedParameters()', () => {
 message: /The"enabled"argumentmustbeaboolean/,
 });
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+constsetup=db.exec(
+'CREATE TABLE data(key INTEGER PRIMARY KEY, val INTEGER) STRICT;'
+);
+t.assert.strictEqual(setup,undefined);
+conststmt=db.prepare('INSERT INTO data (key, val) VALUES ($k, $v)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.setAllowUnknownNamedParameters(true);
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('options.allowUnknownNamedParameters',()=>{

test/parallel/test-sqlite-statement-sync.js

@@ -67,6 +67,18 @@ suite('StatementSync.prototype.get()', () => {
 __proto__: null,key: 'key1',val: 'val1',
 });
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.get();
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.all()',()=>{
@@ -120,6 +132,18 @@ suite('StatementSync.prototype.all()', () => {
 {__proto__: null,key: 'key1',val: 'val1'},
 ]);
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.all();
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.iterate()',()=>{
@@ -286,6 +310,18 @@ suite('StatementSync.prototype.iterate()', () => {
 stmt2.get();
 it.next();
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.iterate();
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.run()',()=>{
@@ -385,6 +421,18 @@ suite('StatementSync.prototype.run()', () => {
 conststmt=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)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.run();
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.sourceSQL',()=>{
@@ -399,6 +447,16 @@ suite('StatementSync.prototype.sourceSQL', () => {
 conststmt=db.prepare(sql);
 t.assert.strictEqual(stmt.sourceSQL,sql);
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>stmt.sourceSQL,{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.expandedSQL',()=>{
@@ -418,6 +476,16 @@ suite('StatementSync.prototype.expandedSQL', () => {
 );
 t.assert.strictEqual(stmt.expandedSQL,expanded);
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>stmt.expandedSQL,{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.setReadBigInts()',()=>{
@@ -487,6 +555,18 @@ suite('StatementSync.prototype.setReadBigInts()', () => {
 [`${Number.MAX_SAFE_INTEGER} + 1`]: 2n**53n,
 });
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.setReadBigInts(true);
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.setReturnArrays()',()=>{
@@ -505,6 +585,18 @@ suite('StatementSync.prototype.setReturnArrays()', () => {
 message: /The"returnArrays"argumentmustbeaboolean/,
 });
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.setReturnArrays(true);
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.get() with array output',()=>{
@@ -723,6 +815,18 @@ suite('StatementSync.prototype.setAllowBareNamedParameters()', () => {
 message: /The"allowBareNamedParameters"argumentmustbeaboolean/,
 });
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.setAllowBareNamedParameters(true);
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('options.readBigInts',()=>{
@@ -971,6 +1075,31 @@ suite('options.allowBareNamedParameters', () => {
 });
 
 
+suite('StatementSync.prototype.close()',()=>{
+test('finalizes an open statement',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+db.exec('CREATE TABLE storage(key TEXT, val TEXT)');
+conststmt=db.prepare('SELECT * FROM storage');
+t.assert.strictEqual(stmt.close(),undefined);
+t.assert.throws(()=>stmt.get(),{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.close();
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
+});
+
 suite('StatementSync.prototype[Symbol.dispose]()',()=>{
 test('finalizes an open statement',(t)=>{
 usingdb=newDatabaseSync(':memory:');

doc/api/sqlite.md

@@ -989,6 +989,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
@@ -1683,6 +1692,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

src/node_sqlite.cc

@@ -2656,6 +2656,15 @@ inline bool StatementSync::IsFinalized() {
 }
 
 voidStatementSync::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();
+}
+
+voidStatementSync::Dispose(const FunctionCallbackInfo<Value>& args) {
  StatementSync* stmt;
 ASSIGN_OR_RETURN_UNWRAP(&stmt, args.This());
  stmt->Close();
@@ -3694,7 +3703,8 @@ Local<FunctionTemplate> StatementSync::GetConstructorTemplate(
  isolate, tmpl, "setReadBigInts", StatementSync::SetReadBigInts);
 SetProtoMethod(
  isolate, tmpl, "setReturnArrays", StatementSync::SetReturnArrays);
-SetProtoDispose(isolate, tmpl, StatementSync::Close);
+SetProtoMethod(isolate, tmpl, "close", StatementSync::Close);
+SetProtoDispose(isolate, tmpl, StatementSync::Dispose);
  env->set_sqlite_statement_sync_constructor_template(tmpl);
  }
 return tmpl;

src/node_sqlite.h

@@ -285,6 +285,7 @@ class StatementSync : public BaseObject {
 staticvoidSetReadBigInts(const v8::FunctionCallbackInfo<v8::Value>& args);
 staticvoidSetReturnArrays(const v8::FunctionCallbackInfo<v8::Value>& args);
 staticvoidClose(const v8::FunctionCallbackInfo<v8::Value>& args);
+staticvoidDispose(const v8::FunctionCallbackInfo<v8::Value>& args);
  v8::MaybeLocal<v8::Value> ColumnToValue(constint column);
  v8::MaybeLocal<v8::Name> ColumnNameToName(constint column);
 boolGetCachedColumnNames(v8::LocalVector<v8::Name>* keys);

test/parallel/test-sqlite-named-parameters.js

@@ -109,6 +109,22 @@ suite('StatementSync.prototype.setAllowUnknownNamedParameters()', () => {
 message: /The"enabled"argumentmustbeaboolean/,
 });
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+constsetup=db.exec(
+'CREATE TABLE data(key INTEGER PRIMARY KEY, val INTEGER) STRICT;'
+);
+t.assert.strictEqual(setup,undefined);
+conststmt=db.prepare('INSERT INTO data (key, val) VALUES ($k, $v)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.setAllowUnknownNamedParameters(true);
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('options.allowUnknownNamedParameters',()=>{

test/parallel/test-sqlite-statement-sync.js

@@ -67,6 +67,18 @@ suite('StatementSync.prototype.get()', () => {
 __proto__: null,key: 'key1',val: 'val1',
 });
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.get();
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.all()',()=>{
@@ -120,6 +132,18 @@ suite('StatementSync.prototype.all()', () => {
 {__proto__: null,key: 'key1',val: 'val1'},
 ]);
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.all();
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.iterate()',()=>{
@@ -286,6 +310,18 @@ suite('StatementSync.prototype.iterate()', () => {
 stmt2.get();
 it.next();
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.iterate();
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.run()',()=>{
@@ -385,6 +421,18 @@ suite('StatementSync.prototype.run()', () => {
 conststmt=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)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.run();
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.sourceSQL',()=>{
@@ -399,6 +447,16 @@ suite('StatementSync.prototype.sourceSQL', () => {
 conststmt=db.prepare(sql);
 t.assert.strictEqual(stmt.sourceSQL,sql);
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>stmt.sourceSQL,{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.expandedSQL',()=>{
@@ -418,6 +476,16 @@ suite('StatementSync.prototype.expandedSQL', () => {
 );
 t.assert.strictEqual(stmt.expandedSQL,expanded);
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>stmt.expandedSQL,{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.setReadBigInts()',()=>{
@@ -487,6 +555,18 @@ suite('StatementSync.prototype.setReadBigInts()', () => {
 [`${Number.MAX_SAFE_INTEGER} + 1`]: 2n**53n,
 });
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.setReadBigInts(true);
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.setReturnArrays()',()=>{
@@ -505,6 +585,18 @@ suite('StatementSync.prototype.setReturnArrays()', () => {
 message: /The"returnArrays"argumentmustbeaboolean/,
 });
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.setReturnArrays(true);
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.get() with array output',()=>{
@@ -723,6 +815,18 @@ suite('StatementSync.prototype.setAllowBareNamedParameters()', () => {
 message: /The"allowBareNamedParameters"argumentmustbeaboolean/,
 });
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.setAllowBareNamedParameters(true);
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('options.readBigInts',()=>{
@@ -971,6 +1075,31 @@ suite('options.allowBareNamedParameters', () => {
 });
 
 
+suite('StatementSync.prototype.close()',()=>{
+test('finalizes an open statement',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+db.exec('CREATE TABLE storage(key TEXT, val TEXT)');
+conststmt=db.prepare('SELECT * FROM storage');
+t.assert.strictEqual(stmt.close(),undefined);
+t.assert.throws(()=>stmt.get(),{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.close();
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
+});
+
 suite('StatementSync.prototype[Symbol.dispose]()',()=>{
 test('finalizes an open statement',(t)=>{
 usingdb=newDatabaseSync(':memory:');

doc/api/sqlite.md

@@ -989,6 +989,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
@@ -1683,6 +1692,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

src/node_sqlite.cc

@@ -2656,6 +2656,15 @@ inline bool StatementSync::IsFinalized() {
 }
 
 voidStatementSync::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();
+}
+
+voidStatementSync::Dispose(const FunctionCallbackInfo<Value>& args) {
  StatementSync* stmt;
 ASSIGN_OR_RETURN_UNWRAP(&stmt, args.This());
  stmt->Close();
@@ -3694,7 +3703,8 @@ Local<FunctionTemplate> StatementSync::GetConstructorTemplate(
  isolate, tmpl, "setReadBigInts", StatementSync::SetReadBigInts);
 SetProtoMethod(
  isolate, tmpl, "setReturnArrays", StatementSync::SetReturnArrays);
-SetProtoDispose(isolate, tmpl, StatementSync::Close);
+SetProtoMethod(isolate, tmpl, "close", StatementSync::Close);
+SetProtoDispose(isolate, tmpl, StatementSync::Dispose);
  env->set_sqlite_statement_sync_constructor_template(tmpl);
  }
 return tmpl;

src/node_sqlite.h

@@ -285,6 +285,7 @@ class StatementSync : public BaseObject {
 staticvoidSetReadBigInts(const v8::FunctionCallbackInfo<v8::Value>& args);
 staticvoidSetReturnArrays(const v8::FunctionCallbackInfo<v8::Value>& args);
 staticvoidClose(const v8::FunctionCallbackInfo<v8::Value>& args);
+staticvoidDispose(const v8::FunctionCallbackInfo<v8::Value>& args);
  v8::MaybeLocal<v8::Value> ColumnToValue(constint column);
  v8::MaybeLocal<v8::Name> ColumnNameToName(constint column);
 boolGetCachedColumnNames(v8::LocalVector<v8::Name>* keys);

test/parallel/test-sqlite-named-parameters.js

@@ -109,6 +109,22 @@ suite('StatementSync.prototype.setAllowUnknownNamedParameters()', () => {
 message: /The"enabled"argumentmustbeaboolean/,
 });
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+constsetup=db.exec(
+'CREATE TABLE data(key INTEGER PRIMARY KEY, val INTEGER) STRICT;'
+);
+t.assert.strictEqual(setup,undefined);
+conststmt=db.prepare('INSERT INTO data (key, val) VALUES ($k, $v)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.setAllowUnknownNamedParameters(true);
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('options.allowUnknownNamedParameters',()=>{

test/parallel/test-sqlite-statement-sync.js

@@ -67,6 +67,18 @@ suite('StatementSync.prototype.get()', () => {
 __proto__: null,key: 'key1',val: 'val1',
 });
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.get();
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.all()',()=>{
@@ -120,6 +132,18 @@ suite('StatementSync.prototype.all()', () => {
 {__proto__: null,key: 'key1',val: 'val1'},
 ]);
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.all();
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.iterate()',()=>{
@@ -286,6 +310,18 @@ suite('StatementSync.prototype.iterate()', () => {
 stmt2.get();
 it.next();
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.iterate();
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.run()',()=>{
@@ -385,6 +421,18 @@ suite('StatementSync.prototype.run()', () => {
 conststmt=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)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.run();
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.sourceSQL',()=>{
@@ -399,6 +447,16 @@ suite('StatementSync.prototype.sourceSQL', () => {
 conststmt=db.prepare(sql);
 t.assert.strictEqual(stmt.sourceSQL,sql);
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>stmt.sourceSQL,{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.expandedSQL',()=>{
@@ -418,6 +476,16 @@ suite('StatementSync.prototype.expandedSQL', () => {
 );
 t.assert.strictEqual(stmt.expandedSQL,expanded);
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>stmt.expandedSQL,{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.setReadBigInts()',()=>{
@@ -487,6 +555,18 @@ suite('StatementSync.prototype.setReadBigInts()', () => {
 [`${Number.MAX_SAFE_INTEGER} + 1`]: 2n**53n,
 });
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.setReadBigInts(true);
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.setReturnArrays()',()=>{
@@ -505,6 +585,18 @@ suite('StatementSync.prototype.setReturnArrays()', () => {
 message: /The"returnArrays"argumentmustbeaboolean/,
 });
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.setReturnArrays(true);
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('StatementSync.prototype.get() with array output',()=>{
@@ -723,6 +815,18 @@ suite('StatementSync.prototype.setAllowBareNamedParameters()', () => {
 message: /The"allowBareNamedParameters"argumentmustbeaboolean/,
 });
 });
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.setAllowBareNamedParameters(true);
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
 });
 
 suite('options.readBigInts',()=>{
@@ -971,6 +1075,31 @@ suite('options.allowBareNamedParameters', () => {
 });
 
 
+suite('StatementSync.prototype.close()',()=>{
+test('finalizes an open statement',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+db.exec('CREATE TABLE storage(key TEXT, val TEXT)');
+conststmt=db.prepare('SELECT * FROM storage');
+t.assert.strictEqual(stmt.close(),undefined);
+t.assert.throws(()=>stmt.get(),{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
+
+test('throws if the statement is already finalized',(t)=>{
+usingdb=newDatabaseSync(':memory:');
+conststmt=db.prepare('CREATE TABLE storage(key TEXT, val TEXT)');
+stmt.close();
+t.assert.throws(()=>{
+stmt.close();
+},{
+code: 'ERR_INVALID_STATE',
+message: /statementhasbeenfinalized/,
+});
+});
+});
+
 suite('StatementSync.prototype[Symbol.dispose]()',()=>{
 test('finalizes an open statement',(t)=>{
 usingdb=newDatabaseSync(':memory:');