@capawesome/capacitor-libsql

Capacitor plugin for libSQL databases.¹

Installation

npm install @capawesome/capacitor-libsql
npx cap sync

Usage

import { Libsql } from '@capawesome/capacitor-libsql';

const connect = async () => {
  const { connectionId } = await Libsql.connect({
    database: 'my-database',
    user: 'my-user',
    password: 'my-password',
  });
  console.log('Connected to database with ID:', connectionId);
};

const query = async () => {
  const result = await Libsql.query({
    connectionId: 'my-connection-id',
    statement: 'SELECT * FROM my_table',
  });
  console.log('Query result:', result.rows);
};

const execute = async () => {
  await Libsql.execute({
    connectionId: 'my-connection-id',
    statement: 'INSERT INTO my_table (column1, column2) VALUES (?, ?)',
    values: ['value1', 'value2'],
  });
  console.log('Insert executed successfully');
};

const performTransaction = async () => {
  const { transactionId } = await Libsql.beginTransaction({
    connectionId: 'my-connection-id',
  });
  try {
    await Libsql.execute({
      connectionId: 'my-connection-id',
      statement: 'UPDATE my_table SET column1 = ? WHERE column2 = ?',
      values: ['new_value', 'value2'],
      transactionId,
    });
    await Libsql.commitTransaction({
      connectionId: 'my-connection-id',
      transactionId,
    });
    console.log('Transaction committed successfully');
  } catch (error) {
    await Libsql.rollbackTransaction({
      connectionId: 'my-connection-id',
      transactionId,
    });
    console.error('Transaction rolled back due to error:', error);
  }
};

const sync = async () => {
  await Libsql.sync({
    connectionId: 'my-connection-id',
  });
  console.log('Database synchronized successfully');
};

API

• beginTransaction(...)
• commitTransaction(...)
• connect(...)
• execute(...)
• executeBatch(...)
• query(...)
• rollbackTransaction(...)
• sync(...)
• Interfaces
• Type Aliases

beginTransaction(...)

beginTransaction(options: BeginTransactionOptions) => Promise<BeginTransactionResult>

Begin a transaction on the specified database connection.

Only available on Android.

Param	Type
options	BeginTransactionOptions

Returns: Promise<BeginTransactionResult>

Since: 0.0.0

---

commitTransaction(...)

commitTransaction(options: CommitTransactionOptions) => Promise<void>

Commit the current transaction on the specified database connection.

Only available on Android.

Param	Type
options	CommitTransactionOptions

Since: 0.0.0

---

connect(...)

connect(options: ConnectOptions) => Promise<ConnectResult>

Connect to a database.

This method must be called before any other methods that interact with the database.

Param	Type
options	ConnectOptions

Returns: Promise<ConnectResult>

Since: 0.0.0

---

execute(...)

execute(options: ExecuteOptions) => Promise<void>

Execute a single SQL statement on the specified database connection.

This method can be used to execute any SQL statement, including INSERT, UPDATE, DELETE, and CREATE TABLE.

Param	Type
options	ExecuteOptions

Since: 0.0.0

---

executeBatch(...)

executeBatch(options: ExecuteBatchOptions) => Promise<void>

Execute a batch of SQL statements on the specified database connection.

This method can be used to execute multiple SQL statements in a single call.

Param	Type
options	ExecuteBatchOptions

Since: 0.0.0

---

query(...)

query(options: QueryOptions) => Promise<QueryResult>

Query the database and return the result set.

This method can be used to execute SELECT statements and retrieve the result set.

Param	Type
options	QueryOptions

Returns: Promise<QueryResult>

Since: 0.0.0

---

rollbackTransaction(...)

rollbackTransaction(options: RollbackTransactionOptions) => Promise<void>

Rollback the current transaction on the specified database connection.

This method will undo all changes made in the current transaction.

Only available on Android.

Param	Type
options	RollbackTransactionOptions

Since: 0.0.0

---

sync(...)

sync(options: SyncOptions) => Promise<void>

Synchronize the database with the remote server.

Only available on iOS.

Param	Type
options	SyncOptions

Since: 0.0.0

---

Interfaces

BeginTransactionResult

Prop	Type	Description	Since
transactionId	string	The ID of the transaction that was started.	0.0.0

BeginTransactionOptions

Prop	Type	Description	Since
connectionId	string	The ID of the connection to begin the transaction on.	0.0.0

CommitTransactionOptions

Prop	Type	Description	Since
connectionId	string	The ID of the connection to commit the transaction on.	0.0.0
transactionId	string	The ID of the transaction to commit.	0.0.0

ConnectResult

Prop	Type	Description	Since
connectionId	string	The ID of the connection.	0.0.0

ConnectOptions

Prop	Type	Description	Since
authToken	string	The authentication token for the database. This is required for connecting to a remote database. If the database is local (i.e., a file on the device), this can be omitted.	0.0.0
path	string	The path to the database file. If no path or URL is provided, the plugin will create a new in-memory database. If no file exists at the specified path, a new file will be created.	0.0.0
url	string	The URL of the database. This can be used to connect to a remote database. If the URL is provided, the authToken must also be provided. If no path or URL is provided, the plugin will create a new in-memory database.	0.0.0

ExecuteOptions

Prop	Type	Description	Since
connectionId	string	The ID of the connection to execute the SQL statement on.	0.0.0
statement	string	The SQL statement to execute.	0.0.0
transactionId	string	The transaction ID to use for the SQL statement. Only available on Android.	0.0.0
values	Value[]	The values to bind to the SQL statement.	0.0.0

ExecuteBatchOptions

Prop	Type	Description	Since
connectionId	string	The ID of the connection to execute the batch on.	0.0.0
statement	string[]	The SQL statements to execute in the batch.	0.0.0
values	Value[][]	The transaction ID to use for the batch. Only available on Android.	0.0.0

QueryResult

Prop	Type	Description	Since
rows	Value[][]	The values returned by the query.	0.0.0

QueryOptions

Prop	Type	Description	Since
connectionId	string	The ID of the connection to query.	0.0.0
statement	string	The SQL statement to execute.	0.0.0
transactionId	string	The transaction ID to use for the query. Only available on Android.	0.0.0
values	Value[]	The values to bind to the SQL statement.	0.0.0

RollbackTransactionOptions

Prop	Type	Description	Since
connectionId	string	The ID of the connection to rollback the transaction on.	0.0.0
transactionId	string	The ID of the transaction to rollback.	0.0.0

SyncOptions

Prop	Type	Description	Since
connectionId	string	The ID of the connection to sync.	0.0.0

Type Aliases

Value

string | number | null

---

1. This project is not affiliated with, endorsed by, sponsored by, or approved by CHISELSTRIKE INC. or any of their affiliates or subsidiaries. ↩