Class CapacitorSqliteAdapter

Adapter using @capacitor-community/sqlite for native mobile targets.

It opens its database through the plugin's SQLiteConnection, one for every adapter in the page, and close() closes the plugin's connection too, so the database can be opened again. One adapter at a time holds a database: a second open() of the same database fails while the first adapter has it, and so does an open() of a database whose connection the plugin holds for anything else; the adapter closes no connection it did not open. The plugin drops a trailing ".db" from a name, so notes.db and notes are one database.

Transactions use the plugin's beginTransaction, commitTransaction and rollbackTransaction (plugin 5.0.7 and later). The plugin runs every other execute and run call in a transaction of its own, which cannot nest in an open one, so the statements of a transaction's callback go to the plugin with transaction false. A PRAGMA statement goes through the plugin's query(), outside that transaction of the plugin's own: in a run() call, or at the start or the end of an exec() script.

The plugin turns foreign keys on when it opens a database, on Android, iOS and Electron. foreignKeys: false in the open options turns them off.

Implements

Constructors

constructor

Properties

kind capabilities

Methods

open run get all exec transaction close

Constructors

constructor

Properties

Readonlykind

kind: "capacitor-sqlite" = 'capacitor-sqlite'

Identifier for logging/diagnostics (e.g., 'better-sqlite3', 'postgres').

Readonlycapabilities

capabilities: ReadonlySet<StorageCapability> = ...

Capability flags indicating supported features.

Methods

open

run

  • run(statement, parameters?): Promise<StorageRunResult>

  • Executes a mutation statement (INSERT, UPDATE, DELETE).

    Parameters

    • statement: string

      SQL statement to execute

    • Optionalparameters: StorageParameters

      Optional parameters for the statement

    Returns Promise<StorageRunResult>

    Metadata about affected rows

    Throws

    If statement execution fails

    Example

    const result = await adapter.run('INSERT INTO users (name) VALUES (?)', ['John']);
    console.log(`Inserted with ID: ${result.lastInsertRowid}`);

get

  • get<T>(statement, parameters?): Promise<null | T>

  • Retrieves a single row (or null if none found).

    Type Parameters

    • T

    Parameters

    • statement: string

      SQL SELECT statement

    • Optionalparameters: StorageParameters

      Optional parameters for the statement

    Returns Promise<null | T>

    First row or null if no results

    Throws

    If query execution fails

    Example

    const user = await adapter.get<User>('SELECT * FROM users WHERE id = ?', [123]);

all

  • all<T>(statement, parameters?): Promise<T[]>

  • Retrieves all rows returned by the statement.

    WARNING: For large result sets, this loads everything into memory. Consider using streaming (if supported) for large queries.

    Type Parameters

    • T

    Parameters

    • statement: string

      SQL SELECT statement

    • Optionalparameters: StorageParameters

      Optional parameters for the statement

    Returns Promise<T[]>

    Array of all matching rows (empty array if none)

    Throws

    If query execution fails

    Example

    const users = await adapter.all<User>('SELECT * FROM users WHERE age > ?', [18]);

exec

  • exec(script): Promise<void>

  • Executes a script containing multiple SQL statements.

    Statements are typically delimited by semicolons. This is useful for running migrations or initialization scripts. No results are returned.

    Parameters

    • script: string

      SQL script with multiple statements

    Returns Promise<void>

    Throws

    If any statement in the script fails

    Example

    await adapter.exec(`
      CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT);
      CREATE INDEX idx_users_name ON users(name);
    `);

transaction

  • transaction<T>(fn): Promise<T>

  • Executes a callback within a database transaction.

    Callbacks run one at a time, since every transaction shares the one connection. The callback's statements go through the handle it receives; a statement issued through the adapter itself while the callback runs waits until the transaction ends, so a callback must not await one.

    Type Parameters

    • T

    Parameters

    Returns Promise<T>

close

  • close(): Promise<void>

  • Closes the database and the plugin's connection to it, so the database can be opened again, by this adapter or another one. A call made while a close is running waits for that close, so a caller that awaited either call can open the database again at once.

    Returns Promise<void>

Settings

Member Visibility

On This Page

Constructors
Properties
Methods