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.19%. Comparing base (808e6b3) to head (fa23c05).
Report is 41 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.19%   +0.01%     
==========================================
  Files         662      662              
  Lines      191759   192031     +272     
  Branches    36911    36968      +57     
==========================================
+ Hits       171017   171291     +274     
+ Misses      13613    13576      -37     
- Partials     7129     7164      +35     

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

... and 62 files with indirect coverage changes

[jasnell]

Probably best to check try_catch.CanContinue() before calling Reject to check for fatal errors that are terminating the isolate.

[geeksilva97]

If we do that I think we need to let somehow the user know that the backup is happening even though the progress function is not called.

I added the CanContinue to check and ran the test below.

    await database.backup('database.bkp', {
      progress: () => {.throw 'something went wrong'; }
    });

For this progress function the CanContinue is true. The backup is finished but there's no progress information. I wonder if it might lead to confusion.

Maybe we can emit a warning or something?

[geeksilva97]

Thanks a lot, @jasnell

[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.