Reference version

SDK 48

Archive Expo Snack Discord and Forums Newsletter

Expo SQLite

GitHub

npm

A library that provides access to a database that can be queried through a WebSQL-like API.

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

Platform Compatibility

Android Device	Android Emulator	iOS Device	iOS Simulator	Web

Installation

Terminal

- npx expo install expo-sqlite

If you're installing this in a bare React Native app, you should also follow these additional installation instructions.

Usage

To-do list app

An example to-do list app is available that uses this module for storage.

Importing an existing database

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

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

Terminal

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

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

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

const defaultConfig = getDefaultConfig(__dirname);

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

module.exports = defaultConfig;

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

import * as FileSystem from 'expo-file-system';
import * as SQLite from 'expo-sqlite';
import { Asset } from 'expo-asset';

async function openDatabase(pathToDatabaseFile: string): Promise<SQLite.WebSQLDatabase> {
  if (!(await FileSystem.getInfoAsync(FileSystem.documentDirectory + 'SQLite')).exists) {
    await FileSystem.makeDirectoryAsync(FileSystem.documentDirectory + 'SQLite');
  }
  await FileSystem.downloadAsync(
    Asset.fromModule(require(pathToDatabaseFile)).uri,
    FileSystem.documentDirectory + 'SQLite/myDatabaseName.db'
  );
  return SQLite.openDatabase('myDatabaseName.db');
}

Executing statements outside of a transaction

You should use this kind of execution only when it is necessary. For instance, when code is a no-op within transactions. Example: PRAGMA foreign_keys = ON;.

import * as SQLite from 'expo-sqlite';

const db = SQLite.openDatabase('dbName', version);

db.exec([{ sql: 'PRAGMA foreign_keys = ON;', args: [] }], false, () =>
  console.log('Foreign keys turned on')
);

API

import * as SQLite from 'expo-sqlite';

Classes

Methods

`SQLite.openDatabase(name, version, description, size, callback)`

Name	Type	Description
name	`string`	Name of the database file to open.
version (optional)	`string`	-
description (optional)	`string`	-
size (optional)	`number`	-
callback (optional)	`(db: WebSQLDatabase) => void`	-

Open a database, creating it if it doesn't exist, and return a Database object. On disk, the database will be created under the app's documents directory, i.e. ${FileSystem.documentDirectory}/SQLite/${name}.

The version, description and size arguments are ignored, but are accepted by the function for compatibility with the WebSQL specification.

Returns

WebSQLDatabase

Interfaces

`Database`

Database objects are returned by calls to SQLite.openDatabase(). Such an object represents a connection to a database on your device.

Database Methods

`readTransaction(callback, errorCallback, successCallback)`

Name	Type	Description
callback	`SQLTransactionCallback`	-
errorCallback (optional)	`SQLTransactionErrorCallback`	-
successCallback (optional)	`() => void`	-

Returns

void

`transaction(callback, errorCallback, successCallback)`

Name	Type	Description
callback	`SQLTransactionCallback`	A function representing the transaction to perform. Takes a Transaction (see below) as its only parameter, on which it can add SQL statements to execute.
errorCallback (optional)	`SQLTransactionErrorCallback`	Called if an error occurred processing this transaction. Takes a single parameter describing the error.
successCallback (optional)	`() => void`	Called when the transaction has completed executing on the database.

Execute a database transaction.

Returns

void

Database Properties

Name	Type	Description
version	`string`	-

`SQLResultSetRowList`

SQLResultSetRowList Methods

`item(index)`

Name	Type	Description
index	`number`	Index of row to get.

Returns the row with the given index. If there is no such row, returns null.

Returns

any

SQLResultSetRowList Properties

Name	Type	Description
_array	`any[]`	The actual array of rows returned by the query. Can be used directly instead of getting rows through rows.item().
length	`number`	The number of rows returned by the query.

`SQLTransaction`

A SQLTransaction object is passed in as a parameter to the callback parameter for the db.transaction() method on a Database (see above). It allows enqueuing SQL statements to perform in a database transaction.

SQLTransaction Methods

`executeSql(sqlStatement, args, callback, errorCallback)`

Name	Type	Description
sqlStatement	`string`	A string containing a database query to execute expressed as SQL. The string may contain `?` placeholders, with values to be substituted listed in the `arguments` parameter.
args (optional)	`(null \| string \| number)[]`	An array of values (numbers, strings or nulls) to substitute for `?` placeholders in the SQL statement.
callback (optional)	`SQLStatementCallback`	Called when the query is successfully completed during the transaction. Takes two parameters: the transaction itself, and a `ResultSet` object (see below) with the results of the query.
errorCallback (optional)	`SQLStatementErrorCallback`	Called if an error occurred executing this particular query in the transaction. Takes two parameters: the transaction itself, and the error object.

Enqueue a SQL statement to execute in the transaction. Authors are strongly recommended to make use of the ? placeholder feature of the method to avoid against SQL injection attacks, and to never construct SQL statements on the fly.

Returns

void

`WebSQLDatabase`

Extends: Database

Database objects are returned by calls to SQLite.openDatabase(). Such an object represents a connection to a database on your device.

WebSQLDatabase Methods

`closeAsync()`

Close the database.

Returns

void

`deleteAsync()`

Delete the database file.

The database has to be closed prior to deletion.

Returns

Promise<void>

`exec(queries, readOnly, callback)`

Name	Type	Description
queries	`Query[]`	-
readOnly	`boolean`	-
callback	`SQLiteCallback`	-

Returns

void

`Window`

Window Properties

Name	Type	Description
openDatabase (optional)	`(name: string, version: string, displayName: string, estimatedSize: number, creationCallback: DatabaseCallback) => Database`	-

Types

`DatabaseCallback()`

Name	Type	Description
database	`Database`	-

`Query`

Name	Type	Description
args	`unknown[]`	-
sql	`string`	-

`ResultSet`

ResultSet objects are returned through second parameter of the success callback for the tx.executeSql() method on a SQLTransaction (see above).

Name	Type	Description
insertId (optional)	`number`	The row ID of the row that the SQL statement inserted into the database, if a row was inserted.
rows	`{ [column]: any }`	-
rowsAffected	`number`	The number of rows that were changed by the SQL statement.

`ResultSetError`

Name	Type	Description
error	`Error`	-

`SQLResultSet`

Name	Type	Description
insertId (optional)	`number`	The row ID of the row that the SQL statement inserted into the database, if a row was inserted.
rows	`SQLResultSetRowList`	-
rowsAffected	`number`	The number of rows that were changed by the SQL statement.

`SQLStatementCallback()`

Name	Type	Description
transaction	`SQLTransaction`	-
resultSet	`SQLResultSet`	-

`SQLStatementErrorCallback()`

Name	Type	Description
transaction	`SQLTransaction`	-
error	`SQLError`	-

`SQLTransactionCallback()`

Name	Type	Description
transaction	`SQLTransaction`	-

`SQLTransactionErrorCallback()`

Name	Type	Description
error	`SQLError`	-

`SQLiteCallback()`

Name	Type	Description
error (optional)	`Error \| null`	-
resultSet (optional)	`(ResultSetError \| ResultSet)[]`	-