doc: document sqlite parameter binding

Signed-off-by: Guilherme Araújo <arauujogui@gmail.com>
PR-URL: #65089
Refs: #62001
Refs: #62061
Reviewed-By: Aviv Keller <me@aviv.sh>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>

Author: araujogui

doc/api/sqlite.md

@@ -97,13 +97,19 @@ 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.
 
-| Storage class | JavaScript to SQLite       | SQLite to JavaScript                  |
-| ------------- | -------------------------- | ------------------------------------- |
-| `NULL`        | {null}                     | {null}                                |
-| `INTEGER`     | {number} or {bigint}       | {number} or {bigint} _(configurable)_ |
-| `REAL`        | {number}                   | {number}                              |
-| `TEXT`        | {string}                   | {string}                              |
-| `BLOB`        | {TypedArray} or {DataView} | {Uint8Array}                          |
+| Storage class | JavaScript to SQLite                                            | SQLite to JavaScript                  |
+| ------------- | --------------------------------------------------------------- | ------------------------------------- |
+| `NULL`        | {null}                                                          | {null}                                |
+| `INTEGER`     | {number}, {bigint}, or {boolean}                                | {number} or {bigint} _(configurable)_ |
+| `REAL`        | {number}                                                        | {number}                              |
+| `TEXT`        | {string}                                                        | {string}                              |
+| `BLOB`        | {TypedArray}, {DataView}, {ArrayBuffer}, or {SharedArrayBuffer} | {Uint8Array}                          |
+
+Booleans are written as the `INTEGER` values `1` and `0`. Like any other
+`INTEGER` value, they are read back as {number} by default, or as {bigint}
+values (`1n` and `0n`) when reading BigInts is enabled. Writing a {bigint} that
+does not fit in a signed 64-bit integer throws an `ERR_INVALID_ARG_VALUE`
+error.
 
 APIs that read values from SQLite have a configuration option that determines
 whether `INTEGER` values are converted to `number` or `bigint` in JavaScript,
@@ -832,6 +838,7 @@ added:
 -->
 
 * `changeset` {Uint8Array} A binary changeset or patchset.
+
 * `options` {Object} The configuration options for how the changes will be applied.
   * `filter` {Function} for each table affected by at least
     one change in the changeset, the `filter` callback is invoked with the
@@ -860,6 +867,7 @@ added:
     applying the changeset is aborted and the database is rolled back.
 
     **Default**: A function that returns `SQLITE_CHANGESET_ABORT`.
+
 * Returns: {boolean} Whether the changeset was applied successfully without being aborted.
 
 An exception is thrown if the database is not
@@ -985,11 +993,61 @@ 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.
 
+### Binding parameters
+
+The `all()`, `get()`, `iterate()`, and `run()` methods bind their arguments to
+the parameters of the prepared statement before executing it. Parameters are
+either anonymous or named.
+
+Anonymous parameters are written as `?` in SQL and are bound in order from the
+arguments passed to the method. The `?NNN` form assigns SQLite parameter index
+`NNN` to a placeholder. Avoid mixing numbered and named parameters because they
+share parameter indexes.
+
+```js
+db.prepare('SELECT ? AS a, ? AS b').get('x', 42);
+// { a: 'x', b: 42 }
+db.prepare('SELECT ?2 AS a, ?1 AS b').get('first', 'second');
+// { a: 'second', b: 'first' }
+```
+
+Named parameters begin with one of the prefix characters `$`, `:`, or `@` in
+SQL. They are bound from an object passed as the first argument. Repeating a
+name in the SQL binds the same value to every occurrence.
+
+```js
+db.prepare('SELECT $a AS a, $b AS b').get({ $a: 1, $b: 2 });
+// { a: 1, b: 2 }
+db.prepare('SELECT :a AS a').get({ ':a': 1 });
+// { a: 1 }
+db.prepare('SELECT @a AS a').get({ '@a': 1 });
+// { a: 1 }
+db.prepare('SELECT $k AS a, $k AS b').get({ k: 7 });
+// { a: 7, b: 7 }
+```
+
+The last example omits the prefix character from the object key. Bare names are
+allowed by default; see [`statement.setAllowBareNamedParameters()`][] for their
+caveats.
+
+Binding a key that does not name a parameter of the statement throws an
+`ERR_INVALID_STATE` error unless unknown named parameters are ignored. See
+[`statement.setAllowUnknownNamedParameters()`][].
+
+See [Type conversion between JavaScript and SQLite][] for the values that can be
+bound. Binding any other value throws an `ERR_INVALID_ARG_TYPE` error.
+
 ### `statement.all([namedParameters][, ...anonymousParameters])`
 
 <!-- YAML
 added: v22.5.0
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/62001
+    description: Add support for boolean values in bound parameters.
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/62061
+    description: Add support for `ArrayBuffer` and `SharedArrayBuffer` objects in bound parameters.
   - version:
     - v23.7.0
     - v22.14.0
@@ -999,16 +1057,17 @@ changes:
 
 * `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|TypedArray|DataView} Zero or
-  more values to bind to anonymous parameters.
+* `...anonymousParameters` {null|number|bigint|boolean|string|Buffer|TypedArray|DataView|ArrayBuffer|SharedArrayBuffer}
+  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`.
+the values in `namedParameters` and `anonymousParameters`. See
+[Binding parameters][].
 
 ### `statement.close()`
 
@@ -1029,7 +1088,6 @@ added:
 
 * Returns: {Array} An array of objects. Each object corresponds to a column
   in the prepared statement, and contains the following properties:
-
   * `column` {string|null} The unaliased name of the column in the origin
     table, or `null` if the column is the result of an expression or subquery.
     This property is the result of [`sqlite3_column_origin_name()`][].
@@ -1067,6 +1125,12 @@ execution of this prepared statement. This property is a wrapper around
 <!-- YAML
 added: v22.5.0
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/62001
+    description: Add support for boolean values in bound parameters.
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/62061
+    description: Add support for `ArrayBuffer` and `SharedArrayBuffer` objects in bound parameters.
   - version:
     - v23.7.0
     - v22.14.0
@@ -1076,8 +1140,8 @@ changes:
 
 * `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|TypedArray|DataView} Zero or
-  more values to bind to anonymous parameters.
+* `...anonymousParameters` {null|number|bigint|boolean|string|Buffer|TypedArray|DataView|ArrayBuffer|SharedArrayBuffer}
+  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
@@ -1086,7 +1150,8 @@ changes:
 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`.
+values in `namedParameters` and `anonymousParameters`. See
+[Binding parameters][].
 
 ### `statement.iterate([namedParameters][, ...anonymousParameters])`
 
@@ -1095,6 +1160,12 @@ added:
   - v23.4.0
   - v22.13.0
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/62001
+    description: Add support for boolean values in bound parameters.
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/62061
+    description: Add support for `ArrayBuffer` and `SharedArrayBuffer` objects in bound parameters.
   - version:
     - v23.7.0
     - v22.14.0
@@ -1104,22 +1175,29 @@ changes:
 
 * `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|TypedArray|DataView} Zero or
-  more values to bind to anonymous parameters.
+* `...anonymousParameters` {null|number|bigint|boolean|string|Buffer|TypedArray|DataView|ArrayBuffer|SharedArrayBuffer}
+  Zero or more values to bind to anonymous parameters.
 * Returns: {Iterator} An iterable iterator 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 an iterator of
 objects. If the prepared statement does not return any results, this method
 returns an empty iterator. The prepared statement [parameters are bound][] using
-the values in `namedParameters` and `anonymousParameters`.
+the values in `namedParameters` and `anonymousParameters`. See
+[Binding parameters][].
 
 ### `statement.run([namedParameters][, ...anonymousParameters])`
 
 <!-- YAML
 added: v22.5.0
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/62001
+    description: Add support for boolean values in bound parameters.
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/62061
+    description: Add support for `ArrayBuffer` and `SharedArrayBuffer` objects in bound parameters.
   - version:
     - v23.7.0
     - v22.14.0
@@ -1129,8 +1207,8 @@ changes:
 
 * `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|TypedArray|DataView} Zero or
-  more values to bind to anonymous parameters.
+* `...anonymousParameters` {null|number|bigint|boolean|string|Buffer|TypedArray|DataView|ArrayBuffer|SharedArrayBuffer}
+  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.
@@ -1144,7 +1222,8 @@ changes:
 
 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`.
+values in `namedParameters` and `anonymousParameters`. See
+[Binding parameters][].
 
 ### `statement.setAllowBareNamedParameters(enabled)`
 
@@ -1155,14 +1234,15 @@ added: v22.5.0
 * `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` allows binding named parameters without this prefix character in
-the parameter object. With the exception of the dollar sign character, these
-prefix characters require extra quoting when used in object keys.
+The names of SQLite parameters begin with a prefix character. However, with the
+exception of the dollar sign character, these prefix characters also require
+extra quoting when used in object keys.
 
-This method enables or disables support for bare named parameters, which do not
-require the prefix character in JavaScript code. There are several caveats to
-be aware of when bare named parameters are enabled:
+To improve ergonomics, `node:sqlite` allows bare named parameters, which do not
+require the prefix character in JavaScript code, by default. This method can be
+used to disable that behavior, requiring the prefix character when binding.
+There are several caveats to be aware of when bare named parameters are
+allowed:
 
 * The prefix character is still required in SQL.
 * The prefix character is still allowed in JavaScript. In fact, prefixed names
@@ -1256,11 +1336,18 @@ class execute synchronously.
 
 <!-- YAML
 added: v24.9.0
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/62001
+    description: Add support for boolean values in bound parameters.
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/62061
+    description: Add support for `ArrayBuffer` and `SharedArrayBuffer` objects in bound parameters.
 -->
 
 * `stringElements` {string\[]} Template literal elements containing the SQL
   query.
-* `...boundParameters` {null|number|bigint|string|Buffer|TypedArray|DataView}
+* `...boundParameters` {null|number|bigint|boolean|string|Buffer|TypedArray|DataView|ArrayBuffer|SharedArrayBuffer}
   Parameter values to be bound to placeholders in the template string.
 * Returns: {Array} An array of objects representing the rows returned by the query.
 
@@ -1274,11 +1361,18 @@ called directly.
 
 <!-- YAML
 added: v24.9.0
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/62001
+    description: Add support for boolean values in bound parameters.
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/62061
+    description: Add support for `ArrayBuffer` and `SharedArrayBuffer` objects in bound parameters.
 -->
 
 * `stringElements` {string\[]} Template literal elements containing the SQL
   query.
-* `...boundParameters` {null|number|bigint|string|Buffer|TypedArray|DataView}
+* `...boundParameters` {null|number|bigint|boolean|string|Buffer|TypedArray|DataView|ArrayBuffer|SharedArrayBuffer}
   Parameter values to be bound to placeholders in the template string.
 * Returns: {Object | undefined} An object representing the first row returned by
   the query, or `undefined` if no rows are returned.
@@ -1292,11 +1386,18 @@ called directly.
 
 <!-- YAML
 added: v24.9.0
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/62001
+    description: Add support for boolean values in bound parameters.
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/62061
+    description: Add support for `ArrayBuffer` and `SharedArrayBuffer` objects in bound parameters.
 -->
 
 * `stringElements` {string\[]} Template literal elements containing the SQL
   query.
-* `...boundParameters` {null|number|bigint|string|Buffer|TypedArray|DataView}
+* `...boundParameters` {null|number|bigint|boolean|string|Buffer|TypedArray|DataView|ArrayBuffer|SharedArrayBuffer}
   Parameter values to be bound to placeholders in the template string.
 * Returns: {Iterator} An iterator that yields objects representing the rows returned by the query.
 
@@ -1309,11 +1410,18 @@ called directly.
 
 <!-- YAML
 added: v24.9.0
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/62001
+    description: Add support for boolean values in bound parameters.
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/62061
+    description: Add support for `ArrayBuffer` and `SharedArrayBuffer` objects in bound parameters.
 -->
 
 * `stringElements` {string\[]} Template literal elements containing the SQL
   query.
-* `...boundParameters` {null|number|bigint|string|Buffer|TypedArray|DataView}
+* `...boundParameters` {null|number|bigint|boolean|string|Buffer|TypedArray|DataView|ArrayBuffer|SharedArrayBuffer}
   Parameter values to be bound to placeholders in the template string.
 * Returns: {Object} An object containing information about the execution, including `changes` and `lastInsertRowid`.
 
@@ -1679,6 +1787,7 @@ callback function to indicate what type of operation is being authorized.
   </tr>
 </table>
 
+[Binding parameters]: #binding-parameters
 [Changesets and Patchsets]: https://www.sqlite.org/sessionintro.html#changesets_and_patchsets
 [Constants Passed To The Conflict Handler]: https://www.sqlite.org/session/c_changeset_conflict.html
 [Constants Returned From The Conflict Handler]: https://www.sqlite.org/session/c_changeset_abort.html
@@ -1727,6 +1836,8 @@ callback function to indicate what type of operation is being authorized.
 [`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
+[`statement.setAllowBareNamedParameters()`]: #statementsetallowbarenamedparametersenabled
+[`statement.setAllowUnknownNamedParameters()`]: #statementsetallowunknownnamedparametersenabled
 [busy timeout]: https://sqlite.org/c3ref/busy_timeout.html
 [connection]: https://www.sqlite.org/c3ref/sqlite3.html
 [data types]: https://www.sqlite.org/datatype3.html