@capawesome/capacitor-libsql

Capacitor plugin for libSQL databases.[^1]

Compatibility

| Plugin Version | Capacitor Version | Status | | -------------- | ----------------- | -------------- | | 0.2.x | >=8.x.x | Active support | | 0.1.x | 7.x.x | Deprecated |

Installation

npm install @capawesome/capacitor-libsql
npx cap sync

Android

Variables

If needed, you can define the following project variable in your app's variables.gradle file to change the default version of the dependency:

• $libsqlVersion version of tech.turso.libsql:libsql (default: 0.1.2)

This can be useful if you encounter dependency conflicts with other plugins in your project.

Usage

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

const connectToLocalDatabase = async () => {
  const { connectionId } = await Libsql.connect({
    path: 'database.db',
  });
  console.log('Connected to database with ID:', connectionId);
};

const connectToRemoteDatabase = async () => {
  const { connectionId } = await Libsql.connect({
    url: 'libsql://your-database-url.turso.io',
    authToken: 'your-auth-token',
  });
  console.log('Connected to remote 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.

Available on iOS and Android.

| 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 values to bind to the SQL statements. | 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.