Skip to main content
Deno 2 is finally here 🎉️
Learn more
Go to Latest
class PreparedQuery
import { PreparedQuery } from "https://deno.land/x/sqlite@v3.8/mod.ts";

A prepared query which can be executed many times.

Constructors

new
PreparedQuery(
wasm: Wasm,
stmt: StatementPtr,
openStatements: Set<StatementPtr>,
)

This constructor should never be used directly. Instead a prepared query can be obtained by calling DB.prepareQuery.

Type Parameters

optional
R extends Row = Row
optional
O extends RowObject = RowObject

Methods

all(params?: P): Array<R>

Binds the given parameters to the query and returns an array containing all resulting rows.

Examples

const query = db.prepareQuery<[number, string]>("SELECT id, name FROM people");
const rows = query.all();
// rows = [[1, "Peter"], ...]

To avoid SQL injection, user-provided values should always be passed to the database through a query parameter.

const query = db.prepareQuery("SELECT id FROM people WHERE name = ?");
query.all([name]);
const query = db.prepareQuery("SELECT id FROM people WHERE name = :name");
query.all({ name });

See QueryParameterSet for documentation on how values can be bound to SQL statements.

See QueryParameter for documentation on how values are returned from the database.

allEntries(params?: P): Array<O>

Like all except each row is returned as an object containing key-value pairs.

Example

const query = db.prepareQuery<[number, string], { id: number, name: string }>("SELECT id, name FROM people");
const rows = query.allEntries();
// rows = [{ id: 1, name: "Peter" }, ...]

Returns the column names for this query.

execute(params?: P)

Binds the given parameters to the query and executes the query, ignoring any rows which might be returned.

Using this method is more efficient when the rows returned by a query are not needed or the query does not return any rows.

Examples

const query = db.prepareQuery<never, never, [string]>("INSERT INTO people (name) VALUES (?)");
query.execute(["Peter"]);
const query = db.prepareQuery<never, never, { name: string }>("INSERT INTO people (name) VALUES (:name)");
query.execute({ name: "Peter" });

See QueryParameterSet for documentation on how values can be bound to SQL statements.

See QueryParameter for documentation on how values are returned from the database.

expandSql(params?: P): string

Returns the SQL string used to construct this query, substituting placeholders (e.g. ?) with their values supplied in params.

Calling this function invalidates any iterators previously returned by calls to iter.

See QueryParameterSet for documentation on how values can be bound to SQL statements.

Closes the prepared query. This must be called once the query is no longer needed to avoid leaking resources.

After a prepared query has been finalized, calls to iter, all, first, execute, or columns will fail.

Using iterators which were previously returned from the finalized query will fail.

finalize may safely be called multiple times.

first(params?: P): R | undefined

Binds the given parameters to the query and returns the first resulting row or undefined when there are no rows returned by the query.

Examples

const query = db.prepareQuery<[number, string]>("SELECT id, name FROM people");
const person = query.first();
// person = [1, "Peter"]
const query = db.prepareQuery("SELECT id, name FROM people WHERE name = ?");
const person = query.first(["not a name"]);
// person = undefined

To avoid SQL injection, user-provided values should always be passed to the database through a query parameter.

const query = db.prepareQuery("SELECT id FROM people WHERE name = ?");
query.first([name]);
const query = db.prepareQuery("SELECT id FROM people WHERE name = :name");
query.first({ name });

See QueryParameterSet for documentation on how values can be bound to SQL statements.

See QueryParameter for documentation on how values are returned from the database.

firstEntry(params?: P): O | undefined

Like first except the row is returned as an object containing key-value pairs.

Example

const query = db.prepareQuery<[number, string], { id: number, name: string }>("SELECT id, name FROM people");
const person = query.firstEntry();
// person = { id: 1, name: "Peter" }
iter(params?: P): RowsIterator<R>

Binds the given parameters to the query and returns an iterator over rows.

Using an iterator avoids loading all returned rows into memory and hence allows to process a large number of rows.

Calling iter, all, or first invalidates any iterators previously returned from this prepared query.

Examples

const query = db.prepareQuery<[number, string]>("SELECT id, name FROM people");
for (const [id, name] of query.iter()) {
  // ...
}

To avoid SQL injection, user-provided values should always be passed to the database through a query parameter.

const query = db.prepareQuery("SELECT id FROM people WHERE name = ?");
query.iter([name]);
const query = db.prepareQuery("SELECT id FROM people WHERE name = :name");
query.iter({ name });

See QueryParameterSet for documentation on how values can be bound to SQL statements.

See QueryParameter for documentation on how values are returned from the database.

iterEntries(params?: P): RowsIterator<O>

Like iter except each row is returned as an object containing key-value pairs.

Example

const query = db.prepareQuery<[number, string], { id: number, name: string }>("SELECT id, name FROM people");
for (const { id, name } of query.iterEntries()) {
  // ...
}
next(): IteratorResult<R | O>
one(params?: P): R

Deprecated: prefer first.

oneEntry(params?: P): O

Deprecated: prefer firstEntry.

[Symbol.iterator](): RowsIterator<R | O>