sqlite: expose backup api

[geeksilva97]

Closes #55413

This PR exposes the SQLite Online Backup API, which allows database backup.

The API is inspired by better-sqlite3 https://github.com/WiseLibs/better-sqlite3/blob/master/docs/api.md#backupdestination-options---promise.

Multithreading caveats

As long as writes come from the same process and handle (sqlite*), the backup will continue progressing as expected. Other than that, it can cause the backup process to restart. From docs:

...If the source database is not an in-memory database, and the write is performed from within the same process as the backup operation and uses the same database handle (pDb), then the destination database (the one opened using connection pFile) is automatically updated along with the source.

Writes to an in-memory source database, or writes to a file-based source database by an external process or thread using a database connection other than pDb are significantly more expensive than writes made to a file-based source database using pDb (as the entire backup operation must be restarted...)

[geeksilva97]

This comment mentions that DatabaseSync needs to have only sync operations (makes sense).

The backup can be performed synchronously but I don't think it should be like that.

I wonder if indeed this PR would be more suitable for async API.

Any thoughts?

Thanks in advance

[codecov]

Codecov Report

Attention: Patch coverage is 81.59204% with 37 lines in your changes missing coverage. Please review.

Project coverage is 89.20%. Comparing base (808e6b3) to head (0df678e).
Report is 61 commits behind head on main.

Files with missing lines	Patch %	Lines
src/node_sqlite.cc	81.59%	15 Missing and 22 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #56253      +/-   ##
==========================================
+ Coverage   89.18%   89.20%   +0.02%     
==========================================
  Files         662      662              
  Lines      191759   192100     +341     
  Branches    36911    36979      +68     
==========================================
+ Hits       171017   171362     +345     
+ Misses      13613    13558      -55     
- Partials     7129     7180      +51     

Files with missing lines	Coverage Δ
src/node_sqlite.h	70.00% <ø> (ø)
src/node_sqlite.cc	79.94% <81.59%> (+0.28%)	⬆️

... and 72 files with indirect coverage changes

[geeksilva97]

Hi hi @cjihrig . Could you share your thoughts?

[nodejs-github-bot]

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

[cjihrig]

I haven't made it through the changes in src/node_sqlite.cc yet, but left some comments. This also needs docs before landing.

[geeksilva97]

Failing test seems unrelated

[geeksilva97]

@jasnell @cjihrig do you think I need to check any memory leak using valgrind here? If so, is there a command in node that would allow me to do so? I saw some make test-valgrind but I don't know how it should be used.

Thanks in advance

[cjihrig]

do you think I need to check any memory leak using valgrind here?

That is not a requirement.

[cjihrig]

Not something that needs to happen in this PR necessarily, but we will need to rename the DatabaseSync class now that an async operation is being added. My plan was always to keep the sync and async APIs separated, similar to the fs module. Since we are breaking from that, I'll leave it up to others to decide on naming, keeping in mind that there is already a feature request for an async API.

[geeksilva97]

Yeah, it could be a start for that async API.

#54307

I asked about this in the issue but I didn't get an answer

[geeksilva97]

Question, @cjihrig . In your plans, would DatabaseSync have a backup feature?

Personally, I have no problem moving this to a Database class (without the Sync) as a start for that async API.

[jasnell]

Does it need to be a method on DatabaseSync? Could it be a separate API exposed on the node:sqlite module? e.g.

const { backup, DatabaseSync } = require('node:sqlite');

const db = new DatabaseSync(...);
// ...
await backup(db);

[geeksilva97]

I like this idea!