SQLite

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.

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

Platform Compatibility

Android Device	Android Emulator	iOS Device	iOS Simulator	Web

Guides

Importing an existing database

In order to open a new SQLite database using an existing .db file you already have, you need to do three things:

expo install expo-file-system expo-asset
create a metro.config.js file in the root of your project with the following contents (curious why? read here):

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:

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

Please note that you should use this kind of execution only when it is necessary. For instance, when code is a no-op within transactions (like eg. PRAGMA foreign_keys = ON;).

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

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

Installation

Terminal

→ expo install expo-sqlite

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

API

import * as SQLite from 'expo-sqlite';

SQLError Properties

code
Type: number
message
Type: string
CONSTRAINT_ERR
Type: number
DATABASE_ERR
Type: number
QUOTA_ERR
Type: number
SYNTAX_ERR
Type: number
TIMEOUT_ERR
Type: number
TOO_LARGE_ERR
Type: number
UNKNOWN_ERR
Type: number
VERSION_ERR
Type: number

Methods

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

Arguments

name (string) - Name of the database file to open.
version (string)
description (string)
size (number)
callback? ((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

Types

`DatabaseCallback()`

Arguments

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()`

Arguments

transaction (SQLTransaction)
resultSet (SQLResultSet)

`SQLStatementErrorCallback()`

Arguments

transaction (SQLTransaction)
error (SQLError)

`SQLTransactionCallback()`

Arguments

transaction (SQLTransaction)

`SQLTransactionErrorCallback()`

Arguments

error (SQLError)

`SQLiteCallback()`

Arguments

error? (Error | null)
resultSet? ((ResultSetError | ResultSet)[])

Interfaces

`Database`

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

Name	Type	Description
version	`string`	-
readTransaction()	`(callback, errorCallback, successCallback) => void`	callback (`SQLTransactionCallback`) errorCallback? (`SQLTransactionErrorCallback`) successCallback? (`() => void`) Returns: `void`
transaction()	`(callback, errorCallback, successCallback) => void`	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? (`SQLTransactionErrorCallback`) - Called if an error occurred processing this transaction. Takes a single parameter describing the error. successCallback? (`() => void`) - Called when the transaction has completed executing on the database. Returns: `void` Execute a database transaction.

`SQLResultSetRowList`

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.
item()	`(index) => any`	index (`number`) - Index of row to get. Returns: `any` Returns the row with the given `index`. If there is no such row, returns `null`.

`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.

Name	Type	Description
executeSql()	`(sqlStatement, args, callback, errorCallback) => void`	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? (`(string \| number)[]`) - An array of values (numbers or strings) to substitute for `?` placeholders in the SQL statement. callback? (`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? (`SQLStatementErrorCallback`) - Called if an error occurred executing this particular query in the transaction. Takes two parameters: the transaction itself, and the error object. Returns: `void` 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.

`WebSQLDatabase`

Extends: Database

Name	Type	Description
close()	`() => void`	Returns: `void` Close the database.
deleteAsync()	`() => Promise<void>`	Returns: `Promise<void>` Delete the database file.
exec()	`(queries, readOnly, callback) => void`	queries (`Query[]`) readOnly (`boolean`) callback (`SQLiteCallback`) Returns: `void`

`Window`

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