lib,src,test,doc: add node:sqlite module

PR-URL: #53752
Fixes: #53264
Reviewed-By: Michaël Zasso <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Benjamin Gruenbaum <[email protected]>
Reviewed-By: Vinícius Lourenço Claro Cardoso <[email protected]>
Reviewed-By: Yagiz Nizipli <[email protected]>
Reviewed-By: Paolo Insogna <[email protected]>
Reviewed-By: Matteo Collina <[email protected]>
Reviewed-By: Stephen Belanger <[email protected]>
Reviewed-By: Chemi Atlow <[email protected]>

doc/api/cli.md

@@ -1045,6 +1045,14 @@ added:
 
 Use this flag to enable [ShadowRealm][] support.
 
+### `--experimental-sqlite`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+Enable the experimental [`node:sqlite`][] module.
+
 ### `--experimental-test-coverage`
 
 <!-- YAML
@@ -2893,6 +2901,7 @@ one is included in the list below.
 * `--experimental-require-module`
 * `--experimental-shadow-realm`
 * `--experimental-specifier-resolution`
+* `--experimental-sqlite`
 * `--experimental-top-level-await`
 * `--experimental-vm-modules`
 * `--experimental-wasi-unstable-preview1`
@@ -3458,6 +3467,7 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
 [`dnsPromises.lookup()`]: dns.md#dnspromiseslookuphostname-options
 [`import` specifier]: esm.md#import-specifiers
 [`net.getDefaultAutoSelectFamilyAttemptTimeout()`]: net.md#netgetdefaultautoselectfamilyattempttimeout
+[`node:sqlite`]: sqlite.md
 [`process.setUncaughtExceptionCaptureCallback()`]: process.md#processsetuncaughtexceptioncapturecallbackfn
 [`process.setuid()`]: process.md#processsetuidid
 [`setuid(2)`]: https://man7.org/linux/man-pages/man2/setuid.2.html

doc/api/errors.md

@@ -2580,6 +2580,16 @@ disconnected socket.
 
 A call was made and the UDP subsystem was not running.
 
+<a id="ERR_SQLITE_ERROR"></a>
+
+### `ERR_SQLITE_ERROR`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+An error was returned from [SQLite][].
+
 <a id="ERR_SRI_PARSE"></a>
 
 ### `ERR_SRI_PARSE`
@@ -4013,6 +4023,7 @@ An error occurred trying to allocate memory. This should never happen.
 [Node.js error codes]: #nodejs-error-codes
 [Permission Model]: permissions.md#permission-model
 [RFC 7230 Section 3]: https://tools.ietf.org/html/rfc7230#section-3
+[SQLite]: sqlite.md
 [Subresource Integrity specification]: https://www.w3.org/TR/SRI/#the-integrity-attribute
 [V8's stack trace API]: https://v8.dev/docs/stack-trace-api
 [WHATWG Supported Encodings]: util.md#whatwg-supported-encodings

doc/api/index.md

@@ -53,6 +53,7 @@
 * [REPL](repl.md)
 * [Report](report.md)
 * [Single executable applications](single-executable-applications.md)
+* [SQLite](sqlite.md)
 * [Stream](stream.md)
 * [String decoder](string_decoder.md)
 * [Test runner](test.md)

doc/api/sqlite.md

@@ -0,0 +1,328 @@
+# SQLite
+
+<!--introduced_in=REPLACEME-->
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1.1 - Active development
+
+<!-- source_link=lib/sqlite.js -->
+
+The `node:sqlite` module facilitates working with SQLite databases.
+To access it:
+
+```mjs
+import sqlite from 'node:sqlite';
+```
+
+```cjs
+const sqlite = require('node:sqlite');
+```
+
+This module is only available under the `node:` scheme. The following will not
+work:
+
+```mjs
+import sqlite from 'sqlite';
+```
+
+```cjs
+const sqlite = require('sqlite');
+```
+
+The following example shows the basic usage of the `node:sqlite` module to open
+an in-memory database, write data to the database, and then read the data back.
+
+```mjs
+import { DatabaseSync } from 'node:sqlite';
+const database = new DatabaseSync(':memory:');
+
+// Execute SQL statements from strings.
+database.exec(`
+  CREATE TABLE data(
+    key INTEGER PRIMARY KEY,
+    value TEXT
+  ) STRICT
+`);
+// Create a prepared statement to insert data into the database.
+const insert = database.prepare('INSERT INTO data (key, value) VALUES (?, ?)');
+// Execute the prepared statement with bound values.
+insert.run(1, 'hello');
+insert.run(2, 'world');
+// Create a prepared statement to read data from the database.
+const query = database.prepare('SELECT * FROM data ORDER BY key');
+// Execute the prepared statement and log the result set.
+console.log(query.all());
+// Prints: [ { key: 1, value: 'hello' }, { key: 2, value: 'world' } ]
+```
+
+```cjs
+'use strict';
+const { DatabaseSync } = require('node:sqlite');
+const database = new DatabaseSync(':memory:');
+
+// Execute SQL statements from strings.
+database.exec(`
+  CREATE TABLE data(
+    key INTEGER PRIMARY KEY,
+    value TEXT
+  ) STRICT
+`);
+// Create a prepared statement to insert data into the database.
+const insert = database.prepare('INSERT INTO data (key, value) VALUES (?, ?)');
+// Execute the prepared statement with bound values.
+insert.run(1, 'hello');
+insert.run(2, 'world');
+// Create a prepared statement to read data from the database.
+const query = database.prepare('SELECT * FROM data ORDER BY key');
+// Execute the prepared statement and log the result set.
+console.log(query.all());
+// Prints: [ { key: 1, value: 'hello' }, { key: 2, value: 'world' } ]
+```
+
+## Class: `DatabaseSync`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+This class represents a single [connection][] to a SQLite database. All APIs
+exposed by this class execute synchronously.
+
+### `new DatabaseSync(location[, options])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `location` {string} The location of the database. A SQLite database can be
+  stored in a file or completely [in memory][]. To use a file-backed database,
+  the location should be a file path. To use an in-memory database, the location
+  should be the special name `':memory:'`.
+* `options` {Object} Configuration options for the database connection. The
+  following options are supported:
+  * `open` {boolean} If `true`, the database is opened by the constructor. When
+    this value is `false`, the database must be opened via the `open()` method.
+    **Default:** `true`.
+
+Constructs a new `DatabaseSync` instance.
+
+### `database.close()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+Closes the database connection. An exception is thrown if the database is not
+open. This method is a wrapper around [`sqlite3_close_v2()`][].
+
+### `database.exec(sql)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `sql` {string} A SQL string to execute.
+
+This method allows one or more SQL statements to be executed without returning
+any results. This method is useful when executing SQL statements read from a
+file. This method is a wrapper around [`sqlite3_exec()`][].
+
+### `database.open()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+Opens the database specified in the `location` argument of the `DatabaseSync`
+constructor. This method should only be used when the database is not opened via
+the constructor. An exception is thrown if the database is already open.
+
+### `database.prepare(sql)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `sql` {string} A SQL string to compile to a prepared statement.
+* Returns: {StatementSync} The prepared statement.
+
+Compiles a SQL statement into a [prepared statement][]. This method is a wrapper
+around [`sqlite3_prepare_v2()`][].
+
+## Class: `StatementSync`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+This class represents a single [prepared statement][]. This class cannot be
+instantiated via its constructor. Instead, instances are created via the
+`database.prepare()` method. All APIs exposed by this class execute
+synchronously.
+
+A prepared statement is an efficient binary representation of the SQL used to
+create it. Prepared statements are parameterizable, and can be invoked multiple
+times with different bound values. Parameters also offer protection against
+[SQL injection][] attacks. For these reasons, prepared statements are preferred
+over hand-crafted SQL strings when handling user input.
+
+### `statement.all([namedParameters][, ...anonymousParameters])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `namedParameters` {Object} An optional object used to bind named parameters.
+  The keys of this object are used to configure the mapping.
+* `...anonymousParameters` {null|number|bigint|string|Buffer|Uint8Array} Zero or
+  more values to bind to anonymous parameters.
+* Returns: {Array} An array of objects. Each object corresponds to a row
+  returned by executing the prepared statement. The keys and values of each
+  object correspond to the column names and values of the row.
+
+This method executes a prepared statement and returns all results as an array of
+objects. If the prepared statement does not return any results, this method
+returns an empty array. The prepared statement [parameters are bound][] using
+the values in `namedParameters` and `anonymousParameters`.
+
+### `statement.expandedSQL()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Returns: {string} The source SQL expanded to include parameter values.
+
+This method returns the source SQL of the prepared statement with parameter
+placeholders replaced by values. This method is a wrapper around
+[`sqlite3_expanded_sql()`][].
+
+### `statement.get([namedParameters][, ...anonymousParameters])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `namedParameters` {Object} An optional object used to bind named parameters.
+  The keys of this object are used to configure the mapping.
+* `...anonymousParameters` {null|number|bigint|string|Buffer|Uint8Array} Zero or
+  more values to bind to anonymous parameters.
+* Returns: {Object|undefined} An object corresponding to the first row returned
+  by executing the prepared statement. The keys and values of the object
+  correspond to the column names and values of the row. If no rows were returned
+  from the database then this method returns `undefined`.
+
+This method executes a prepared statement and returns the first result as an
+object. If the prepared statement does not return any results, this method
+returns `undefined`. The prepared statement [parameters are bound][] using the
+values in `namedParameters` and `anonymousParameters`.
+
+### `statement.run([namedParameters][, ...anonymousParameters])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `namedParameters` {Object} An optional object used to bind named parameters.
+  The keys of this object are used to configure the mapping.
+* `...anonymousParameters` {null|number|bigint|string|Buffer|Uint8Array} Zero or
+  more values to bind to anonymous parameters.
+* Returns: {Object}
+  * `changes`: {number|bigint} The number of rows modified, inserted, or deleted
+    by the most recently completed `INSERT`, `UPDATE`, or `DELETE` statement.
+    This field is either a number or a `BigInt` depending on the prepared
+    statement's configuration. This property is the result of
+    [`sqlite3_changes64()`][].
+  * `lastInsertRowid`: {number|bigint} The most recently inserted rowid. This
+    field is either a number or a `BigInt` depending on the prepared statement's
+    configuration. This property is the result of
+    [`sqlite3_last_insert_rowid()`][].
+
+This method executes a prepared statement and returns an object summarizing the
+resulting changes. The prepared statement [parameters are bound][] using the
+values in `namedParameters` and `anonymousParameters`.
+
+### `statement.setAllowBareNamedParameters(enabled)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `enabled` {boolean} Enables or disables support for binding named parameters
+  without the prefix character.
+
+The names of SQLite parameters begin with a prefix character. By default,
+`node:sqlite` requires that this prefix character is present when binding
+parameters. However, with the exception of dollar sign character, these
+prefix characters also require extra quoting when used in object keys.
+
+To improve ergonomics, this method can be used to also allow bare named
+parameters, which do not require the prefix character in JavaScript code. There
+are several caveats to be aware of when enabling bare named parameters:
+
+* The prefix character is still required in SQL.
+* The prefix character is still allowed in JavaScript. In fact, prefixed names
+  will have slightly better binding performance.
+* Using ambiguous named parameters, such as `$k` and `@k`, in the same prepared
+  statement will result in an exception as it cannot be determined how to bind
+  a bare name.
+
+### `statement.setReadBigInts(enabled)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `enabled` {boolean} Enables or disables the use of `BigInt`s when reading
+  `INTEGER` fields from the database.
+
+When reading from the database, SQLite `INTEGER`s are mapped to JavaScript
+numbers by default. However, SQLite `INTEGER`s can store values larger than
+JavaScript numbers are capable of representing. In such cases, this method can
+be used to read `INTEGER` data using JavaScript `BigInt`s. This method has no
+impact on database write operations where numbers and `BigInt`s are both
+supported at all times.
+
+### `statement.sourceSQL()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Returns: {string} The source SQL used to create this prepared statement.
+
+This method returns the source SQL of the prepared statement. This method is a
+wrapper around [`sqlite3_sql()`][].
+
+### Type conversion between JavaScript and SQLite
+
+When Node.js writes to or reads from SQLite it is necessary to convert between
+JavaScript data types and SQLite's [data types][]. Because JavaScript supports
+more data types than SQLite, only a subset of JavaScript types are supported.
+Attempting to write an unsupported data type to SQLite will result in an
+exception.
+
+| SQLite    | JavaScript           |
+| --------- | -------------------- |
+| `NULL`    | `null`               |
+| `INTEGER` | `number` or `BigInt` |
+| `REAL`    | `number`             |
+| `TEXT`    | `string`             |
+| `BLOB`    | `Uint8Array`         |
+
+[SQL injection]: https://en.wikipedia.org/wiki/SQL_injection
+[`sqlite3_changes64()`]: https://www.sqlite.org/c3ref/changes.html
+[`sqlite3_close_v2()`]: https://www.sqlite.org/c3ref/close.html
+[`sqlite3_exec()`]: https://www.sqlite.org/c3ref/exec.html
+[`sqlite3_expanded_sql()`]: https://www.sqlite.org/c3ref/expanded_sql.html
+[`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
+[connection]: https://www.sqlite.org/c3ref/sqlite3.html
+[data types]: https://www.sqlite.org/datatype3.html
+[in memory]: https://www.sqlite.org/inmemorydb.html
+[parameters are bound]: https://www.sqlite.org/c3ref/bind_blob.html
+[prepared statement]: https://www.sqlite.org/c3ref/stmt.html