Reference version

Expo SQLite (Next) iconExpo SQLite (Next)

GitHub

npm

A library that provides access to a database that can be queried through a SQLite API.


This page documents an upcoming version of the SQLite library. To try it, switch to expo-sqlite/next imports in your code.

What are Next (/next) libraries
Next libraries are pre-release versions of SDK libraries. We provide them to get feedback from the community and test new features before their stable release. If you encounter any issue, we encourage reporting on the Expo GitHub repository.

expo-sqlite gives your app access to a database that can be queried through a SQLite API. The database is persisted across restarts of your app.

Platform Compatibility

Android DeviceAndroid EmulatoriOS DeviceiOS SimulatorWeb

Installation

Terminal
npx expo install expo-sqlite

If you are installing this in an existing React Native app (bare workflow), start by installing expo in your project. Then, follow the additional instructions as mentioned by library's README under "Installation in bare React Native projects" section.

Usage

Import the module from expo-sqlite/next.

Import the module from expo-sqlite/next
import * as SQLite from 'expo-sqlite/next';

Basic CRUD operations

Basic CRUD operations
const db = await SQLite.openDatabaseAsync('databaseName');

// `execAsync()` is useful for bulk queries when you want to execute altogether.
// Please note that `execAsync()` does not escape parameters and may lead to SQL injection.
await db.execAsync(`
PRAGMA journal_mode = WAL;
CREATE TABLE IF NOT EXISTS test (id INTEGER PRIMARY KEY NOT NULL, value TEXT NOT NULL, intValue INTEGER);
INSERT INTO test (value, intValue) VALUES ('test1', 123);
INSERT INTO test (value, intValue) VALUES ('test2', 456);
INSERT INTO test (value, intValue) VALUES ('test3', 789);
`);

// `runAsync()` is useful when you want to execute some write operations.
const result = await db.runAsync('INSERT INTO test (value, intValue) VALUES (?, ?)', 'aaa', 100);
console.log(result.lastInsertRowId, result.changes);
await db.runAsync('UPDATE test SET intValue = ? WHERE value = ?', 999, 'aaa'); // Binding unnamed parameters from variadic arguments
await db.runAsync('UPDATE test SET intValue = ? WHERE value = ?', [999, 'aaa']); // Binding unnamed parameters from array
await db.runAsync('DELETE FROM test WHERE value = $value', { $value: 'aaa' }); // Binding named parameters from object

// `getFirstAsync()` is useful when you want to get a single row from the database.
const firstRow = await db.getFirstAsync('SELECT * FROM test');
console.log(firstRow.id, firstRow.value, firstRow.intValue);

// `getAllAsync()` is useful when you want to get all results as an array of objects.
const allRows = await db.getAllAsync('SELECT * FROM test');
for (const row of allRows) {
  console.log(row.id, row.value, row.intValue);
}

// `getEachAsync()` is useful when you want to iterate SQLite query cursor.
for await (const row of db.getEachAsync('SELECT * FROM test')) {
  console.log(row.id, row.value, row.intValue);
}

Prepared statements

Prepared statement allows you compile your SQL query once and execute it multiple times with different parameters. You can get a prepared statement by calling prepareAsync() or prepareSync() method on a database instance. The prepared statement can fulfill CRUD operations by calling executeAsync() or executeSync() method.

Note: Remember to call finalizeAsync() or finalizeSync() method to release the prepared statement after you finish using the statement. try-finally block is recommended to ensure the prepared statement is finalized.

Prepared statements
const statement = await db.prepareAsync(
  'INSERT INTO test (value, intValue) VALUES ($value, $intValue)'
);
try {
  let result = await statement.executeAsync({ $value: 'bbb', $intValue: 101 });
  console.log('bbb and 101:', result.lastInsertRowId, result.changes);

  result = await statement.executeAsync({ $value: 'ccc', $intValue: 102 });
  console.log('ccc and 102:', result.lastInsertRowId, result.changes);

  result = await statement.executeAsync({ $value: 'ddd', $intValue: 103 });
  console.log('ddd and 103:', result.lastInsertRowId, result.changes);
} finally {
  await statement.finalizeAsync();
}

const statement2 = await db.prepareAsync('SELECT * FROM test WHERE intValue >= $intValue');
try {
  const result = await statement2.executeAsync<{ value: string; intValue: number }>({
    $intValue: 100,
  });

  // `getFirstAsync()` is useful when you want to get a single row from the database.
  const firstRow = await result.getFirstAsync();
  console.log(firstRow.id, firstRow.value, firstRow.intValue);

  // Reset the SQLite query cursor to the beginning for the next `getAllAsync()` call.
  await result.resetAsync();

  // `getAllAsync()` is useful when you want to get all results as an array of objects.
  const allRows = await result.getAllAsync();
  for (const row of allRows) {
    console.log(row.value, row.intValue);
  }

  // Reset the SQLite query cursor to the beginning for the next `for-await-of` loop.
  await result.resetAsync();

  // The result object is also an async iterable. You can use it in `for-await-of` loop to iterate SQLite query cursor.
  for await (const row of result) {
    console.log(row.value, row.intValue);
  }
} finally {
  await statement2.finalizeAsync();
}

useSQLiteContext() hook

useSQLiteContext() hook
import { SQLiteProvider, useSQLiteContext, type SQLiteDatabase } from 'expo-sqlite/next';
import { useEffect, useState } from 'react';
import { View, Text, StyleSheet } from 'react-native';

export default function App() {
  return (
    <View style={styles.container}>
      <SQLiteProvider databaseName="test.db" onInit={migrateDbIfNeeded}>
        <Header />
        <Content />
      </SQLiteProvider>
    </View>
  );
}

export function Header() {
  const db = useSQLiteContext();
  const [version, setVersion] = useState('');
  useEffect(() => {
    async function setup() {
      const result = await db.getFirstAsync<{ 'sqlite_version()': string }>(
        'SELECT sqlite_version()'
      );
      setVersion(result['sqlite_version()']);
    }
    setup();
  }, []);
  return (
    <View style={styles.headerContainer}>
      <Text style={styles.headerText}>SQLite version: {version}</Text>
    </View>
  );
}

interface Todo {
  value: string;
  intValue: number;
}

export function Content() {
  const db = useSQLiteContext();
  const [todos, setTodos] = useState<Todo[]>([]);

  useEffect(() => {
    async function setup() {
      const result = await db.getAllAsync<Todo>('SELECT * FROM todos');
      setTodos(result);
    }
    setup();
  }, []);

  return (
    <View style={styles.contentContainer}>
      {todos.map((todo, index) => (
        <View style={styles.todoItemContainer} key={index}>
          <Text>{`${todo.intValue} - ${todo.value}`}</Text>
        </View>
      ))}
    </View>
  );
}

async function migrateDbIfNeeded(db: SQLiteDatabase) {
  const DATABASE_VERSION = 1;
  let { user_version: currentDbVersion } = await db.getFirstAsync<{ user_version: number }>(
    'PRAGMA user_version'
  );
  if (currentDbVersion >= DATABASE_VERSION) {
    return;
  }
  if (currentDbVersion === 0) {
    await db.execAsync(`
PRAGMA journal_mode = 'wal';
CREATE TABLE todos (id INTEGER PRIMARY KEY NOT NULL, value TEXT NOT NULL, intValue INTEGER);
`);
    await db.runAsync('INSERT INTO todos (value, intValue) VALUES (?, ?)', 'hello', 1);
    await db.runAsync('INSERT INTO todos (value, intValue) VALUES (?, ?)', 'world', 2);
    currentDbVersion = 1;
  }
  // if (currentDbVersion === 1) {
  //   Add more migrations
  // }
  await db.execAsync(`PRAGMA user_version = ${DATABASE_VERSION}`);
}

const styles = StyleSheet.create({
  // Your styles...
});

useSQLiteContext() hook with React.Suspense

As with the useSQLiteContext() hook, you can also integrate the SQLiteProvider with React.Suspense to show a fallback component until the database is ready. To enable the integration, pass the useSuspense prop to the SQLiteProvider component.

useSQLiteContext() hook with React.Suspense
import { SQLiteProvider, useSQLiteContext } from 'expo-sqlite/next';
import { Suspense } from 'react';
import { View, Text, StyleSheet } from 'react-native';

export default function App() {
  return (
    <View style={styles.container}>
      <Suspense fallback={<Fallback />}>
        <SQLiteProvider databaseName="test.db" onInit={migrateDbIfNeeded} useSuspense>
          <Header />
          <Content />
        </SQLiteProvider>
      </Suspense>
    </View>
  );
}

Executing queries within an async transaction

Executing queries within an async transaction
const db = await SQLite.openDatabaseAsync('databaseName');

await db.withTransactionAsync(async () => {
  const result = await db.getFirstAsync('SELECT COUNT(*) FROM USERS');
  console.log('Count:', result.rows[0]['COUNT(*)']);
});

Due to the nature of async/await, any query that runs while the transaction is active will be included in the transaction. This includes query statements that are outside of the scope function passed to withTransactionAsync() and may be surprising behavior. For example, the following test case runs queries inside and outside of a scope function passed to withTransactionAsync(). However, all of the queries will run within the actual SQL transaction because the second UPDATE query runs before the transaction finishes.

Promise.all([
  // 1. A new transaction begins
  db.withTransactionAsync(async () => {
    // 2. The value "first" is inserted into the test table and we wait 2
    //    seconds
    await db.execAsync('INSERT INTO test (data) VALUES ("first")');
    await sleep(2000);

    // 4. Two seconds in, we read the latest data from the table
    const row = await db.getFirstAsync<{ data: string }>('SELECT data FROM test');

    // ❌ The data in the table will be "second" and this expectation will fail.
    //    Additionally, this expectation will throw an error and roll back the
    //    transaction, including the `UPDATE` query below since it ran within
    //    the transaction.
    expect(row.data).toBe('first');
  }),
  // 3. One second in, the data in the test table is updated to be "second".
  //    This `UPDATE` query runs in the transaction even though its code is
  //    outside of it because the transaction happens to be active at the time
  //    this query runs.
  sleep(1000).then(async () => db.execAsync('UPDATE test SET data = "second"')),
]);

The withExclusiveTransactionAsync() function addresses this. Only queries that run within the scope function passed to withExclusiveTransactionAsync() will run within the actual SQL transaction.

Executing PRAGMA queries

Executing PRAGMA queries
const db = await SQLite.openDatabaseAsync('databaseName');
await db.execAsync('PRAGMA journal_mode = WAL');
await db.execAsync('PRAGMA foreign_keys = ON');
Tip: Enable WAL journal mode when you create a new database to improve performance in general.

Import an existing database

To open a new SQLite database using an existing .db file you already have, follow the steps below:

1

Install expo-file-system and expo-asset libraries:

Terminal
npx expo install expo-file-system expo-asset

2

Create a metro.config.js file at the root of your project with the following contents to include extra asset extensions:

metro.config.js
const { getDefaultConfig } = require('expo/metro-config');

const defaultConfig = getDefaultConfig(__dirname);

defaultConfig.resolver.assetExts.push('db');

module.exports = defaultConfig;

3

Use the following function (or similar) to open your database:

async function openDatabase(pathToDatabaseFile: string): Promise<SQLite.Database> {
  if (!(await FileSystem.getInfoAsync(FileSystem.documentDirectory + 'SQLite')).exists) {
    await FileSystem.makeDirectoryAsync(FileSystem.documentDirectory + 'SQLite');
  }
  const asset = await Asset.fromModule(require(pathToDatabaseFile)).downloadAsync();
  await FileSystem.copyAsync({
    from: asset.localUri,
    to: FileSystem.documentDirectory + 'SQLite/myDatabaseName.db',
  });
  return await SQLite.openDatabaseAsync('myDatabaseName.db');
}

Passing binary data

Use Uint8Array to pass binary data to the database:

Passing binary data
await db.execAsync(`
DROP TABLE IF EXISTS blobs;
CREATE TABLE IF NOT EXISTS blobs (id INTEGER PRIMARY KEY NOT NULL, data BLOB);
`);

const blob = new Uint8Array([0x00, 0x01, 0x02, 0x03, 0x04, 0x05]);
await db.runAsync('INSERT INTO blobs (data) VALUES (?)', blob);

const row = await db.getFirstAsync<{ data: Uint8Array }>('SELECT * FROM blobs');
expect(row.data).toEqual(blob);

Third-party library integrations

The expo-sqlite library is designed to be a solid SQLite foundation. It enables broader integrations with third-party libraries for more advanced higher-level features. Here are some of the libraries that you can use with expo-sqlite.

Drizzle ORM

Drizzle is a "headless TypeScript ORM with a head". It runs on Node.js, Bun, Deno, and React Native. It also has a CLI companion called drizzle-kit for generating SQL migrations.

Check out the Drizzle ORM documentation and the expo-sqlite integration guide for more details.

Knex.js

Knex.js is a SQL query builder that is "flexible, portable, and fun to use!"

Check out the expo-sqlite integration guide for more details.

API

Cheatsheet for the common API

The following table summarizes the common API for SQLiteDatabase and SQLiteStatement classes:

SQLiteDatabase methodsSQLiteStatement methodsDescriptionUse Case
runAsync()executeAsync()Executes a SQL query, returning information on the changes made.Ideal for SQL write operations such as INSERT, UPDATE, DELETE.
getFirstAsync()executeAsync() + getFirstAsync()Retrieves the first row from the query result.Suitable for fetching a single row from the database. For example: getFirstAsync('SELECT * FROM Users WHERE id = ?', userId).
getAllAsync()executeAsync() + getFirstAsync()Fetches all query results at once.Best suited for scenarios with smaller result sets, such as queries with a LIMIT clause, like SELECT * FROM Table LIMIT 100, where you intend to retrieve all results in a single batch.
getEachAsync()executeAsync() + for-await-of async iteratorProvides an iterator for result set traversal. This method fetches one row at a time from the database, potentially reducing memory usage compared to getAllAsync().Recommended for handling large result sets incrementally, such as with infinite scrolling implementations.

Component

SQLiteProvider

Type: React.Element<SQLiteProviderProps>

Context.Provider component that provides a SQLite database to all children. All descendants of this component will be able to access the database using the useSQLiteContext hook.

SQLiteProviderProps

databaseName

Type: string

The name of the database file to open.

onError

Optional • Type: (error: Error) => void • Default: rethrow the error

Handle errors from SQLiteProvider.

onInit

Optional • Type: (db: SQLiteDatabase) => Promise<void>

A custom initialization handler to run before rendering the children. You can use this to run database migrations or other setup tasks.

options

Optional • Type: SQLiteOpenOptions

Open options.

useSuspense

Optional • Type: boolean • Default: false

Enable React.Suspense integration.

Example

export default function App() {
  return (
    <Suspense fallback={<Text>Loading...</Text>}>
      <SQLiteProvider databaseName="test.db" useSuspense={true}>
        <Main />
      </SQLiteProvider>
    </Suspense>
  );
}

Hooks

useSQLiteContext()

A global hook for accessing the SQLite database across components. This hook should only be used within a <SQLiteProvider> component.

Returns:

SQLiteDatabase

Example

export default function App() {
  return (
    <SQLiteProvider databaseName="test.db">
      <Main />
    </SQLiteProvider>
  );
}

export function Main() {
  const db = useSQLiteContext();
  console.log('sqlite version', db.getFirstSync('SELECT sqlite_version()'));
  return <View />
}

Classes

SQLiteDatabase

A SQLite database.

SQLiteDatabase Properties

databaseName

Read Only • Type: string

options

Read Only • Type: SQLiteOpenOptions

SQLiteDatabase Methods

closeAsync()

Close the database.

Returns:

Promise<void>

closeSync()

Close the database.

Returns:

void

execAsync(source)

NameTypeDescription
sourcestring

A string containing all the SQL queries.


Execute all SQL queries in the supplied string.

Note: The queries are not escaped for you! Be careful when constructing your queries.

Returns:

Promise<void>

execSync(source)

NameTypeDescription
sourcestring

A string containing all the SQL queries.


Execute all SQL queries in the supplied string.

Note: The queries are not escaped for you! Be careful when constructing your queries.

Note: Running heavy tasks with this function can block the JavaScript thread and affect performance.

Returns:

void

getAllAsync<T>(source, params)


A convenience wrapper around SQLiteDatabase.prepareAsync(), SQLiteStatement.executeAsync(), SQLiteExecuteAsyncResult.getAllAsync(), and SQLiteStatement.finalizeAsync().

Returns:

Promise<T[]>

Example

// For unnamed parameters, you pass values in an array.
db.getAllAsync('SELECT * FROM test WHERE intValue = ? AND name = ?', [1, 'Hello']);

// For unnamed parameters, you pass values in variadic arguments.
db.getAllAsync('SELECT * FROM test WHERE intValue = ? AND name = ?', 1, 'Hello');

// For named parameters, you should pass values in object.
db.getAllAsync('SELECT * FROM test WHERE intValue = $intValue AND name = $name', { $intValue: 1, $name: 'Hello' });

getAllSync<T>(source, params)

NameTypeDescription
sourcestring

A string containing the SQL query.

paramsSQLiteBindParams

The parameters to bind to the prepared statement. You can pass values in array, object, or variadic arguments. See SQLiteBindValue for more information about binding values.


A convenience wrapper around SQLiteDatabase.prepareSync(), SQLiteStatement.executeSync(), SQLiteExecuteSyncResult.getAllSync(), and SQLiteStatement.finalizeSync().

Note: Running heavy tasks with this function can block the JavaScript thread and affect performance.

Returns:

T[]

getEachAsync<T>(source, params)

NameTypeDescription
sourcestring

A string containing the SQL query.

paramsSQLiteBindParams

The parameters to bind to the prepared statement. You can pass values in array, object, or variadic arguments. See SQLiteBindValue for more information about binding values.


A convenience wrapper around SQLiteDatabase.prepareAsync(), SQLiteStatement.executeAsync(), SQLiteExecuteAsyncResult AsyncIterator, and SQLiteStatement.finalizeAsync().

Rather than returning Promise, this function returns an AsyncIterableIterator. You can use for await...of to iterate over the rows from the SQLite query result.

getEachSync<T>(source, params)

NameTypeDescription
sourcestring

A string containing the SQL query.

paramsSQLiteBindParams

The parameters to bind to the prepared statement. You can pass values in array, object, or variadic arguments. See SQLiteBindValue for more information about binding values.


A convenience wrapper around SQLiteDatabase.prepareSync(), SQLiteStatement.executeSync(), SQLiteExecuteSyncResult Iterator, and SQLiteStatement.finalizeSync().

Note: Running heavy tasks with this function can block the JavaScript thread and affect performance.

Returns:

IterableIterator<T>

This function returns an IterableIterator. You can use for...of to iterate over the rows from the SQLite query result.

getFirstAsync<T>(source, params)

NameTypeDescription
sourcestring

A string containing the SQL query.

paramsSQLiteBindParams

The parameters to bind to the prepared statement. You can pass values in array, object, or variadic arguments. See SQLiteBindValue for more information about binding values.


A convenience wrapper around SQLiteDatabase.prepareAsync(), SQLiteStatement.executeAsync(), SQLiteExecuteAsyncResult.getFirstAsync(), and SQLiteStatement.finalizeAsync().

Returns:

Promise<null | T>

getFirstSync<T>(source, params)

NameTypeDescription
sourcestring

A string containing the SQL query.

paramsSQLiteBindParams

The parameters to bind to the prepared statement. You can pass values in array, object, or variadic arguments. See SQLiteBindValue for more information about binding values.


A convenience wrapper around SQLiteDatabase.prepareSync(), SQLiteStatement.executeSync(), SQLiteExecuteSyncResult.getFirstSync(), and SQLiteStatement.finalizeSync().

Note: Running heavy tasks with this function can block the JavaScript thread and affect performance.

Returns:

null | T

isInTransactionAsync()

Asynchronous call to return whether the database is currently in a transaction.

Returns:

Promise<boolean>

isInTransactionSync()

Synchronous call to return whether the database is currently in a transaction.

Returns:

boolean

prepareAsync(source)

NameTypeDescription
sourcestring

A string containing the SQL query.


Create a prepared SQLite statement.

prepareSync(source)

NameTypeDescription
sourcestring

A string containing the SQL query.


Create a prepared SQLite statement.

Note: Running heavy tasks with this function can block the JavaScript thread and affect performance.

runAsync(source, params)

NameTypeDescription
sourcestring

A string containing the SQL query.

paramsSQLiteBindParams

The parameters to bind to the prepared statement. You can pass values in array, object, or variadic arguments. See SQLiteBindValue for more information about binding values.


A convenience wrapper around SQLiteDatabase.prepareAsync(), SQLiteStatement.executeAsync(), and SQLiteStatement.finalizeAsync().

runSync(source, params)

NameTypeDescription
sourcestring

A string containing the SQL query.

paramsSQLiteBindParams

The parameters to bind to the prepared statement. You can pass values in array, object, or variadic arguments. See SQLiteBindValue for more information about binding values.


A convenience wrapper around SQLiteDatabase.prepareSync(), SQLiteStatement.executeSync(), and SQLiteStatement.finalizeSync().

Note: Running heavy tasks with this function can block the JavaScript thread and affect performance.

withExclusiveTransactionAsync(task)

NameTypeDescription
task(txn: Transaction) => Promise<void>

An async function to execute within a transaction. Any queries inside the transaction must be executed on the txn object. The txn object has the same interfaces as the SQLiteDatabase object. You can use txn like a SQLiteDatabase object.


Execute a transaction and automatically commit/rollback based on the task result.

The transaction may be exclusive. As long as the transaction is converted into a write transaction, the other async write queries will abort with database is locked error.

Returns:

Promise<void>

Example

db.withExclusiveTransactionAsync(async (txn) => {
  await txn.execAsync('UPDATE test SET name = "aaa"');
});

withTransactionAsync(task)

NameTypeDescription
task() => Promise<void>

An async function to execute within a transaction.


Execute a transaction and automatically commit/rollback based on the task result.

Note: This transaction is not exclusive and can be interrupted by other async queries.

Returns:

Promise<void>

Example

db.withTransactionAsync(async () => {
  await db.execAsync('UPDATE test SET name = "aaa"');

  //
  // We cannot control the order of async/await order, so order of execution is not guaranteed.
  // The following UPDATE query out of transaction may be executed here and break the expectation.
  //

  const result = await db.getAsync<{ name: string }>('SELECT name FROM Users');
  expect(result?.name).toBe('aaa');
});
db.execAsync('UPDATE test SET name = "bbb"');

If you worry about the order of execution, use withExclusiveTransactionAsync instead.

withTransactionSync(task)

NameTypeDescription
task() => void

An async function to execute within a transaction.


Execute a transaction and automatically commit/rollback based on the task result.

Note: Running heavy tasks with this function can block the JavaScript thread and affect performance.

Returns:

void

SQLiteStatement

A prepared statement returned by SQLiteDatabase.prepareAsync() or SQLiteDatabase.prepareSync() that can be binded with parameters and executed.

SQLiteStatement Methods

executeAsync<T>(params)

NameTypeDescription
paramsSQLiteBindParams

The parameters to bind to the prepared statement. You can pass values in array, object, or variadic arguments. See SQLiteBindValue for more information about binding values.


Run the prepared statement and return the SQLiteExecuteAsyncResult instance.

Returns:

Promise<SQLiteExecuteAsyncResult<T>>

executeSync<T>(params)

NameTypeDescription
paramsSQLiteBindParams

The parameters to bind to the prepared statement. You can pass values in array, object, or variadic arguments. See SQLiteBindValue for more information about binding values.


Run the prepared statement and return the SQLiteExecuteSyncResult instance.

Note: Running heavy tasks with this function can block the JavaScript thread and affect performance.

finalizeAsync()

Finalize the prepared statement. This will call the sqlite3_finalize() C function under the hood.

Attempting to access a finalized statement will result in an error.

Note: While expo-sqlite will automatically finalize any orphaned prepared statements upon closing the database, it is considered best practice to manually finalize prepared statements as soon as they are no longer needed. This helps to prevent resource leaks. You can use the try...finally statement to ensure that prepared statements are finalized even if an error occurs.

Returns:

Promise<void>

finalizeSync()

Finalize the prepared statement. This will call the sqlite3_finalize() C function under the hood.

Attempting to access a finalized statement will result in an error.

Note: While expo-sqlite will automatically finalize any orphaned prepared statements upon closing the database, it is considered best practice to manually finalize prepared statements as soon as they are no longer needed. This helps to prevent resource leaks. You can use the try...finally statement to ensure that prepared statements are finalized even if an error occurs.

Returns:

void

getColumnNamesAsync()

Get the column names of the prepared statement.

Returns:

Promise<string[]>

getColumnNamesSync()

Get the column names of the prepared statement.

Returns:

string[]

Methods

SQLite.deleteDatabaseAsync(databaseName)

NameTypeDescription
databaseNamestring

The name of the database file to delete.


Delete a database file.

Returns:

Promise<void>

SQLite.deleteDatabaseSync(databaseName)

NameTypeDescription
databaseNamestring

The name of the database file to delete.


Delete a database file.

Note: Running heavy tasks with this function can block the JavaScript thread and affect performance.

Returns:

void

SQLite.openDatabaseAsync(databaseName, options)

NameTypeDescription
databaseNamestring

The name of the database file to open.

options
(optional)
SQLiteOpenOptions

Open options.


Open a database.

Returns:

Promise<SQLiteDatabase>

SQLite.openDatabaseSync(databaseName, options)

NameTypeDescription
databaseNamestring

The name of the database file to open.

options
(optional)
SQLiteOpenOptions

Open options.


Open a database.

Note: Running heavy tasks with this function can block the JavaScript thread and affect performance.

Returns:

SQLiteDatabase

Event Subscriptions

SQLite.addDatabaseChangeListener(listener)

NameTypeDescription
listener(event: DatabaseChangeEvent) => void

A function that receives the databaseName, databaseFilePath, tableName and rowId of the modified data.


Add a listener for database changes.

Note: to enable this feature, you must set enableChangeListener to true when opening the database.

Returns:

Subscription

A Subscription object that you can call remove() on when you would like to unsubscribe the listener.

Interfaces

SQLiteExecuteAsyncResult

Extends: AsyncIterableIterator<T>

A result returned by SQLiteStatement.executeAsync().

Example

The result includes the lastInsertRowId and changes properties. You can get the information from the write operations.

const statement = await db.prepareAsync('INSERT INTO test (value) VALUES (?)');
try {
  const result = await statement.executeAsync(101);
  console.log('lastInsertRowId:', result.lastInsertRowId);
  console.log('changes:', result.changes);
} finally {
  await statement.finalizeAsync();
}

Example

The result implements the AsyncIterator interface, so you can use it in for await...of loops.

const statement = await db.prepareAsync('SELECT value FROM test WHERE value > ?');
try {
  const result = await statement.executeAsync<{ value: number }>(100);
  for await (const row of result) {
    console.log('row value:', row.value);
  }
} finally {
  await statement.finalizeAsync();
}

Example

If your write operations also return values, you can mix all of them together.

const statement = await db.prepareAsync('INSERT INTO test (name, value) VALUES (?, ?) RETURNING name');
try {
  const result = await statement.executeAsync<{ name: string }>('John Doe', 101);
  console.log('lastInsertRowId:', result.lastInsertRowId);
  console.log('changes:', result.changes);
  for await (const row of result) {
    console.log('name:', row.name);
  }
} finally {
  await statement.finalizeAsync();
}

SQLiteExecuteAsyncResult Methods

getAllAsync()

Get all rows of the result set. This requires the SQLite cursor to be in its initial state. If you have already retrieved rows from the result set, you need to reset the cursor first by calling resetAsync(). Otherwise, an error will be thrown.

Returns:

Promise<T[]>

getFirstAsync()

Get the first row of the result set. This requires the SQLite cursor to be in its initial state. If you have already retrieved rows from the result set, you need to reset the cursor first by calling resetAsync(). Otherwise, an error will be thrown.

Returns:

Promise<null | T>

resetAsync()

Reset the prepared statement cursor. This will call the sqlite3_reset() C function under the hood.

Returns:

Promise<void>

SQLiteExecuteAsyncResult Properties

NameTypeDescription
changesnumber

The number of rows affected. Returned from the sqlite3_changes() function.

lastInsertRowIdnumber

The last inserted row ID. Returned from the sqlite3_last_insert_rowid() function.


SQLiteExecuteSyncResult

Extends: IterableIterator<T>

A result returned by SQLiteStatement.executeSync().

Note: Running heavy tasks with this function can block the JavaScript thread and affect performance.

Example

The result includes the lastInsertRowId and changes properties. You can get the information from the write operations.

const statement = db.prepareSync('INSERT INTO test (value) VALUES (?)');
try {
  const result = statement.executeSync(101);
  console.log('lastInsertRowId:', result.lastInsertRowId);
  console.log('changes:', result.changes);
} finally {
  statement.finalizeSync();
}

Example

The result implements the Iterator interface, so you can use it in for...of loops.

const statement = db.prepareSync('SELECT value FROM test WHERE value > ?');
try {
  const result = statement.executeSync<{ value: number }>(100);
  for (const row of result) {
    console.log('row value:', row.value);
  }
} finally {
  statement.finalizeSync();
}

Example

If your write operations also return values, you can mix all of them together.

const statement = db.prepareSync('INSERT INTO test (name, value) VALUES (?, ?) RETURNING name');
try {
  const result = statement.executeSync<{ name: string }>('John Doe', 101);
  console.log('lastInsertRowId:', result.lastInsertRowId);
  console.log('changes:', result.changes);
  for (const row of result) {
    console.log('name:', row.name);
  }
} finally {
  statement.finalizeSync();
}

SQLiteExecuteSyncResult Methods

getAllSync()

Get all rows of the result set. This requires the SQLite cursor to be in its initial state. If you have already retrieved rows from the result set, you need to reset the cursor first by calling resetSync(). Otherwise, an error will be thrown.

Returns:

T[]

getFirstSync()

Get the first row of the result set. This requires the SQLite cursor to be in its initial state. If you have already retrieved rows from the result set, you need to reset the cursor first by calling resetSync(). Otherwise, an error will be thrown.

Returns:

null | T

resetSync()

Reset the prepared statement cursor. This will call the sqlite3_reset() C function under the hood.

Returns:

void

SQLiteExecuteSyncResult Properties

NameTypeDescription
changesnumber

The number of rows affected. Returned from the sqlite3_changes() function.

lastInsertRowIdnumber

The last inserted row ID. Returned from the sqlite3_last_insert_rowid() function.


SQLiteOpenOptions

Options for opening a database.

SQLiteOpenOptions Properties

NameTypeDescription
enableCRSQLite
(optional)
boolean

Whether to enable the CR-SQLite extension.

Default: false
enableChangeListener
(optional)
boolean

Whether to call the sqlite3_update_hook() function and enable the onDatabaseChange events. You can later subscribe to the change events by addDatabaseChangeListener.

Default: false
useNewConnection
(optional)
boolean

Whether to create new connection even if connection with the same database name exists in cache.

Default: false

SQLiteRunResult

A result returned by SQLiteDatabase.runAsync or SQLiteDatabase.runSync.

SQLiteRunResult Properties

NameTypeDescription
changesnumber

The number of rows affected. Returned from the sqlite3_changes() function.

lastInsertRowIdnumber

The last inserted row ID. Returned from the sqlite3_last_insert_rowid() function.


Types

DatabaseChangeEvent

The event payload for the listener of addDatabaseChangeListener

NameTypeDescription
databaseFilePathstring

The absolute file path to the database.

databaseNamestring

The database name. The value would be main by default and other database names if you use ATTACH DATABASE statement.

rowIdnumber

The changed row ID.

tableNamestring

The table name.

SQLiteBindParams

Literal Type: multiple types

Acceptable values are: Record<string, SQLiteBindValue>

SQLiteBindValue

Literal Type: multiple types

Bind parameters to the prepared statement. You can either pass the parameters in the following forms:

Example

A single array for unnamed parameters.

const statement = await db.prepareAsync('SELECT * FROM test WHERE value = ? AND intValue = ?');
const result = await statement.executeAsync(['test1', 789]);
const firstRow = await result.getFirstAsync();

Example

Variadic arguments for unnamed parameters.

const statement = await db.prepareAsync('SELECT * FROM test WHERE value = ? AND intValue = ?');
const result = await statement.executeAsync('test1', 789);
const firstRow = await result.getFirstAsync();

Example

A single object for named parameters

We support multiple named parameter forms such as :VVV, @VVV, and $VVV. We recommend using $VVV because JavaScript allows using $ in identifiers without escaping.

const statement = await db.prepareAsync('SELECT * FROM test WHERE value = $value AND intValue = $intValue');
const result = await statement.executeAsync({ $value: 'test1', $intValue: 789 });
const firstRow = await result.getFirstAsync();

Acceptable values are: string | number | null | boolean | Uint8Array

SQLiteVariadicBindParams

Type: SQLiteBindValue[]