sqlite

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.

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

Database#

A synchronous SQLite database connection.

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.

new Database(path: string, options?: Options)

Database methods#

database.close()#

Closes the database connection.

Repeated calls are safe and have no additional effect.

database.close(): void;

database.prepare()#

Compiles SQL into a reusable statement.

Parameters

• sql — SQL statement to prepare.

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.

database.exec(
    sql: string,
    first?: Param,
    ...rest: PrimitiveParam[]
  ): Changes

Example

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.

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.

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.

type Param = Dict<PrimitiveParam> | PrimitiveParam;

PrimitiveParam#

A primitive value accepted by SQLite parameter bindings.

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

Statement#

A reusable prepared SQLite statement.

declare abstract class Statement {}

Statement methods#

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.

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.

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.

statement.run(first?: Param, ...rest: PrimitiveParam[]): Changes;