sqlite: add support for SQLite Session Extension

PR-URL: https://github.com/nodejs/node/pull/54181
Reviewed-By: Yagiz Nizipli <yagiz@nizipli.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>

doc/api/sqlite.md

@@ -155,6 +155,70 @@ added: v22.5.0
 Compiles a SQL statement into a [prepared statement][]. This method is a wrapper
 around [`sqlite3_prepare_v2()`][].
 
+### `database.createSession([options])`
+
+* `options` {Object} The configuration options for the session.
+  * `table` {string} A specific table to track changes for. By default, changes to all tables are tracked.
+  * `db` {string} Name of the database to track. This is useful when multiple databases have been added using [`ATTACH DATABASE`][]. **Default**: `'main'`.
+* Returns: {Session} A session handle.
+
+Creates and attaches a session to the database. This method is a wrapper around [`sqlite3session_create()`][] and [`sqlite3session_attach()`][].
+
+### `database.applyChangeset(changeset[, options])`
+
+* `changeset` {Uint8Array} A binary changeset or patchset.
+* `options` {Object} The configuration options for how the changes will be applied.
+  * `filter` {Function} Skip changes that, when targeted table name is supplied to this function, return a truthy value.
+    By default, all changes are attempted.
+  * `onConflict` {number} Determines how conflicts are handled. **Default**: `SQLITE_CHANGESET_ABORT`.
+    * `SQLITE_CHANGESET_OMIT`: conflicting changes are omitted.
+    * `SQLITE_CHANGESET_REPLACE`: conflicting changes replace existing values.
+    * `SQLITE_CHANGESET_ABORT`: abort on conflict and roll back databsase.
+* Returns: {boolean} Whether the changeset was applied succesfully without being aborted.
+
+An exception is thrown if the database is not
+open. This method is a wrapper around [`sqlite3changeset_apply()`][].
+
+```js
+const sourceDb = new DatabaseSync(':memory:');
+const targetDb = new DatabaseSync(':memory:');
+
+sourceDb.exec('CREATE TABLE data(key INTEGER PRIMARY KEY, value TEXT)');
+targetDb.exec('CREATE TABLE data(key INTEGER PRIMARY KEY, value TEXT)');
+
+const session = sourceDb.createSession();
+
+const insert = sourceDb.prepare('INSERT INTO data (key, value) VALUES (?, ?)');
+insert.run(1, 'hello');
+insert.run(2, 'world');
+
+const changeset = session.changeset();
+targetDb.applyChangeset(changeset);
+// Now that the changeset has been applied, targetDb contains the same data as sourceDb.
+```
+
+## Class: `Session`
+
+### `session.changeset()`
+
+* Returns: {Uint8Array} Binary changeset that can be applied to other databases.
+
+Retrieves a changeset containing all changes since the changeset was created. Can be called multiple times.
+An exception is thrown if the database or the session is not open. This method is a wrapper around [`sqlite3session_changeset()`][].
+
+### `session.patchset()`
+
+* Returns: {Uint8Array} Binary patchset that can be applied to other databases.
+
+Similar to the method above, but generates a more compact patchset. See [Changesets and Patchsets][]
+in the documentation of SQLite. An exception is thrown if the database or the session is not open. This method is a
+wrapper around [`sqlite3session_patchset()`][].
+
+### `session.close()`.
+
+Closes the session. An exception is thrown if the database or the session is not open. This method is a
+wrapper around [`sqlite3session_delete()`][].
+
 ## Class: `StatementSync`
 
 <!-- YAML
@@ -317,8 +381,39 @@ exception.
 | `TEXT`    | {string}             |
 | `BLOB`    | {Uint8Array}         |
 
+## SQLite constants
+
+The following constants are exported by the `node:sqlite` module.
+
+### SQLite Session constants
+
+#### Conflict-resolution constants
+
+The following constants are meant for use with [`database.applyChangeset()`](#databaseapplychangesetchangeset-options).
+
+<table>
+  <tr>
+    <th>Constant</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td><code>SQLITE_CHANGESET_OMIT</code></td>
+    <td>Conflicting changes are omitted.</td>
+  </tr>
+  <tr>
+    <td><code>SQLITE_CHANGESET_REPLACE</code></td>
+    <td>Conflicting changes replace existing values.</td>
+  </tr>
+  <tr>
+    <td><code>SQLITE_CHANGESET_ABORT</code></td>
+    <td>Abort when a change encounters a conflict and roll back databsase.</td>
+  </tr>
+</table>
+
+[Changesets and Patchsets]: https://www.sqlite.org/sessionintro.html#changesets_and_patchsets
 [SQL injection]: https://en.wikipedia.org/wiki/SQL_injection
 [`--experimental-sqlite`]: cli.md#--experimental-sqlite
+[`ATTACH DATABASE`]: https://www.sqlite.org/lang_attach.html
 [`PRAGMA foreign_keys`]: https://www.sqlite.org/pragma.html#pragma_foreign_keys
 [`sqlite3_changes64()`]: https://www.sqlite.org/c3ref/changes.html
 [`sqlite3_close_v2()`]: https://www.sqlite.org/c3ref/close.html
@@ -327,6 +422,12 @@ exception.
 [`sqlite3_last_insert_rowid()`]: https://www.sqlite.org/c3ref/last_insert_rowid.html
 [`sqlite3_prepare_v2()`]: https://www.sqlite.org/c3ref/prepare.html
 [`sqlite3_sql()`]: https://www.sqlite.org/c3ref/expanded_sql.html
+[`sqlite3changeset_apply()`]: https://www.sqlite.org/session/sqlite3changeset_apply.html
+[`sqlite3session_attach()`]: https://www.sqlite.org/session/sqlite3session_attach.html
+[`sqlite3session_changeset()`]: https://www.sqlite.org/session/sqlite3session_changeset.html
+[`sqlite3session_create()`]: https://www.sqlite.org/session/sqlite3session_create.html
+[`sqlite3session_delete()`]: https://www.sqlite.org/session/sqlite3session_delete.html
+[`sqlite3session_patchset()`]: https://www.sqlite.org/session/sqlite3session_patchset.html
 [connection]: https://www.sqlite.org/c3ref/sqlite3.html
 [data types]: https://www.sqlite.org/datatype3.html
 [double-quoted string literals]: https://www.sqlite.org/quirks.html#dblquote