wa-sqlite
    Preparing search index...

    Interface SQLiteAPI

    Javascript wrappers for the SQLite C API (plus a few convenience functions)

    Function signatures have been slightly modified to be more Javascript-friendly. For the C functions that return an error code, the corresponding Javascript wrapper will throw an exception with a code property on an error.

    Note that a few functions return a Promise in order to accomodate either a synchronous or asynchronous SQLite build, generally those involved with opening/closing a database or executing a statement.

    To create an instance of the API, follow these steps:

    // Import an ES6 module factory function from one of the
    // package builds, either 'wa-sqlite.mjs' (synchronous) or
    // 'wa-sqlite-async.mjs' (asynchronous). You should only
    // use the asynchronous build if you plan to use an
    // asynchronous VFS or module.
    import SQLiteESMFactory from 'wa-sqlite/dist/wa-sqlite.mjs';

    // Import the Javascript API wrappers.
    import * as SQLite from 'wa-sqlite';

    // Use an async function to simplify Promise handling.
    (async function() {
    // Invoke the ES6 module factory to create the SQLite
    // Emscripten module. This will fetch and compile the
    // .wasm file.
    const module = await SQLiteESMFactory();

    // Use the module to build the API instance.
    const sqlite3 = SQLite.Factory(module);

    // Use the API to open and access a database.
    const db = await sqlite3.open_v2('myDB');
    ...
    })();
    interface SQLiteAPI {
        bind(stmt: number, i: number, value: SQLiteCompatibleType): number;
        bind_blob(stmt: number, i: number, value: number[] | Uint8Array): number;
        bind_collection(
            stmt: number,
            bindings:
                | { [index: string]: SQLiteCompatibleType }
                | SQLiteCompatibleType[],
        ): number;
        bind_double(stmt: number, i: number, value: number): number;
        bind_int(stmt: number, i: number, value: number): number;
        bind_int64(stmt: number, i: number, value: bigint): number;
        bind_null(stmt: number, i: number): number;
        bind_parameter_count(stmt: number): number;
        bind_parameter_name(stmt: number, i: number): string;
        bind_text(stmt: number, i: number, value: string): number;
        changes(db: number): number;
        clear_bindings(stmt: number): number;
        close(db: number): Promise<number>;
        column(stmt: number, i: number): SQLiteCompatibleType;
        column_blob(stmt: number, i: number): Uint8Array;
        column_bytes(stmt: number, i: number): number;
        column_count(stmt: number): number;
        column_double(stmt: number, i: number): number;
        column_int(stmt: number, i: number): number;
        column_int64(stmt: number, i: number): bigint;
        column_name(stmt: number, i: number): string;
        column_names(stmt: number): string[];
        column_text(stmt: number, i: number): string;
        column_type(stmt: number, i: number): number;
        commit_hook(db: number, callback: () => number): void;
        create_function(
            db: number,
            zFunctionName: string,
            nArg: number,
            eTextRep: number,
            pApp: number,
            xFunc?: (context: number, values: Uint32Array) => void | Promise<void>,
            xStep?: (context: number, values: Uint32Array) => void | Promise<void>,
            xFinal?: (context: number) => void | Promise<void>,
        ): number;
        data_count(stmt: number): number;
        exec(
            db: number,
            zSQL: string,
            callback?: (row: SQLiteCompatibleType[], columns: string[]) => void,
        ): Promise<number>;
        finalize(stmt: number): Promise<number>;
        get_autocommit(db: number): number;
        libversion(): string;
        libversion_number(): number;
        limit(db: number, id: number, newVal: number): number;
        open_v2(zFilename: string, iFlags?: number, zVfs?: string): Promise<number>;
        progress_handler<T = any>(
            db: number,
            nProgressOps: number,
            handler: (userData: T) => number | Promise<number>,
            userData: T,
        ): void;
        reset(stmt: number): Promise<number>;
        result(context: number, value: SQLiteCompatibleType): void;
        result_blob(context: number, value: number[] | Uint8Array): void;
        result_double(context: number, value: number): void;
        result_int(context: number, value: number): void;
        result_int64(context: number, value: bigint): void;
        result_null(context: number): void;
        result_text(context: number, value: string): void;
        row(stmt: number): SQLiteCompatibleType[];
        set_authorizer(
            db: number,
            authFunction: (
                userData: any,
                iActionCode: number,
                param3: string,
                param4: string,
                param5: string,
                param6: string,
            ) => number | Promise<number>,
            userData: any,
        ): number;
        sql(stmt: number): string;
        statements(
            db: number,
            sql: string,
            options?: SQLitePrepareOptions,
        ): AsyncIterable<number>;
        step(stmt: number): Promise<number>;
        update_hook(
            db: number,
            callback: (
                updateType: number,
                dbName: string,
                tblName: string,
                rowid: bigint,
            ) => void,
        ): void;
        value(pValue: number): SQLiteCompatibleType;
        value_blob(pValue: number): Uint8Array;
        value_bytes(pValue: number): number;
        value_double(pValue: number): number;
        value_int(pValue: number): number;
        value_int64(pValue: number): bigint;
        value_text(pValue: number): string;
        value_type(pValue: number): number;
        vfs_register(vfs: SQLiteVFS, makeDefault?: boolean): number;
    }
    Index
    • Bind value to prepared statement

      This convenience function calls the appropriate bind_* function based on the type of value. Note that binding indices begin with 1.

      Parameters

      Returns number

      SQLITE_OK (throws exception on error)

    • Bind blob to prepared statement parameter

      Note that binding indices begin with 1.

      Parameters

      • stmt: number

        prepared statement pointer

      • i: number

        binding index

      • value: number[] | Uint8Array

      Returns number

      SQLITE_OK (throws exception on error)

    • Bind a collection of values to a statement

      This convenience function binds values from either an array or object to a prepared statement with placeholder parameters.

      Array example using numbered parameters (numbering is implicit in this example):

      const sql = 'INSERT INTO tbl VALUES (?, ?, ?)';
      for await (const stmt of sqlite3.statements(db, sql) {
      sqlite3.bind_collection(stmt, [42, 'hello', null]);
      ...
      }

      Object example using named parameters (':', '@', or '$' prefixes are allowed):

      const sql = 'INSERT INTO tbl VALUES (?, ?, ?)';
      for await (const stmt of sqlite3.statements(db, sql) {
      sqlite3.bind_collection(stmt, {
      '@foo': 42,
      '@bar': 'hello',
      '@baz': null,
      });
      ...
      }

      Note that SQLite bindings are indexed beginning with 1, but when binding values from an array a the values begin with a[0].

      Parameters

      Returns number

      SQLITE_OK (throws exception on error)

    • Bind number to prepared statement parameter

      Note that binding indices begin with 1.

      Parameters

      • stmt: number

        prepared statement pointer

      • i: number

        binding index

      • value: number

      Returns number

      SQLITE_OK (throws exception on error)

    • Bind number to prepared statement parameter

      Note that binding indices begin with 1.

      Parameters

      • stmt: number

        prepared statement pointer

      • i: number

        binding index

      • value: number

      Returns number

      SQLITE_OK (throws exception on error)

    • Bind number to prepared statement parameter

      Note that binding indices begin with 1.

      Parameters

      • stmt: number

        prepared statement pointer

      • i: number

        binding index

      • value: bigint

      Returns number

      SQLITE_OK (throws exception on error)

    • Bind null to prepared statement

      Note that binding indices begin with 1.

      Parameters

      • stmt: number

        prepared statement pointer

      • i: number

        binding index

      Returns number

      SQLITE_OK (throws exception on error)

    • Get name of bound parameter

      Note that binding indices begin with 1.

      Parameters

      • stmt: number

        prepared statement pointer

      • i: number

        binding index

      Returns string

      binding name

    • Bind string to prepared statement

      Note that binding indices begin with 1.

      Parameters

      • stmt: number

        prepared statement pointer

      • i: number

        binding index

      • value: string

      Returns number

      SQLITE_OK (throws exception on error)

    • Close database connection

      Parameters

      • db: number

        database pointer

      Returns Promise<number>

      SQLITE_OK (throws exception on error)

    • Call the appropriate column_* function based on the column type

      The type is determined by calling column_type, which may not match the type declared in CREATE TABLE. Note that if the column value is a blob then as with column_blob the result may be invalid after the next SQLite call; copy if it needs to be retained.

      Integer values are returned as Number if within the min/max safe integer bounds, otherwise they are returned as BigInt.

      Parameters

      • stmt: number

        prepared statement pointer

      • i: number

        column index

      Returns SQLiteCompatibleType

      column value

    • Extract a column value from a row after a prepared statment step

      The contents of the returned buffer may be invalid after the next SQLite call. Make a copy of the data (e.g. with .slice()) if longer retention is required.

      Parameters

      • stmt: number

        prepared statement pointer

      • i: number

        column index

      Returns Uint8Array

      column value

    • Get storage size for column text or blob

      Parameters

      • stmt: number

        prepared statement pointer

      • i: number

        column index

      Returns number

      number of bytes in column text or blob

    • Extract a column value from a row after a prepared statment step

      Parameters

      • stmt: number

        prepared statement pointer

      • i: number

        column index

      Returns number

      column value

    • Extract a column value from a row after a prepared statment step

      Parameters

      • stmt: number

        prepared statement pointer

      • i: number

        column index

      Returns number

      column value

    • Extract a column value from a row after a prepared statment step

      Parameters

      • stmt: number

        prepared statement pointer

      • i: number

        column index

      Returns bigint

      column value

    • Get a column name for a prepared statement

      Parameters

      • stmt: number

        prepared statement pointer

      • i: number

        column index

      Returns string

      column name

    • Get names for all columns of a prepared statement

      This is a convenience function that calls column_count and column_name.

      Parameters

      • stmt: number

      Returns string[]

      array of column names

    • Extract a column value from a row after a prepared statment step

      Parameters

      • stmt: number

        prepared statement pointer

      • i: number

        column index

      Returns string

      column value, or null if the column is SQL NULL

    • Get column type for a prepared statement

      Note that this type may not match the type declared in CREATE TABLE.

      Parameters

      • stmt: number

        prepared statement pointer

      • i: number

        column index

      Returns number

      enumeration value for type

    • Register a commit hook

      Parameters

      • db: number

        database pointer

      • callback: () => number

        If a non-zero value is returned, commit is converted into a rollback; disables callback when null

      Returns void

    • Create or redefine SQL functions

      The application data passed is ignored. Use closures instead.

      If any callback function returns a Promise, that function must be declared async, i.e. it must allow use of await.

      Parameters

      • db: number

        database pointer

      • zFunctionName: string
      • nArg: number

        number of function arguments

      • eTextRep: number

        text encoding (and other flags)

      • pApp: number

        application data (ignored)

      • OptionalxFunc: (context: number, values: Uint32Array) => void | Promise<void>
      • OptionalxStep: (context: number, values: Uint32Array) => void | Promise<void>
      • OptionalxFinal: (context: number) => void | Promise<void>

      Returns number

      SQLITE_OK (throws exception on error)

    • Get number of columns in current row of a prepared statement

      Parameters

      • stmt: number

        prepared statement pointer

      Returns number

      number of columns

    • One-step query execution interface

      The implementation of this function uses row, which makes a copy of blobs and returns BigInt for integers outside the safe integer bounds for Number.

      Parameters

      • db: number

        database pointer

      • zSQL: string

        queries

      • Optionalcallback: (row: SQLiteCompatibleType[], columns: string[]) => void

        called for each output row

      Returns Promise<number>

      Promise resolving to SQLITE_OK (rejects on error)

    • Destroy a prepared statement object compiled by statements with the unscoped option set to true

      This function does not throw on error.

      Parameters

      • stmt: number

        prepared statement pointer

      Returns Promise<number>

      Promise resolving to SQLITE_OK or error status

    • Set a usage limit on a connection.

      Parameters

      • db: number

        database pointer

      • id: number

        limit category

      • newVal: number

      Returns number

      previous setting

    • Opening a new database connection.

      Note that this function differs from the C API in that it returns the Promise-wrapped database pointer (instead of a result code).

      Parameters

      • zFilename: string
      • OptionaliFlags: number

        SQLite.SQLITE_OPEN_CREATE | SQLite.SQLITE_OPEN_READWRITE (0x6) if omitted

      • OptionalzVfs: string

        VFS name

      Returns Promise<number>

      Promise-wrapped database pointer.

    • Specify callback to be invoked between long-running queries

      The application data passed is ignored. Use closures instead.

      If any callback function returns a Promise, that function must be declared async, i.e. it must allow use of await.

      Type Parameters

      • T = any

      Parameters

      • db: number

        database pointer

      • nProgressOps: number

        target number of database operations between handler invocations

      • handler: (userData: T) => number | Promise<number>
      • userData: T

      Returns void

    • Reset a prepared statement object

      Parameters

      • stmt: number

        prepared statement pointer

      Returns Promise<number>

      Promise-wrapped SQLITE_OK (rejects on error)

    • Convenience function to call result_* based of the type of value

      Parameters

      Returns void

    • Set the result of a function or vtable column

      Parameters

      • context: number

        context pointer

      • value: number[] | Uint8Array

      Returns void

    • Set the result of a function or vtable column

      Parameters

      • context: number

        context pointer

      • value: number

      Returns void

    • Set the result of a function or vtable column

      Parameters

      • context: number

        context pointer

      • value: number

      Returns void

    • Set the result of a function or vtable column

      Parameters

      • context: number

        context pointer

      • value: bigint

      Returns void

    • Set the result of a function or vtable column

      Parameters

      • context: number

        context pointer

      • value: string

      Returns void

    • Get all column data for a row from a prepared statement step

      This convenience function will return a copy of any blob, unlike column_blob which returns a value referencing volatile WASM memory with short validity. Like column, it will return a BigInt for integers outside the safe integer bounds for Number.

      Parameters

      • stmt: number

        prepared statement pointer

      Returns SQLiteCompatibleType[]

      row data

    • Register a callback function that is invoked to authorize certain SQL statement actions.

      Parameters

      • db: number

        database pointer

      • authFunction: (
            userData: any,
            iActionCode: number,
            param3: string,
            param4: string,
            param5: string,
            param6: string,
        ) => number | Promise<number>
      • userData: any

      Returns number

    • SQL statement iterator

      This function manages statement compilation by creating an async iterator that yields a prepared statement handle on each iteration. It is typically used with a for await loop (in an async function), like this:

      // Compile one statement on each iteration of this loop.
      for await (const stmt of sqlite3.statements(db, sql)) {
      // Bind parameters here if using SQLite placeholders.

      // Execute the statement with this loop.
      while (await sqlite3.step(stmt) === SQLite.SQLITE_ROW) {
      // Collect row data here.
      }

      // Change bindings, reset, and execute again if desired.
      }

      By default, the lifetime of a yielded prepared statement is managed automatically by the iterator, ending at the end of each iteration. finalize should not be called on a statement provided by the iterator unless the unscoped option is set to true (that option is provided for applications that wish to manage statement lifetimes manually).

      If using the iterator manually, i.e. by calling its next method, be sure to call the return method if iteration is abandoned before completion (for await and other implicit traversals provided by Javascript do this automatically) to ensure that all allocated resources are released.

      Parameters

      Returns AsyncIterable<number>

    • Evaluate an SQL statement

      Parameters

      • stmt: number

        prepared statement pointer

      Returns Promise<number>

      Promise resolving to SQLITE_ROW or SQLITE_DONE (rejects on error)

    • Register an update hook

      The callback is invoked whenever a row is updated, inserted, or deleted in a rowid table on this connection.

      Parameters

      • db: number

        database pointer

      • callback: (updateType: number, dbName: string, tblName: string, rowid: bigint) => void

      Returns void

      updateType is one of:

    • Extract a value from sqlite3_value

      This is a convenience function that calls the appropriate value_* function based on its type. Note that if the value is a blob then as with value_blob the result may be invalid after the next SQLite call.

      Integer values are returned as Number if within the min/max safe integer bounds, otherwise they are returned as BigInt.

      Parameters

      • pValue: number

        sqlite3_value pointer

      Returns SQLiteCompatibleType

      value

    • Extract a value from sqlite3_value

      The contents of the returned buffer may be invalid after the next SQLite call. Make a copy of the data (e.g. with .slice()) if longer retention is required.

      Parameters

      • pValue: number

        sqlite3_value pointer

      Returns Uint8Array

      value

    • Extract a value from sqlite3_value

      Parameters

      • pValue: number

        sqlite3_value pointer

      Returns string

      value, or null if the value is SQL NULL