sqlite: add StatementSync.prototype.close() and [Symbol.dispose]() by araujogui · Pull Request #64232 · nodejs/node

araujogui · 2026-07-01T14:22:08Z

No description provided.

nodejs-github-bot · 2026-07-01T14:22:14Z

Review requested:

@nodejs/sqlite

Renegade334 · 2026-07-03T17:54:29Z

We are currently finalizing statements when the wrapper is deconstructed after GC. This PR only makes sense if we are going to change this to an explicit "user should finalize statements themselves" model, in which case we should also expose a named .finalize() method that does the same thing. If not, then this probably isn't a logical addition.

araujogui · 2026-07-03T19:21:33Z

We are currently finalizing statements when the wrapper is deconstructed after GC. This PR only makes sense if we are going to change this to an explicit "user should finalize statements themselves" model, in which case we should also expose a named .finalize() method that does the same thing. If not, then this probably isn't a logical addition.

I think we can support both approaches. I don't see any issue with that.

We can either let the GC finalize statements as they are today, or let users finalize them explicitly with a dispose() or the using keyword. The choice is theirs. Explicit finalization is very useful in memory-constrained environments.

jasnell · 2026-07-04T14:46:48Z

... We are currently finalizing statements when the wrapper is deconstructed after GC. This PR only makes sense if we are going to change this to an explicit "user should finalize statements themselves" model ...

Honestly, I'm not a fan at all of relying on GC timing. It's too unpredictable and can expose GC timing details (which can be problematic on its own). We originally had FileHandle automatically close on GC but have since backed away from that to require explicit closing. I think it makes sense to do the same here.

Renegade334 · 2026-07-04T14:48:15Z

That's the case I had in mind. I don't have a problem with the approach, we just need to be very clear to consumers that the contract is changing.

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>

Signed-off-by: Guilherme Araújo <arauujogui@gmail.com>

Renegade334

LGTM. As a follow-up, we should update all of the statement examples in sqlite.md to demonstrate explicit teardown.

codecov · 2026-07-08T18:21:23Z

Codecov Report

❌ Patch coverage is 87.50000% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.24%. Comparing base (799e910) to head (7144743).
⚠️ Report is 342 commits behind head on main.

Files with missing lines	Patch %	Lines
src/node_sqlite.cc	87.50%	0 Missing and 2 partials ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #64232 +/- ##
==========================================
- Coverage 90.25% 90.24% -0.02% 
==========================================
Files 741 741 Lines 241165 241177 +12 Branches 45428 45426 -2 ==========================================
- Hits 217667 217643 -24 - Misses 15069 15114 +45 + Partials 8429 8420 -9

Files with missing lines	Coverage Δ
src/node_sqlite.h	`80.64% <ø> (ø)`
src/node_sqlite.cc	`81.06% <87.50%> (+0.34%)`	⬆️

... and 34 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

nodejs-github-bot · 2026-08-05T22:34:46Z

CI: https://ci.nodejs.org/job/node-test-pull-request/75541/

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> PR-URL: #64232 Reviewed-By: René <contact.9a5d6388@renegade334.me.uk>

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

trivikr · 2026-08-06T01:16:17Z

Landed in 735a09f...51c0d94

Statements could only be finalized by garbage collection or by closing the database, so there was no way to release one deterministically and `using stmt = db.prepare(...)` did nothing. close() finalizes the statement and stops the database tracking it. It throws ERR_INVALID_STATE if the statement is already finalized, if it is currently executing, or if it is called from inside an authorizer callback: finalizing a statement whose sqlite3_step() is on the stack is undefined behavior, and sqlite3_finalize() modifies the connection, which SQLite forbids from an authorizer. That second guard is what every other statement method already does, and is an intentional divergence from node:sqlite, which has no authorizer guard at all. Symbol.dispose never throws, so both unsafe cases become no-ops there and the statement is finalized later by GC or database close. Also drops FinalizeStatement() and FinalizedGetter(), which were never registered on the prototype and so were unreachable. Ports nodejs/node#64232.

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> PR-URL: #64232 Reviewed-By: René <contact.9a5d6388@renegade334.me.uk>

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

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> PR-URL: #64232 Reviewed-By: René <contact.9a5d6388@renegade334.me.uk>

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

Notable changes: benchmark: * (SEMVER-MINOR) add --analyze mode to compare.js (James M Snell) #65416 crypto: * update root certificates to NSS 3.126 (Node.js GitHub Bot) #65495 * (SEMVER-MINOR) enable SIV and GCM-SIV modes in Cipher/Decipher APIs (Filip Skokan) #63411 diagnostics_channel: * mark TracingChannel as stable (Abdelrahman Awad) #64525 lib,src: * (SEMVER-MINOR) improve histogram implementation (James M Snell) #65024 net: * (SEMVER-MINOR) improve performance of net.BlockList (James M Snell) #64974 perf_hooks: * (SEMVER-MINOR) add statistical hypothesis testing to histogram (James M Snell) #65416 repl: * add basic syntax highlighting (Aviv Keller) #64591 sqlite: * (SEMVER-MINOR) add StatementSync.prototype.close() (Guilherme Araújo) #64232 * (SEMVER-MINOR) add StatementSync.prototype[Symbol.dispose]() (Guilherme Araújo) #64232 util: * (SEMVER-MINOR) add non-throwing MIMEType.parse (James M Snell) #64965 zlib: * (SEMVER-MINOR) add ZipEntry, ZipFile, and ZipBuffer (Philipp Dunkel) #64339 PR-URL: #65551

araujogui · 2026-07-01T14:22:08Z

No description provided.

nodejs-github-bot · 2026-07-01T14:22:14Z

Review requested:

@nodejs/sqlite

Renegade334 · 2026-07-03T17:54:29Z

We are currently finalizing statements when the wrapper is deconstructed after GC. This PR only makes sense if we are going to change this to an explicit "user should finalize statements themselves" model, in which case we should also expose a named .finalize() method that does the same thing. If not, then this probably isn't a logical addition.

araujogui · 2026-07-03T19:21:33Z

We are currently finalizing statements when the wrapper is deconstructed after GC. This PR only makes sense if we are going to change this to an explicit "user should finalize statements themselves" model, in which case we should also expose a named .finalize() method that does the same thing. If not, then this probably isn't a logical addition.

I think we can support both approaches. I don't see any issue with that.

We can either let the GC finalize statements as they are today, or let users finalize them explicitly with a dispose() or the using keyword. The choice is theirs. Explicit finalization is very useful in memory-constrained environments.

jasnell · 2026-07-04T14:46:48Z

... We are currently finalizing statements when the wrapper is deconstructed after GC. This PR only makes sense if we are going to change this to an explicit "user should finalize statements themselves" model ...

Honestly, I'm not a fan at all of relying on GC timing. It's too unpredictable and can expose GC timing details (which can be problematic on its own). We originally had FileHandle automatically close on GC but have since backed away from that to require explicit closing. I think it makes sense to do the same here.

Renegade334 · 2026-07-04T14:48:15Z

That's the case I had in mind. I don't have a problem with the approach, we just need to be very clear to consumers that the contract is changing.

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>

Signed-off-by: Guilherme Araújo <arauujogui@gmail.com>

Renegade334

LGTM. As a follow-up, we should update all of the statement examples in sqlite.md to demonstrate explicit teardown.

codecov · 2026-07-08T18:21:23Z

Codecov Report

❌ Patch coverage is 87.50000% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.24%. Comparing base (799e910) to head (7144743).
⚠️ Report is 342 commits behind head on main.

Files with missing lines	Patch %	Lines
src/node_sqlite.cc	87.50%	0 Missing and 2 partials ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #64232 +/- ##
==========================================
- Coverage 90.25% 90.24% -0.02% 
==========================================
Files 741 741 Lines 241165 241177 +12 Branches 45428 45426 -2 ==========================================
- Hits 217667 217643 -24 - Misses 15069 15114 +45 + Partials 8429 8420 -9

Files with missing lines	Coverage Δ
src/node_sqlite.h	`80.64% <ø> (ø)`
src/node_sqlite.cc	`81.06% <87.50%> (+0.34%)`	⬆️

... and 34 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

nodejs-github-bot · 2026-08-05T22:34:46Z

CI: https://ci.nodejs.org/job/node-test-pull-request/75541/

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> PR-URL: #64232 Reviewed-By: René <contact.9a5d6388@renegade334.me.uk>

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

trivikr · 2026-08-06T01:16:17Z

Landed in 735a09f...51c0d94

Statements could only be finalized by garbage collection or by closing the database, so there was no way to release one deterministically and `using stmt = db.prepare(...)` did nothing. close() finalizes the statement and stops the database tracking it. It throws ERR_INVALID_STATE if the statement is already finalized, if it is currently executing, or if it is called from inside an authorizer callback: finalizing a statement whose sqlite3_step() is on the stack is undefined behavior, and sqlite3_finalize() modifies the connection, which SQLite forbids from an authorizer. That second guard is what every other statement method already does, and is an intentional divergence from node:sqlite, which has no authorizer guard at all. Symbol.dispose never throws, so both unsafe cases become no-ops there and the statement is finalized later by GC or database close. Also drops FinalizeStatement() and FinalizedGetter(), which were never registered on the prototype and so were unreachable. Ports nodejs/node#64232.

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> PR-URL: #64232 Reviewed-By: René <contact.9a5d6388@renegade334.me.uk>

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

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> PR-URL: #64232 Reviewed-By: René <contact.9a5d6388@renegade334.me.uk>

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

Notable changes: benchmark: * (SEMVER-MINOR) add --analyze mode to compare.js (James M Snell) #65416 crypto: * update root certificates to NSS 3.126 (Node.js GitHub Bot) #65495 * (SEMVER-MINOR) enable SIV and GCM-SIV modes in Cipher/Decipher APIs (Filip Skokan) #63411 diagnostics_channel: * mark TracingChannel as stable (Abdelrahman Awad) #64525 lib,src: * (SEMVER-MINOR) improve histogram implementation (James M Snell) #65024 net: * (SEMVER-MINOR) improve performance of net.BlockList (James M Snell) #64974 perf_hooks: * (SEMVER-MINOR) add statistical hypothesis testing to histogram (James M Snell) #65416 repl: * add basic syntax highlighting (Aviv Keller) #64591 sqlite: * (SEMVER-MINOR) add StatementSync.prototype.close() (Guilherme Araújo) #64232 * (SEMVER-MINOR) add StatementSync.prototype[Symbol.dispose]() (Guilherme Araújo) #64232 util: * (SEMVER-MINOR) add non-throwing MIMEType.parse (James M Snell) #64965 zlib: * (SEMVER-MINOR) add ZipEntry, ZipFile, and ZipBuffer (Philipp Dunkel) #64339 PR-URL: #65551

araujogui · 2026-07-01T14:22:08Z

No description provided.

nodejs-github-bot · 2026-07-01T14:22:14Z

Review requested:

@nodejs/sqlite

Renegade334 · 2026-07-03T17:54:29Z

We are currently finalizing statements when the wrapper is deconstructed after GC. This PR only makes sense if we are going to change this to an explicit "user should finalize statements themselves" model, in which case we should also expose a named .finalize() method that does the same thing. If not, then this probably isn't a logical addition.

araujogui · 2026-07-03T19:21:33Z

We are currently finalizing statements when the wrapper is deconstructed after GC. This PR only makes sense if we are going to change this to an explicit "user should finalize statements themselves" model, in which case we should also expose a named .finalize() method that does the same thing. If not, then this probably isn't a logical addition.

I think we can support both approaches. I don't see any issue with that.

We can either let the GC finalize statements as they are today, or let users finalize them explicitly with a dispose() or the using keyword. The choice is theirs. Explicit finalization is very useful in memory-constrained environments.

jasnell · 2026-07-04T14:46:48Z

... We are currently finalizing statements when the wrapper is deconstructed after GC. This PR only makes sense if we are going to change this to an explicit "user should finalize statements themselves" model ...

Honestly, I'm not a fan at all of relying on GC timing. It's too unpredictable and can expose GC timing details (which can be problematic on its own). We originally had FileHandle automatically close on GC but have since backed away from that to require explicit closing. I think it makes sense to do the same here.

Renegade334 · 2026-07-04T14:48:15Z

That's the case I had in mind. I don't have a problem with the approach, we just need to be very clear to consumers that the contract is changing.

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>

Signed-off-by: Guilherme Araújo <arauujogui@gmail.com>

Renegade334

LGTM. As a follow-up, we should update all of the statement examples in sqlite.md to demonstrate explicit teardown.

codecov · 2026-07-08T18:21:23Z

Codecov Report

❌ Patch coverage is 87.50000% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.24%. Comparing base (799e910) to head (7144743).
⚠️ Report is 342 commits behind head on main.

Files with missing lines	Patch %	Lines
src/node_sqlite.cc	87.50%	0 Missing and 2 partials ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #64232 +/- ##
==========================================
- Coverage 90.25% 90.24% -0.02% 
==========================================
Files 741 741 Lines 241165 241177 +12 Branches 45428 45426 -2 ==========================================
- Hits 217667 217643 -24 - Misses 15069 15114 +45 + Partials 8429 8420 -9

Files with missing lines	Coverage Δ
src/node_sqlite.h	`80.64% <ø> (ø)`
src/node_sqlite.cc	`81.06% <87.50%> (+0.34%)`	⬆️

... and 34 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

nodejs-github-bot · 2026-08-05T22:34:46Z

CI: https://ci.nodejs.org/job/node-test-pull-request/75541/

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> PR-URL: #64232 Reviewed-By: René <contact.9a5d6388@renegade334.me.uk>

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

trivikr · 2026-08-06T01:16:17Z

Landed in 735a09f...51c0d94

Statements could only be finalized by garbage collection or by closing the database, so there was no way to release one deterministically and `using stmt = db.prepare(...)` did nothing. close() finalizes the statement and stops the database tracking it. It throws ERR_INVALID_STATE if the statement is already finalized, if it is currently executing, or if it is called from inside an authorizer callback: finalizing a statement whose sqlite3_step() is on the stack is undefined behavior, and sqlite3_finalize() modifies the connection, which SQLite forbids from an authorizer. That second guard is what every other statement method already does, and is an intentional divergence from node:sqlite, which has no authorizer guard at all. Symbol.dispose never throws, so both unsafe cases become no-ops there and the statement is finalized later by GC or database close. Also drops FinalizeStatement() and FinalizedGetter(), which were never registered on the prototype and so were unreachable. Ports nodejs/node#64232.

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> PR-URL: #64232 Reviewed-By: René <contact.9a5d6388@renegade334.me.uk>

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

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> PR-URL: #64232 Reviewed-By: René <contact.9a5d6388@renegade334.me.uk>

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

Notable changes: benchmark: * (SEMVER-MINOR) add --analyze mode to compare.js (James M Snell) #65416 crypto: * update root certificates to NSS 3.126 (Node.js GitHub Bot) #65495 * (SEMVER-MINOR) enable SIV and GCM-SIV modes in Cipher/Decipher APIs (Filip Skokan) #63411 diagnostics_channel: * mark TracingChannel as stable (Abdelrahman Awad) #64525 lib,src: * (SEMVER-MINOR) improve histogram implementation (James M Snell) #65024 net: * (SEMVER-MINOR) improve performance of net.BlockList (James M Snell) #64974 perf_hooks: * (SEMVER-MINOR) add statistical hypothesis testing to histogram (James M Snell) #65416 repl: * add basic syntax highlighting (Aviv Keller) #64591 sqlite: * (SEMVER-MINOR) add StatementSync.prototype.close() (Guilherme Araújo) #64232 * (SEMVER-MINOR) add StatementSync.prototype[Symbol.dispose]() (Guilherme Araújo) #64232 util: * (SEMVER-MINOR) add non-throwing MIMEType.parse (James M Snell) #64965 zlib: * (SEMVER-MINOR) add ZipEntry, ZipFile, and ZipBuffer (Philipp Dunkel) #64339 PR-URL: #65551

araujogui · 2026-07-01T14:22:08Z

No description provided.

nodejs-github-bot · 2026-07-01T14:22:14Z

Review requested:

@nodejs/sqlite

Renegade334 · 2026-07-03T17:54:29Z

We are currently finalizing statements when the wrapper is deconstructed after GC. This PR only makes sense if we are going to change this to an explicit "user should finalize statements themselves" model, in which case we should also expose a named .finalize() method that does the same thing. If not, then this probably isn't a logical addition.

araujogui · 2026-07-03T19:21:33Z

We are currently finalizing statements when the wrapper is deconstructed after GC. This PR only makes sense if we are going to change this to an explicit "user should finalize statements themselves" model, in which case we should also expose a named .finalize() method that does the same thing. If not, then this probably isn't a logical addition.

I think we can support both approaches. I don't see any issue with that.

We can either let the GC finalize statements as they are today, or let users finalize them explicitly with a dispose() or the using keyword. The choice is theirs. Explicit finalization is very useful in memory-constrained environments.

jasnell · 2026-07-04T14:46:48Z

... We are currently finalizing statements when the wrapper is deconstructed after GC. This PR only makes sense if we are going to change this to an explicit "user should finalize statements themselves" model ...

Honestly, I'm not a fan at all of relying on GC timing. It's too unpredictable and can expose GC timing details (which can be problematic on its own). We originally had FileHandle automatically close on GC but have since backed away from that to require explicit closing. I think it makes sense to do the same here.

Renegade334 · 2026-07-04T14:48:15Z

That's the case I had in mind. I don't have a problem with the approach, we just need to be very clear to consumers that the contract is changing.

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>

Signed-off-by: Guilherme Araújo <arauujogui@gmail.com>

Renegade334

LGTM. As a follow-up, we should update all of the statement examples in sqlite.md to demonstrate explicit teardown.

codecov · 2026-07-08T18:21:23Z

Codecov Report

❌ Patch coverage is 87.50000% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.24%. Comparing base (799e910) to head (7144743).
⚠️ Report is 342 commits behind head on main.

Files with missing lines	Patch %	Lines
src/node_sqlite.cc	87.50%	0 Missing and 2 partials ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #64232 +/- ##
==========================================
- Coverage 90.25% 90.24% -0.02% 
==========================================
Files 741 741 Lines 241165 241177 +12 Branches 45428 45426 -2 ==========================================
- Hits 217667 217643 -24 - Misses 15069 15114 +45 + Partials 8429 8420 -9

Files with missing lines	Coverage Δ
src/node_sqlite.h	`80.64% <ø> (ø)`
src/node_sqlite.cc	`81.06% <87.50%> (+0.34%)`	⬆️

... and 34 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

nodejs-github-bot · 2026-08-05T22:34:46Z

CI: https://ci.nodejs.org/job/node-test-pull-request/75541/

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> PR-URL: #64232 Reviewed-By: René <contact.9a5d6388@renegade334.me.uk>

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

trivikr · 2026-08-06T01:16:17Z

Landed in 735a09f...51c0d94

Statements could only be finalized by garbage collection or by closing the database, so there was no way to release one deterministically and `using stmt = db.prepare(...)` did nothing. close() finalizes the statement and stops the database tracking it. It throws ERR_INVALID_STATE if the statement is already finalized, if it is currently executing, or if it is called from inside an authorizer callback: finalizing a statement whose sqlite3_step() is on the stack is undefined behavior, and sqlite3_finalize() modifies the connection, which SQLite forbids from an authorizer. That second guard is what every other statement method already does, and is an intentional divergence from node:sqlite, which has no authorizer guard at all. Symbol.dispose never throws, so both unsafe cases become no-ops there and the statement is finalized later by GC or database close. Also drops FinalizeStatement() and FinalizedGetter(), which were never registered on the prototype and so were unreachable. Ports nodejs/node#64232.

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> PR-URL: #64232 Reviewed-By: René <contact.9a5d6388@renegade334.me.uk>

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

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> PR-URL: #64232 Reviewed-By: René <contact.9a5d6388@renegade334.me.uk>

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

Notable changes: benchmark: * (SEMVER-MINOR) add --analyze mode to compare.js (James M Snell) #65416 crypto: * update root certificates to NSS 3.126 (Node.js GitHub Bot) #65495 * (SEMVER-MINOR) enable SIV and GCM-SIV modes in Cipher/Decipher APIs (Filip Skokan) #63411 diagnostics_channel: * mark TracingChannel as stable (Abdelrahman Awad) #64525 lib,src: * (SEMVER-MINOR) improve histogram implementation (James M Snell) #65024 net: * (SEMVER-MINOR) improve performance of net.BlockList (James M Snell) #64974 perf_hooks: * (SEMVER-MINOR) add statistical hypothesis testing to histogram (James M Snell) #65416 repl: * add basic syntax highlighting (Aviv Keller) #64591 sqlite: * (SEMVER-MINOR) add StatementSync.prototype.close() (Guilherme Araújo) #64232 * (SEMVER-MINOR) add StatementSync.prototype[Symbol.dispose]() (Guilherme Araújo) #64232 util: * (SEMVER-MINOR) add non-throwing MIMEType.parse (James M Snell) #64965 zlib: * (SEMVER-MINOR) add ZipEntry, ZipFile, and ZipBuffer (Philipp Dunkel) #64339 PR-URL: #65551

araujogui · 2026-07-01T14:22:08Z

No description provided.

nodejs-github-bot · 2026-07-01T14:22:14Z

Review requested:

@nodejs/sqlite

Renegade334 · 2026-07-03T17:54:29Z

We are currently finalizing statements when the wrapper is deconstructed after GC. This PR only makes sense if we are going to change this to an explicit "user should finalize statements themselves" model, in which case we should also expose a named .finalize() method that does the same thing. If not, then this probably isn't a logical addition.

araujogui · 2026-07-03T19:21:33Z

We are currently finalizing statements when the wrapper is deconstructed after GC. This PR only makes sense if we are going to change this to an explicit "user should finalize statements themselves" model, in which case we should also expose a named .finalize() method that does the same thing. If not, then this probably isn't a logical addition.

I think we can support both approaches. I don't see any issue with that.

We can either let the GC finalize statements as they are today, or let users finalize them explicitly with a dispose() or the using keyword. The choice is theirs. Explicit finalization is very useful in memory-constrained environments.

jasnell · 2026-07-04T14:46:48Z

... We are currently finalizing statements when the wrapper is deconstructed after GC. This PR only makes sense if we are going to change this to an explicit "user should finalize statements themselves" model ...

Honestly, I'm not a fan at all of relying on GC timing. It's too unpredictable and can expose GC timing details (which can be problematic on its own). We originally had FileHandle automatically close on GC but have since backed away from that to require explicit closing. I think it makes sense to do the same here.

Renegade334 · 2026-07-04T14:48:15Z

That's the case I had in mind. I don't have a problem with the approach, we just need to be very clear to consumers that the contract is changing.

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>

Signed-off-by: Guilherme Araújo <arauujogui@gmail.com>

Renegade334

LGTM. As a follow-up, we should update all of the statement examples in sqlite.md to demonstrate explicit teardown.

codecov · 2026-07-08T18:21:23Z

Codecov Report

❌ Patch coverage is 87.50000% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.24%. Comparing base (799e910) to head (7144743).
⚠️ Report is 342 commits behind head on main.

Files with missing lines	Patch %	Lines
src/node_sqlite.cc	87.50%	0 Missing and 2 partials ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #64232 +/- ##
==========================================
- Coverage 90.25% 90.24% -0.02% 
==========================================
Files 741 741 Lines 241165 241177 +12 Branches 45428 45426 -2 ==========================================
- Hits 217667 217643 -24 - Misses 15069 15114 +45 + Partials 8429 8420 -9

Files with missing lines	Coverage Δ
src/node_sqlite.h	`80.64% <ø> (ø)`
src/node_sqlite.cc	`81.06% <87.50%> (+0.34%)`	⬆️

... and 34 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

nodejs-github-bot · 2026-08-05T22:34:46Z

CI: https://ci.nodejs.org/job/node-test-pull-request/75541/

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> PR-URL: #64232 Reviewed-By: René <contact.9a5d6388@renegade334.me.uk>

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

trivikr · 2026-08-06T01:16:17Z

Landed in 735a09f...51c0d94

Statements could only be finalized by garbage collection or by closing the database, so there was no way to release one deterministically and `using stmt = db.prepare(...)` did nothing. close() finalizes the statement and stops the database tracking it. It throws ERR_INVALID_STATE if the statement is already finalized, if it is currently executing, or if it is called from inside an authorizer callback: finalizing a statement whose sqlite3_step() is on the stack is undefined behavior, and sqlite3_finalize() modifies the connection, which SQLite forbids from an authorizer. That second guard is what every other statement method already does, and is an intentional divergence from node:sqlite, which has no authorizer guard at all. Symbol.dispose never throws, so both unsafe cases become no-ops there and the statement is finalized later by GC or database close. Also drops FinalizeStatement() and FinalizedGetter(), which were never registered on the prototype and so were unreachable. Ports nodejs/node#64232.

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> PR-URL: #64232 Reviewed-By: René <contact.9a5d6388@renegade334.me.uk>

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

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> PR-URL: #64232 Reviewed-By: René <contact.9a5d6388@renegade334.me.uk>

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

Notable changes: benchmark: * (SEMVER-MINOR) add --analyze mode to compare.js (James M Snell) #65416 crypto: * update root certificates to NSS 3.126 (Node.js GitHub Bot) #65495 * (SEMVER-MINOR) enable SIV and GCM-SIV modes in Cipher/Decipher APIs (Filip Skokan) #63411 diagnostics_channel: * mark TracingChannel as stable (Abdelrahman Awad) #64525 lib,src: * (SEMVER-MINOR) improve histogram implementation (James M Snell) #65024 net: * (SEMVER-MINOR) improve performance of net.BlockList (James M Snell) #64974 perf_hooks: * (SEMVER-MINOR) add statistical hypothesis testing to histogram (James M Snell) #65416 repl: * add basic syntax highlighting (Aviv Keller) #64591 sqlite: * (SEMVER-MINOR) add StatementSync.prototype.close() (Guilherme Araújo) #64232 * (SEMVER-MINOR) add StatementSync.prototype[Symbol.dispose]() (Guilherme Araújo) #64232 util: * (SEMVER-MINOR) add non-throwing MIMEType.parse (James M Snell) #64965 zlib: * (SEMVER-MINOR) add ZipEntry, ZipFile, and ZipBuffer (Philipp Dunkel) #64339 PR-URL: #65551

araujogui · 2026-07-01T14:22:08Z

No description provided.

nodejs-github-bot · 2026-07-01T14:22:14Z

Review requested:

@nodejs/sqlite

Renegade334 · 2026-07-03T17:54:29Z

We are currently finalizing statements when the wrapper is deconstructed after GC. This PR only makes sense if we are going to change this to an explicit "user should finalize statements themselves" model, in which case we should also expose a named .finalize() method that does the same thing. If not, then this probably isn't a logical addition.

araujogui · 2026-07-03T19:21:33Z

We are currently finalizing statements when the wrapper is deconstructed after GC. This PR only makes sense if we are going to change this to an explicit "user should finalize statements themselves" model, in which case we should also expose a named .finalize() method that does the same thing. If not, then this probably isn't a logical addition.

I think we can support both approaches. I don't see any issue with that.

We can either let the GC finalize statements as they are today, or let users finalize them explicitly with a dispose() or the using keyword. The choice is theirs. Explicit finalization is very useful in memory-constrained environments.

jasnell · 2026-07-04T14:46:48Z

... We are currently finalizing statements when the wrapper is deconstructed after GC. This PR only makes sense if we are going to change this to an explicit "user should finalize statements themselves" model ...

Honestly, I'm not a fan at all of relying on GC timing. It's too unpredictable and can expose GC timing details (which can be problematic on its own). We originally had FileHandle automatically close on GC but have since backed away from that to require explicit closing. I think it makes sense to do the same here.

Renegade334 · 2026-07-04T14:48:15Z

That's the case I had in mind. I don't have a problem with the approach, we just need to be very clear to consumers that the contract is changing.

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>

Signed-off-by: Guilherme Araújo <arauujogui@gmail.com>

Renegade334

LGTM. As a follow-up, we should update all of the statement examples in sqlite.md to demonstrate explicit teardown.

codecov · 2026-07-08T18:21:23Z

Codecov Report

❌ Patch coverage is 87.50000% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.24%. Comparing base (799e910) to head (7144743).
⚠️ Report is 342 commits behind head on main.

Files with missing lines	Patch %	Lines
src/node_sqlite.cc	87.50%	0 Missing and 2 partials ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #64232 +/- ##
==========================================
- Coverage 90.25% 90.24% -0.02% 
==========================================
Files 741 741 Lines 241165 241177 +12 Branches 45428 45426 -2 ==========================================
- Hits 217667 217643 -24 - Misses 15069 15114 +45 + Partials 8429 8420 -9

Files with missing lines	Coverage Δ
src/node_sqlite.h	`80.64% <ø> (ø)`
src/node_sqlite.cc	`81.06% <87.50%> (+0.34%)`	⬆️

... and 34 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

nodejs-github-bot · 2026-08-05T22:34:46Z

CI: https://ci.nodejs.org/job/node-test-pull-request/75541/

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> PR-URL: #64232 Reviewed-By: René <contact.9a5d6388@renegade334.me.uk>

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

trivikr · 2026-08-06T01:16:17Z

Landed in 735a09f...51c0d94

Statements could only be finalized by garbage collection or by closing the database, so there was no way to release one deterministically and `using stmt = db.prepare(...)` did nothing. close() finalizes the statement and stops the database tracking it. It throws ERR_INVALID_STATE if the statement is already finalized, if it is currently executing, or if it is called from inside an authorizer callback: finalizing a statement whose sqlite3_step() is on the stack is undefined behavior, and sqlite3_finalize() modifies the connection, which SQLite forbids from an authorizer. That second guard is what every other statement method already does, and is an intentional divergence from node:sqlite, which has no authorizer guard at all. Symbol.dispose never throws, so both unsafe cases become no-ops there and the statement is finalized later by GC or database close. Also drops FinalizeStatement() and FinalizedGetter(), which were never registered on the prototype and so were unreachable. Ports nodejs/node#64232.

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> PR-URL: #64232 Reviewed-By: René <contact.9a5d6388@renegade334.me.uk>

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

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> PR-URL: #64232 Reviewed-By: René <contact.9a5d6388@renegade334.me.uk>

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

Notable changes: benchmark: * (SEMVER-MINOR) add --analyze mode to compare.js (James M Snell) #65416 crypto: * update root certificates to NSS 3.126 (Node.js GitHub Bot) #65495 * (SEMVER-MINOR) enable SIV and GCM-SIV modes in Cipher/Decipher APIs (Filip Skokan) #63411 diagnostics_channel: * mark TracingChannel as stable (Abdelrahman Awad) #64525 lib,src: * (SEMVER-MINOR) improve histogram implementation (James M Snell) #65024 net: * (SEMVER-MINOR) improve performance of net.BlockList (James M Snell) #64974 perf_hooks: * (SEMVER-MINOR) add statistical hypothesis testing to histogram (James M Snell) #65416 repl: * add basic syntax highlighting (Aviv Keller) #64591 sqlite: * (SEMVER-MINOR) add StatementSync.prototype.close() (Guilherme Araújo) #64232 * (SEMVER-MINOR) add StatementSync.prototype[Symbol.dispose]() (Guilherme Araújo) #64232 util: * (SEMVER-MINOR) add non-throwing MIMEType.parse (James M Snell) #64965 zlib: * (SEMVER-MINOR) add ZipEntry, ZipFile, and ZipBuffer (Philipp Dunkel) #64339 PR-URL: #65551

araujogui · 2026-07-01T14:22:08Z

No description provided.

nodejs-github-bot · 2026-07-01T14:22:14Z

Review requested:

@nodejs/sqlite

Renegade334 · 2026-07-03T17:54:29Z

We are currently finalizing statements when the wrapper is deconstructed after GC. This PR only makes sense if we are going to change this to an explicit "user should finalize statements themselves" model, in which case we should also expose a named .finalize() method that does the same thing. If not, then this probably isn't a logical addition.

araujogui · 2026-07-03T19:21:33Z

We are currently finalizing statements when the wrapper is deconstructed after GC. This PR only makes sense if we are going to change this to an explicit "user should finalize statements themselves" model, in which case we should also expose a named .finalize() method that does the same thing. If not, then this probably isn't a logical addition.

I think we can support both approaches. I don't see any issue with that.

We can either let the GC finalize statements as they are today, or let users finalize them explicitly with a dispose() or the using keyword. The choice is theirs. Explicit finalization is very useful in memory-constrained environments.

jasnell · 2026-07-04T14:46:48Z

... We are currently finalizing statements when the wrapper is deconstructed after GC. This PR only makes sense if we are going to change this to an explicit "user should finalize statements themselves" model ...

Honestly, I'm not a fan at all of relying on GC timing. It's too unpredictable and can expose GC timing details (which can be problematic on its own). We originally had FileHandle automatically close on GC but have since backed away from that to require explicit closing. I think it makes sense to do the same here.

Renegade334 · 2026-07-04T14:48:15Z

That's the case I had in mind. I don't have a problem with the approach, we just need to be very clear to consumers that the contract is changing.

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>

Signed-off-by: Guilherme Araújo <arauujogui@gmail.com>

Renegade334

LGTM. As a follow-up, we should update all of the statement examples in sqlite.md to demonstrate explicit teardown.

codecov · 2026-07-08T18:21:23Z

Codecov Report

❌ Patch coverage is 87.50000% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.24%. Comparing base (799e910) to head (7144743).
⚠️ Report is 342 commits behind head on main.

Files with missing lines	Patch %	Lines
src/node_sqlite.cc	87.50%	0 Missing and 2 partials ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #64232 +/- ##
==========================================
- Coverage 90.25% 90.24% -0.02% 
==========================================
Files 741 741 Lines 241165 241177 +12 Branches 45428 45426 -2 ==========================================
- Hits 217667 217643 -24 - Misses 15069 15114 +45 + Partials 8429 8420 -9

Files with missing lines	Coverage Δ
src/node_sqlite.h	`80.64% <ø> (ø)`
src/node_sqlite.cc	`81.06% <87.50%> (+0.34%)`	⬆️

... and 34 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

nodejs-github-bot · 2026-08-05T22:34:46Z

CI: https://ci.nodejs.org/job/node-test-pull-request/75541/

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> PR-URL: #64232 Reviewed-By: René <contact.9a5d6388@renegade334.me.uk>

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

trivikr · 2026-08-06T01:16:17Z

Landed in 735a09f...51c0d94

Statements could only be finalized by garbage collection or by closing the database, so there was no way to release one deterministically and `using stmt = db.prepare(...)` did nothing. close() finalizes the statement and stops the database tracking it. It throws ERR_INVALID_STATE if the statement is already finalized, if it is currently executing, or if it is called from inside an authorizer callback: finalizing a statement whose sqlite3_step() is on the stack is undefined behavior, and sqlite3_finalize() modifies the connection, which SQLite forbids from an authorizer. That second guard is what every other statement method already does, and is an intentional divergence from node:sqlite, which has no authorizer guard at all. Symbol.dispose never throws, so both unsafe cases become no-ops there and the statement is finalized later by GC or database close. Also drops FinalizeStatement() and FinalizedGetter(), which were never registered on the prototype and so were unreachable. Ports nodejs/node#64232.

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> PR-URL: #64232 Reviewed-By: René <contact.9a5d6388@renegade334.me.uk>

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

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> PR-URL: #64232 Reviewed-By: René <contact.9a5d6388@renegade334.me.uk>

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

Notable changes: benchmark: * (SEMVER-MINOR) add --analyze mode to compare.js (James M Snell) #65416 crypto: * update root certificates to NSS 3.126 (Node.js GitHub Bot) #65495 * (SEMVER-MINOR) enable SIV and GCM-SIV modes in Cipher/Decipher APIs (Filip Skokan) #63411 diagnostics_channel: * mark TracingChannel as stable (Abdelrahman Awad) #64525 lib,src: * (SEMVER-MINOR) improve histogram implementation (James M Snell) #65024 net: * (SEMVER-MINOR) improve performance of net.BlockList (James M Snell) #64974 perf_hooks: * (SEMVER-MINOR) add statistical hypothesis testing to histogram (James M Snell) #65416 repl: * add basic syntax highlighting (Aviv Keller) #64591 sqlite: * (SEMVER-MINOR) add StatementSync.prototype.close() (Guilherme Araújo) #64232 * (SEMVER-MINOR) add StatementSync.prototype[Symbol.dispose]() (Guilherme Araújo) #64232 util: * (SEMVER-MINOR) add non-throwing MIMEType.parse (James M Snell) #64965 zlib: * (SEMVER-MINOR) add ZipEntry, ZipFile, and ZipBuffer (Philipp Dunkel) #64339 PR-URL: #65551

araujogui · 2026-07-01T14:22:08Z

No description provided.

nodejs-github-bot · 2026-07-01T14:22:14Z

Review requested:

@nodejs/sqlite

Renegade334 · 2026-07-03T17:54:29Z

We are currently finalizing statements when the wrapper is deconstructed after GC. This PR only makes sense if we are going to change this to an explicit "user should finalize statements themselves" model, in which case we should also expose a named .finalize() method that does the same thing. If not, then this probably isn't a logical addition.

araujogui · 2026-07-03T19:21:33Z

We are currently finalizing statements when the wrapper is deconstructed after GC. This PR only makes sense if we are going to change this to an explicit "user should finalize statements themselves" model, in which case we should also expose a named .finalize() method that does the same thing. If not, then this probably isn't a logical addition.

I think we can support both approaches. I don't see any issue with that.

We can either let the GC finalize statements as they are today, or let users finalize them explicitly with a dispose() or the using keyword. The choice is theirs. Explicit finalization is very useful in memory-constrained environments.

jasnell · 2026-07-04T14:46:48Z

... We are currently finalizing statements when the wrapper is deconstructed after GC. This PR only makes sense if we are going to change this to an explicit "user should finalize statements themselves" model ...

Honestly, I'm not a fan at all of relying on GC timing. It's too unpredictable and can expose GC timing details (which can be problematic on its own). We originally had FileHandle automatically close on GC but have since backed away from that to require explicit closing. I think it makes sense to do the same here.

Renegade334 · 2026-07-04T14:48:15Z

That's the case I had in mind. I don't have a problem with the approach, we just need to be very clear to consumers that the contract is changing.

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>

Signed-off-by: Guilherme Araújo <arauujogui@gmail.com>

Renegade334

LGTM. As a follow-up, we should update all of the statement examples in sqlite.md to demonstrate explicit teardown.

codecov · 2026-07-08T18:21:23Z

Codecov Report

❌ Patch coverage is 87.50000% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.24%. Comparing base (799e910) to head (7144743).
⚠️ Report is 342 commits behind head on main.

Files with missing lines	Patch %	Lines
src/node_sqlite.cc	87.50%	0 Missing and 2 partials ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #64232 +/- ##
==========================================
- Coverage 90.25% 90.24% -0.02% 
==========================================
Files 741 741 Lines 241165 241177 +12 Branches 45428 45426 -2 ==========================================
- Hits 217667 217643 -24 - Misses 15069 15114 +45 + Partials 8429 8420 -9

Files with missing lines	Coverage Δ
src/node_sqlite.h	`80.64% <ø> (ø)`
src/node_sqlite.cc	`81.06% <87.50%> (+0.34%)`	⬆️

... and 34 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

nodejs-github-bot · 2026-08-05T22:34:46Z

CI: https://ci.nodejs.org/job/node-test-pull-request/75541/

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> PR-URL: #64232 Reviewed-By: René <contact.9a5d6388@renegade334.me.uk>

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

trivikr · 2026-08-06T01:16:17Z

Landed in 735a09f...51c0d94

Statements could only be finalized by garbage collection or by closing the database, so there was no way to release one deterministically and `using stmt = db.prepare(...)` did nothing. close() finalizes the statement and stops the database tracking it. It throws ERR_INVALID_STATE if the statement is already finalized, if it is currently executing, or if it is called from inside an authorizer callback: finalizing a statement whose sqlite3_step() is on the stack is undefined behavior, and sqlite3_finalize() modifies the connection, which SQLite forbids from an authorizer. That second guard is what every other statement method already does, and is an intentional divergence from node:sqlite, which has no authorizer guard at all. Symbol.dispose never throws, so both unsafe cases become no-ops there and the statement is finalized later by GC or database close. Also drops FinalizeStatement() and FinalizedGetter(), which were never registered on the prototype and so were unreachable. Ports nodejs/node#64232.

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> PR-URL: #64232 Reviewed-By: René <contact.9a5d6388@renegade334.me.uk>

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

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> PR-URL: #64232 Reviewed-By: René <contact.9a5d6388@renegade334.me.uk>

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

Notable changes: benchmark: * (SEMVER-MINOR) add --analyze mode to compare.js (James M Snell) #65416 crypto: * update root certificates to NSS 3.126 (Node.js GitHub Bot) #65495 * (SEMVER-MINOR) enable SIV and GCM-SIV modes in Cipher/Decipher APIs (Filip Skokan) #63411 diagnostics_channel: * mark TracingChannel as stable (Abdelrahman Awad) #64525 lib,src: * (SEMVER-MINOR) improve histogram implementation (James M Snell) #65024 net: * (SEMVER-MINOR) improve performance of net.BlockList (James M Snell) #64974 perf_hooks: * (SEMVER-MINOR) add statistical hypothesis testing to histogram (James M Snell) #65416 repl: * add basic syntax highlighting (Aviv Keller) #64591 sqlite: * (SEMVER-MINOR) add StatementSync.prototype.close() (Guilherme Araújo) #64232 * (SEMVER-MINOR) add StatementSync.prototype[Symbol.dispose]() (Guilherme Araújo) #64232 util: * (SEMVER-MINOR) add non-throwing MIMEType.parse (James M Snell) #64965 zlib: * (SEMVER-MINOR) add ZipEntry, ZipFile, and ZipBuffer (Philipp Dunkel) #64339 PR-URL: #65551

CopilotAI review requested due to automatic review settings July 1, 2026 14:22

nodejs-github-bot added c++ Issues and PRs that require attention from people who are familiar with C++. needs-ci PRs that need a full CI run. sqlite Issues and PRs related to the SQLite subsystem. labels Jul 1, 2026

Copilotstarted reviewing on behalf of araujogui July 1, 2026 14:22 View session

This comment was marked as low quality.
Sign in to view

aduh95 added semver-minor PRs that contain new features and should be released in the next minor version. backport-requested-v24.x PRs awaiting manual backport to the v24.x-staging branch. labels Jul 2, 2026

araujogui changed the title ~~sqlite: add StatementSync.prototype[Symbol.dispose]()~~sqlite: add StatementSync.prototype.close() and [Symbol.dispose]()Jul 4, 2026

Renegade334 reviewed Jul 4, 2026
View reviewed changes

Comment threadsrc/node_sqlite.cc Outdated

jasnell reviewed Jul 4, 2026
View reviewed changes

Comment threadsrc/node_sqlite.cc Outdated

araujogui force-pushed the sqlite-statement-sync-dispose branch from cb5696c to 9ed6faeCompare July 4, 2026 15:58

araujogui added 4 commits July 8, 2026 13:26

sqlite: simplify StatementSync dispose
9425bac
Signed-off-by: Guilherme Araújo <arauujogui@gmail.com>

sqlite: add StatementSync.prototype.close()
9f6d4eb
Signed-off-by: Guilherme Araújo <arauujogui@gmail.com>

sqlite: remove unnecessary trycatch
7144743
Signed-off-by: Guilherme Araújo <arauujogui@gmail.com>

araujogui force-pushed the sqlite-statement-sync-dispose branch from 9ed6fae to 7144743Compare July 8, 2026 16:29

Renegade334 approved these changes Jul 8, 2026
View reviewed changes

trivikr added the request-ci Add this label to start a Jenkins CI on a PR. label Jul 25, 2026

github-actionsBot removed the request-ci Add this label to start a Jenkins CI on a PR. label Jul 26, 2026

This comment was marked as outdated.
Sign in to view

trivikr pushed a commit that referenced this pull request Aug 6, 2026
sqlite: add StatementSync.prototype.close()
51c0d94
Signed-off-by: Guilherme Araújo <arauujogui@gmail.com> PR-URL: #64232 Reviewed-By: René <contact.9a5d6388@renegade334.me.uk>

trivikr closed this Aug 6, 2026

araujogui mentioned this pull request Aug 6, 2026
doc: finalize statements in sqlite examples #65088
Merged

aduh95 pushed a commit that referenced this pull request Aug 13, 2026
sqlite: add StatementSync.prototype.close()
5b8d12e
Signed-off-by: Guilherme Araújo <arauujogui@gmail.com> PR-URL: #64232 Reviewed-By: René <contact.9a5d6388@renegade334.me.uk>

qodo-code-reviewBot mentioned this pull request Aug 25, 2026
Phase 1: synthetic vault data MachineLearning-Nerd/need-to-know#2
Merged

aduh95 pushed a commit that referenced this pull request Aug 25, 2026
sqlite: add StatementSync.prototype.close()
58ea88e
Signed-off-by: Guilherme Araújo <arauujogui@gmail.com> PR-URL: #64232 Reviewed-By: René <contact.9a5d6388@renegade334.me.uk>

github-actionsBot mentioned this pull request Aug 25, 2026
2026-08-26, Version 26.8.0 (Current) #65551
Merged