HomeGuidesReferenceLearn

Reference version

Expo SQLite iconExpo 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 DeviceAndroid EmulatoriOS DeviceiOS SimulatorWeb

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:

1

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

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:

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

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

ExpoSQLTransactionAsync

Type: Class implements SQLTransactionAsync

Internal data structure for the async transaction API.

SQLError

SQLError Properties

SQLiteDatabase

The database returned by openDatabase()

SQLiteDatabase Properties

Deprecated. Use closeAsync() instead.

close

Type: () => void

version

Type: string


SQLiteDatabase Methods

closeAsync()

Close the database.

Returns

  • void

deleteAsync()

Delete the database file.

The database has to be closed prior to deletion.

Returns


exec(queries, readOnly, callback)

NameTypeDescription
queriesQuery[]-
readOnlyboolean-
callbackSQLiteCallback-

Executes the SQL statement and returns a callback resolving with the result.

Returns

  • void

execAsync(queries, readOnly)

NameTypeDescription
queriesQuery[]-
readOnlyboolean-

Executes the SQL statement and returns a Promise resolving with the result.

Returns


readTransaction(callback, errorCallback, successCallback)

NameTypeDescription
callbackSQLTransactionCallback-
errorCallback
(optional)
SQLTransactionErrorCallback-
successCallback
(optional)
() => void-

Returns

  • void

transaction(callback, errorCallback, successCallback)

NameTypeDescription
callbackSQLTransactionCallback

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

transactionAsync(asyncCallback, readOnly)

NameTypeDescription
asyncCallbackSQLTransactionAsyncCallback

A SQLTransactionAsyncCallback function that can perform SQL statements in a transaction.

readOnly
(optional)
boolean

true if all the SQL statements in the callback are read only.

Default: false

Creates a new transaction with Promise support.

Returns


Methods

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

NameTypeDescription
namestring

Name of the database file to open.

version
(optional)
string-
description
(optional)
string-
size
(optional)
number-
callback
(optional)
(db: SQLiteDatabase) => 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


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)

NameTypeDescription
callbackSQLTransactionCallback-
errorCallback
(optional)
SQLTransactionErrorCallback-
successCallback
(optional)
() => void-

Returns

  • void

transaction(callback, errorCallback, successCallback)

NameTypeDescription
callbackSQLTransactionCallback

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

NameTypeDescription
versionstring-

ResultSet

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

ResultSet Properties

NameTypeDescription
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 }-
rowsAffectednumber

The number of rows that were changed by the SQL statement.


ResultSetError

ResultSetError Properties

NameTypeDescription
errorError-

SQLResultSetRowList

SQLResultSetRowList Methods

item(index)

NameTypeDescription
indexnumber

Index of row to get.


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

Returns

  • any

SQLResultSetRowList Properties

NameTypeDescription
_arrayany[]

The actual array of rows returned by the query. Can be used directly instead of getting rows through rows.item().

lengthnumber

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)

NameTypeDescription
sqlStatementstring

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

SQLTransactionAsync

A transaction object to perform SQL statements in async mode.

SQLTransactionAsync Methods

executeSqlAsync(sqlStatement, args)

NameTypeDescription
sqlStatementstring-
args
(optional)
(string | number)[]-

Executes a SQL statement in async mode.

Returns


Deprecated. Use SQLiteDatabase instead.

WebSQLDatabase

Extends: Database

WebSQLDatabase Methods

closeAsync()

Close the database.

Returns

  • void

deleteAsync()

Delete the database file.

The database has to be closed prior to deletion.

Returns


exec(queries, readOnly, callback)

NameTypeDescription
queriesQuery[]-
readOnlyboolean-
callbackSQLiteCallback-

Returns

  • void

Window

Window Properties

NameTypeDescription
openDatabase
(optional)
(name: string, version: string, displayName: string, estimatedSize: number, creationCallback: DatabaseCallback) => Database-

Types

DatabaseCallback()

NameTypeDescription
databaseDatabase-

Query

NameTypeDescription
argsunknown[]-
sqlstring-

SQLResultSet

NameTypeDescription
insertId
(optional)
number

The row ID of the row that the SQL statement inserted into the database, if a row was inserted.

rowsSQLResultSetRowList-
rowsAffectednumber

The number of rows that were changed by the SQL statement.

SQLStatementCallback()

NameTypeDescription
transactionSQLTransaction-
resultSetSQLResultSet-

SQLStatementErrorCallback()

NameTypeDescription
transactionSQLTransaction-
errorSQLError-

SQLTransactionAsyncCallback()

A transaction callback with given SQLTransactionAsync object to perform SQL statements in async mode.

NameTypeDescription
transactionSQLTransactionAsync-

SQLTransactionCallback()

NameTypeDescription
transactionSQLTransaction-

SQLTransactionErrorCallback()

NameTypeDescription
errorSQLError-

SQLiteCallback()

NameTypeDescription
error
(optional)
Error | null-
resultSet
(optional)
(ResultSetError | ResultSet)[]-