sqlite: add stmt persistent flag

[araujogui]

Add statement's persistent argument flag

Reference:
https://sqlite.org/c3ref/c_prepare_dont_log.html#sqlitepreparepersistent

[nodejs-github-bot]

Review requested:

• @nodejs/sqlite

[Copilot]

Pull request overview

Adds a new persistent option to DatabaseSync#prepare() in node:sqlite, exposing SQLite’s SQLITE_PREPARE_PERSISTENT hint to influence statement memory-allocation strategy for frequently reused prepared statements.

Changes:

• Add options.persistent parsing/validation to DatabaseSync::Prepare() and pass SQLITE_PREPARE_PERSISTENT via sqlite3_prepare_v3().
• Add parallel tests covering persistent: true/false, type validation, and interoperability with other options.
• Document the new option and update the implementation reference from sqlite3_prepare_v2() to sqlite3_prepare_v3().

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
src/node_sqlite.cc	Parses options.persistent and uses sqlite3_prepare_v3(..., SQLITE_PREPARE_PERSISTENT) when enabled.
test/parallel/test-sqlite-statement-sync.js	Adds coverage for correct execution and argument validation for persistent.
doc/api/sqlite.md	Documents persistent and updates the underlying SQLite API reference/link definitions.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[araujogui]

Interesting thing: SQLITE_PREPARE_PERSISTENT is enabled by default on better-sqlite3

[codecov]

Codecov Report

❌ Patch coverage is 90.90909% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.33%. Comparing base (1662b69) to head (d32e5e6).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
src/node_sqlite.cc	90.90%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #62757      +/-   ##
==========================================
+ Coverage   90.31%   90.33%   +0.01%     
==========================================
  Files         751      751              
  Lines      249776   249795      +19     
  Branches    47173    47176       +3     
==========================================
+ Hits       225587   225654      +67     
+ Misses      15585    15531      -54     
- Partials     8604     8610       +6     

Files with missing lines	Coverage Δ
src/node_sqlite.cc	81.68% <90.90%> (+0.05%)	⬆️

... and 37 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.

[louwers]

At least makes sense to enable it by default for SQLTagStore statements I'd say.

[araujogui]

@nodejs/sqlite Friendly bump

[trivikr]

@araujogui Can you please rebase from main?

[araujogui]

@araujogui Can you please rebase from main?

Rebased

[trivikr]

Please add a history entry for this new public option; otherwise the docs imply it has been available since v22.5.0.

 changes:
   - version: REPLACEME
     pr-url: https://github.com/nodejs/node/pull/65157
     description: Throw `ERR_INVALID_ARG_VALUE` if `sql` contains no statements.
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/62757
+    description: Add the `persistent` option.

[trivikr]

SQLite does not guarantee reduced heap fragmentation; its documented current behavior is to avoid depleting lookaside memory.

Suggested change

	* `persistent` {boolean} If `true`, hints to SQLite that this statement will
	be reused many times, causing it to use a different memory allocation
	strategy that reduces heap fragmentation. Corresponds to the
	[`SQLITE_PREPARE_PERSISTENT`][] flag. **Default:** `false`.
	* `persistent` {boolean} If `true`, hints to SQLite that this statement will
	be retained for a long time and likely reused many times. SQLite currently
	responds to this hint by avoiding lookaside memory. Corresponds to the
	[`SQLITE_PREPARE_PERSISTENT`][] flag. **Default:** `false`.