Home Original page

sqlite,doc: fix StatementSync section · nodejs/node@edc3033

@@ -647,120 +647,6 @@ times with different bound values. Parameters also offer protection against

647647

[SQL injection][] attacks. For these reasons, prepared statements are preferred

648648

over hand-crafted SQL strings when handling user input.

649649650-

## Class: `SQLTagStore`

651-652-

<!-- YAML

653-

added: v24.9.0

654-

-->

655-656-

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

657-

prepared statements.

658-659-

Instances of this class are created via the database.createTagStore() method,

660-

not by using a constructor. The store caches prepared statements based on the

661-

provided SQL query string. When the same query is seen again, the store

662-

retrieves the cached statement and safely applies the new values through

663-

parameter binding, thereby preventing attacks like SQL injection.

664-665-

The cache has a maxSize that defaults to 1000 statements, but a custom size can

666-

be provided (e.g., database.createTagStore(100)). All APIs exposed by this

667-

class execute synchronously.

668-669-

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

670-671-

<!-- YAML

672-

added: v24.9.0

673-

-->

674-675-

* `sqlTemplate` {Template Literal} A template literal containing the SQL query.

676-

* `...values` {any} Values to be interpolated into the template literal.

677-

* Returns: {Array} An array of objects representing the rows returned by the query.

678-679-

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

680-681-

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

682-683-

<!-- YAML

684-

added: v24.9.0

685-

-->

686-687-

* `sqlTemplate` {Template Literal} A template literal containing the SQL query.

688-

* `...values` {any} Values to be interpolated into the template literal.

689-

* Returns: {Object | undefined} An object representing the first row returned by

690-

the query, or `undefined` if no rows are returned.

691-692-

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

693-694-

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

695-696-

<!-- YAML

697-

added: v24.9.0

698-

-->

699-700-

* `sqlTemplate` {Template Literal} A template literal containing the SQL query.

701-

* `...values` {any} Values to be interpolated into the template literal.

702-

* Returns: {Iterator} An iterator that yields objects representing the rows returned by the query.

703-704-

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

705-706-

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

707-708-

<!-- YAML

709-

added: v24.9.0

710-

-->

711-712-

* `sqlTemplate` {Template Literal} A template literal containing the SQL query.

713-

* `...values` {any} Values to be interpolated into the template literal.

714-

* Returns: {Object} An object containing information about the execution, including `changes` and `lastInsertRowid`.

715-716-

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

717-718-

### `sqlTagStore.size()`

719-720-

<!-- YAML

721-

added: v24.9.0

722-

-->

723-724-

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

725-726-

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

727-728-

### `sqlTagStore.capacity`

729-730-

<!-- YAML

731-

added: v24.9.0

732-

-->

733-734-

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

735-736-

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

737-738-

### `sqlTagStore.db`

739-740-

<!-- YAML

741-

added: v24.9.0

742-

-->

743-744-

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

745-746-

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

747-748-

### `sqlTagStore.reset()`

749-750-

<!-- YAML

751-

added: v24.9.0

752-

-->

753-754-

Resets the LRU cache, clearing all stored prepared statements.

755-756-

### `sqlTagStore.clear()`

757-758-

<!-- YAML

759-

added: v24.9.0

760-

-->

761-762-

An alias for `sqlTagStore.reset()`.

763-764650

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

765651766652

<!-- YAML

@@ -991,6 +877,120 @@ added: v22.5.0

991877

The source SQL text of the prepared statement. This property is a

992878

wrapper around [`sqlite3_sql()`][].

993879880+

## Class: `SQLTagStore`

881+882+

<!-- YAML

883+

added: v24.9.0

884+

-->

885+886+

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

887+

prepared statements.

888+889+

Instances of this class are created via the database.createTagStore() method,

890+

not by using a constructor. The store caches prepared statements based on the

891+

provided SQL query string. When the same query is seen again, the store

892+

retrieves the cached statement and safely applies the new values through

893+

parameter binding, thereby preventing attacks like SQL injection.

894+895+

The cache has a maxSize that defaults to 1000 statements, but a custom size can

896+

be provided (e.g., database.createTagStore(100)). All APIs exposed by this

897+

class execute synchronously.

898+899+

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

900+901+

<!-- YAML

902+

added: v24.9.0

903+

-->

904+905+

* `sqlTemplate` {Template Literal} A template literal containing the SQL query.

906+

* `...values` {any} Values to be interpolated into the template literal.

907+

* Returns: {Array} An array of objects representing the rows returned by the query.

908+909+

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

910+911+

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

912+913+

<!-- YAML

914+

added: v24.9.0

915+

-->

916+917+

* `sqlTemplate` {Template Literal} A template literal containing the SQL query.

918+

* `...values` {any} Values to be interpolated into the template literal.

919+

* Returns: {Object | undefined} An object representing the first row returned by

920+

the query, or `undefined` if no rows are returned.

921+922+

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

923+924+

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

925+926+

<!-- YAML

927+

added: v24.9.0

928+

-->

929+930+

* `sqlTemplate` {Template Literal} A template literal containing the SQL query.

931+

* `...values` {any} Values to be interpolated into the template literal.

932+

* Returns: {Iterator} An iterator that yields objects representing the rows returned by the query.

933+934+

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

935+936+

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

937+938+

<!-- YAML

939+

added: v24.9.0

940+

-->

941+942+

* `sqlTemplate` {Template Literal} A template literal containing the SQL query.

943+

* `...values` {any} Values to be interpolated into the template literal.

944+

* Returns: {Object} An object containing information about the execution, including `changes` and `lastInsertRowid`.

945+946+

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

947+948+

### `sqlTagStore.size()`

949+950+

<!-- YAML

951+

added: v24.9.0

952+

-->

953+954+

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

955+956+

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

957+958+

### `sqlTagStore.capacity`

959+960+

<!-- YAML

961+

added: v24.9.0

962+

-->

963+964+

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

965+966+

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

967+968+

### `sqlTagStore.db`

969+970+

<!-- YAML

971+

added: v24.9.0

972+

-->

973+974+

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

975+976+

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

977+978+

### `sqlTagStore.reset()`

979+980+

<!-- YAML

981+

added: v24.9.0

982+

-->

983+984+

Resets the LRU cache, clearing all stored prepared statements.

985+986+

### `sqlTagStore.clear()`

987+988+

<!-- YAML

989+

added: v24.9.0

990+

-->

991+992+

An alias for `sqlTagStore.reset()`.

993+994994

### Type conversion between JavaScript and SQLite

995995996996

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