Capacitor libSQL Plugin¶

Capacitor plugin for libSQL databases.¹

Deliver Live Updates to your Capacitor app with Capawesome Cloud

Use Cases¶

The libSQL plugin is typically used whenever an app needs a SQL database, for example:

Offline-first apps: Store data in a local database file on the device and synchronize it with a remote server using the sync(...) method.
Remote databases: Connect directly to a remote libSQL database, such as one hosted on Turso, using a URL and authentication token.
Structured local storage: Create tables and insert, update, delete, and query data with SQL statements and bound values.
Atomic operations: Group multiple statements into a transaction that can be committed or rolled back as a whole.

Compatibility¶

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

Installation¶

You can use our AI-Assisted Setup to install the plugin. Add the Capawesome Skills to your AI tool using the following command:

npx skills add capawesome-team/skills --skill capacitor-plugins

Then use the following prompt:

 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-libsql` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

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¶

The following examples show how to connect to local and remote databases, query data, execute insert, update, and delete statements, run statements inside a transaction, and synchronize with a remote server.

Connect to a local database¶

Connect to a local database file on the device. If no file exists at the specified path, a new file is created. If neither a path nor a URL is provided, the plugin creates a new in-memory database. This method must be called before any other methods that interact with the database:

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);
};

Connect to a remote database¶

Connect to a remote libSQL database using its URL and an authentication token:

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

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);
};

Query data¶

Execute a SELECT statement and retrieve the result set:

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

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

Insert, update, and delete data¶

Execute any SQL statement, including INSERT, UPDATE, DELETE, and CREATE TABLE, optionally with bound values:

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

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');
};

Run multiple statements in a transaction¶

Begin a transaction, execute statements as part of it, and either commit or roll back all changes. Transactions are only available on Android:

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

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);
  }
};

Synchronize with a remote server¶

Synchronize the database with the remote server:

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

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

API¶

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

FAQ¶

Can I use this plugin with Turso?¶

Yes, you can connect to a remote libSQL database hosted on Turso by passing the database URL and an authentication token to the connect(...) method, as shown in the usage example above.

Do I need a remote database to use this plugin?¶

No, the plugin also works with purely local databases. If you pass a path to the connect(...) method, the plugin uses a database file on the device and creates it if it does not exist. If you provide neither a path nor a URL, the plugin creates a new in-memory database.

Are transactions supported?¶

Yes, you can use the beginTransaction(...), commitTransaction(...) and rollbackTransaction(...) methods to group multiple statements into a transaction. Note that transactions are only available on Android.

What is the difference between the `query` and `execute` methods?¶

The query(...) method is used to execute SELECT statements and retrieve the result set. The execute(...) method is used for any other SQL statement, including INSERT, UPDATE, DELETE, and CREATE TABLE, and does not return a result set. Both methods support binding values to the statement.

How do I keep a local database in sync with a remote server?¶

Call the sync(...) method with the ID of the connection you want to synchronize. This synchronizes the database with the remote server and is available on Android and iOS.

Can I use this plugin with Ionic, React, Vue or Angular?¶

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

SQLite: Access SQLite databases with support for encryption, transactions, and schema migrations.
Secure Preferences: Securely store key/value pairs such as passwords or tokens.

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our Capawesome Newsletter.

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

Capacitor libSQL Plugin¶

Use Cases¶

Compatibility¶

Installation¶

Android¶

Variables¶

Usage¶

Connect to a local database¶

Connect to a remote database¶

Query data¶

Insert, update, and delete data¶

Run multiple statements in a transaction¶

Synchronize with a remote server¶

API¶

beginTransaction(...)¶

commitTransaction(...)¶

connect(...)¶

execute(...)¶

executeBatch(...)¶

query(...)¶

rollbackTransaction(...)¶

sync(...)¶

Interfaces¶

BeginTransactionResult¶

BeginTransactionOptions¶

CommitTransactionOptions¶

ConnectResult¶

ConnectOptions¶

ExecuteOptions¶

ExecuteBatchOptions¶

QueryResult¶

QueryOptions¶

RollbackTransactionOptions¶

SyncOptions¶

Type Aliases¶

Value¶

FAQ¶

Can I use this plugin with Turso?¶

Do I need a remote database to use this plugin?¶

Are transactions supported?¶

What is the difference between the query and execute methods?¶

How do I keep a local database in sync with a remote server?¶

Can I use this plugin with Ionic, React, Vue or Angular?¶

Related Plugins¶

Newsletter¶

What is the difference between the `query` and `execute` methods?¶