Browse API

API · v0.20.0 · changelog

sqlite

Standard library SQLite client

Runtime support

  • Node
  • Deno
  • Bun
  • Browser

Browser: Imports safely, but constructing a database throws.

Member signatures use schematic object.member(...) API notation. Exported type declarations are valid TypeScript.

Synchronous SQLite access across Node, Deno, and Bun.

Node and Deno use node:sqlite; Bun uses bun:sqlite. Browser bundles can import the package, but constructing Database throws because no portable browser SQLite implementation is provided.

ts
import Database from "@rcompat/sqlite";
import type {
  Changes, Options, Param, PrimitiveParam, Statement,
} from "@rcompat/sqlite";

Database#

A synchronous SQLite database connection.

ts
declare class Database {}

Constructor#

new Database()#

Opens a file-backed or in-memory SQLite database.

Parameters

  • path — Database path or :memory:.
  • options — Read-only and safe-integer options.
ts
new Database(path: string, options?: Options)

Database methods#

database.close()#

Closes the database connection.

Repeated calls are safe and have no additional effect.

ts
database.close(): void;

database.prepare()#

Compiles SQL into a reusable statement.

Parameters

  • sql — SQL statement to prepare.
ts
database.prepare(sql: string): Statement;

database.exec()#

Executes SQL once and returns its change metadata.

Parameters may be supplied as positional primitive values or as one named parameter dictionary. Named keys retain their $, @, or : prefix.

Parameters

  • sql — SQL statement to execute.
  • first — First positional value or the named parameter dictionary.
  • rest — Remaining positional values.
ts
database.exec(
    sql: string,
    first?: Param,
    ...rest: PrimitiveParam[]
  ): Changes

Example

ts
const database = new Database(":memory:");
database.exec("CREATE TABLE users (name TEXT)");
database.exec("INSERT INTO users VALUES (?)", "Ada");
const row = database.prepare("SELECT name FROM users").get();
// row is { name: "Ada" }

Types#

Changes#

Metadata returned after executing a statement.

ts
interface Changes {
  // Number of rows changed by the statement.
  changes: bigint | number;
  // Row ID of the most recent insertion.
  lastInsertRowid: bigint | number;
}

Options#

Options used when opening a database.

ts
type Options = {
  // Opens the database without write access.
  // Default: `false`
  readonly?: boolean;
  // Returns SQLite integers as `bigint`.
  // Default: `false`
  safeIntegers?: boolean;
};

Param#

A positional value or dictionary of named parameter values.

ts
type Param = Dict<PrimitiveParam> | PrimitiveParam;

PrimitiveParam#

A primitive value accepted by SQLite parameter bindings.

ts
type PrimitiveParam =
  | bigint
  | null
  | number
  | string
  | Uint8Array;

Statement#

A reusable prepared SQLite statement.

ts
declare abstract class Statement {}

Statement methods#

statement.close()#

Releases this prepared statement.

Repeated calls are safe and have no additional effect. get(), all(), and run() throw after the statement is closed.

ts
statement.close(): void;

statement.get()#

Returns the first matching row or null when no row matches.

Type parameters

  • T — Expected row shape.

Parameters

  • first — First positional value or the named parameter dictionary.
  • rest — Remaining positional values.
ts
statement.get<T = unknown>(
    first?: Param,
    ...rest: PrimitiveParam[]
  ): T | null;

statement.all()#

Returns all matching rows.

Type parameters

  • T — Expected row shape.

Parameters

  • first — First positional value or the named parameter dictionary.
  • rest — Remaining positional values.
ts
statement.all<T = unknown>(first?: Param, ...rest: PrimitiveParam[]): T[];

statement.run()#

Executes the statement and returns its change metadata.

Parameters

  • first — First positional value or the named parameter dictionary.
  • rest — Remaining positional values.
ts
statement.run(first?: Param, ...rest: PrimitiveParam[]): Changes;