Skip to content

sqlite,doc: fix StatementSync section #60474

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 31, 2025
Merged

sqlite,doc: fix StatementSync section #60474

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
228 changes: 114 additions & 114 deletions doc/api/sqlite.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -647,120 +647,6 @@ 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.

## Class: `SQLTagStore`

<!-- YAML
added: v24.9.0
-->

This class represents a single LRU (Least Recently Used) cache for storing
prepared statements.

Instances of this class are created via the database.createTagStore() method,
not by using a constructor. The store caches prepared statements based on the
provided SQL query string. When the same query is seen again, the store
retrieves the cached statement and safely applies the new values through
parameter binding, thereby preventing attacks like SQL injection.

The cache has a maxSize that defaults to 1000 statements, but a custom size can
be provided (e.g., database.createTagStore(100)). All APIs exposed by this
class execute synchronously.

### `sqlTagStore.all(sqlTemplate[, ...values])`

<!-- YAML
added: v24.9.0
-->

* `sqlTemplate` {Template Literal} A template literal containing the SQL query.
* `...values` {any} Values to be interpolated into the template literal.
* Returns: {Array} An array of objects representing the rows returned by the query.

Executes the given SQL query and returns all resulting rows as an array of objects.

### `sqlTagStore.get(sqlTemplate[, ...values])`

<!-- YAML
added: v24.9.0
-->

* `sqlTemplate` {Template Literal} A template literal containing the SQL query.
* `...values` {any} Values to be interpolated into the template literal.
* Returns: {Object | undefined} An object representing the first row returned by
the query, or `undefined` if no rows are returned.

Executes the given SQL query and returns the first resulting row as an object.

### `sqlTagStore.iterate(sqlTemplate[, ...values])`

<!-- YAML
added: v24.9.0
-->

* `sqlTemplate` {Template Literal} A template literal containing the SQL query.
* `...values` {any} Values to be interpolated into the template literal.
* Returns: {Iterator} An iterator that yields objects representing the rows returned by the query.

Executes the given SQL query and returns an iterator over the resulting rows.

### `sqlTagStore.run(sqlTemplate[, ...values])`

<!-- YAML
added: v24.9.0
-->

* `sqlTemplate` {Template Literal} A template literal containing the SQL query.
* `...values` {any} Values to be interpolated into the template literal.
* Returns: {Object} An object containing information about the execution, including `changes` and `lastInsertRowid`.

Executes the given SQL query, which is expected to not return any rows (e.g., INSERT, UPDATE, DELETE).

### `sqlTagStore.size()`

<!-- YAML
added: v24.9.0
-->

* Returns: {integer} The number of prepared statements currently in the cache.

A read-only property that returns the number of prepared statements currently in the cache.

### `sqlTagStore.capacity`

<!-- YAML
added: v24.9.0
-->

* Returns: {integer} The maximum number of prepared statements the cache can hold.

A read-only property that returns the maximum number of prepared statements the cache can hold.

### `sqlTagStore.db`

<!-- YAML
added: v24.9.0
-->

* {DatabaseSync} The `DatabaseSync` instance that created this `SQLTagStore`.

A read-only property that returns the `DatabaseSync` object associated with this `SQLTagStore`.

### `sqlTagStore.reset()`

<!-- YAML
added: v24.9.0
-->

Resets the LRU cache, clearing all stored prepared statements.

### `sqlTagStore.clear()`

<!-- YAML
added: v24.9.0
-->

An alias for `sqlTagStore.reset()`.

### `statement.all([namedParameters][, ...anonymousParameters])`

<!-- YAML
Expand Down Expand Up @@ -991,6 +877,120 @@ added: v22.5.0
The source SQL text of the prepared statement. This property is a
wrapper around [`sqlite3_sql()`][].

## Class: `SQLTagStore`

<!-- YAML
added: v24.9.0
-->

This class represents a single LRU (Least Recently Used) cache for storing
prepared statements.

Instances of this class are created via the database.createTagStore() method,
not by using a constructor. The store caches prepared statements based on the
provided SQL query string. When the same query is seen again, the store
retrieves the cached statement and safely applies the new values through
parameter binding, thereby preventing attacks like SQL injection.

The cache has a maxSize that defaults to 1000 statements, but a custom size can
be provided (e.g., database.createTagStore(100)). All APIs exposed by this
class execute synchronously.

### `sqlTagStore.all(sqlTemplate[, ...values])`

<!-- YAML
added: v24.9.0
-->

* `sqlTemplate` {Template Literal} A template literal containing the SQL query.
* `...values` {any} Values to be interpolated into the template literal.
* Returns: {Array} An array of objects representing the rows returned by the query.

Executes the given SQL query and returns all resulting rows as an array of objects.

### `sqlTagStore.get(sqlTemplate[, ...values])`

<!-- YAML
added: v24.9.0
-->

* `sqlTemplate` {Template Literal} A template literal containing the SQL query.
* `...values` {any} Values to be interpolated into the template literal.
* Returns: {Object | undefined} An object representing the first row returned by
the query, or `undefined` if no rows are returned.

Executes the given SQL query and returns the first resulting row as an object.

### `sqlTagStore.iterate(sqlTemplate[, ...values])`

<!-- YAML
added: v24.9.0
-->

* `sqlTemplate` {Template Literal} A template literal containing the SQL query.
* `...values` {any} Values to be interpolated into the template literal.
* Returns: {Iterator} An iterator that yields objects representing the rows returned by the query.

Executes the given SQL query and returns an iterator over the resulting rows.

### `sqlTagStore.run(sqlTemplate[, ...values])`

<!-- YAML
added: v24.9.0
-->

* `sqlTemplate` {Template Literal} A template literal containing the SQL query.
* `...values` {any} Values to be interpolated into the template literal.
* Returns: {Object} An object containing information about the execution, including `changes` and `lastInsertRowid`.

Executes the given SQL query, which is expected to not return any rows (e.g., INSERT, UPDATE, DELETE).

### `sqlTagStore.size()`

<!-- YAML
added: v24.9.0
-->

* Returns: {integer} The number of prepared statements currently in the cache.

A read-only property that returns the number of prepared statements currently in the cache.

### `sqlTagStore.capacity`

<!-- YAML
added: v24.9.0
-->

* Returns: {integer} The maximum number of prepared statements the cache can hold.

A read-only property that returns the maximum number of prepared statements the cache can hold.

### `sqlTagStore.db`

<!-- YAML
added: v24.9.0
-->

* {DatabaseSync} The `DatabaseSync` instance that created this `SQLTagStore`.

A read-only property that returns the `DatabaseSync` object associated with this `SQLTagStore`.

### `sqlTagStore.reset()`

<!-- YAML
added: v24.9.0
-->

Resets the LRU cache, clearing all stored prepared statements.

### `sqlTagStore.clear()`

<!-- YAML
added: v24.9.0
-->

An alias for `sqlTagStore.reset()`.

### Type conversion between JavaScript and SQLite

When Node.js writes to or reads from SQLite it is necessary to convert between
Expand Down
Loading