diff --git a/doc/api/sqlite.md b/doc/api/sqlite.md index f07f27e1428..85e96f1f3eb 100644 --- a/doc/api/sqlite.md +++ b/doc/api/sqlite.md @@ -91,13 +91,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, @@ -819,6 +825,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 @@ -847,6 +854,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 @@ -972,11 +980,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])` * `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. @@ -1261,11 +1348,18 @@ called directly. * `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. @@ -1279,11 +1373,18 @@ called directly. * `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. @@ -1296,11 +1397,18 @@ called directly. * `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`. @@ -1666,6 +1774,7 @@ callback function to indicate what type of operation is being authorized. +[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 @@ -1714,6 +1823,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