HomeGuidesReferenceLearn

Reference version

ArchiveExpo SnackDiscord and ForumsNewsletter

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:

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

ExpoSQLTransactionAsync

Type: Class implements SQLTransactionAsync

Internal data structure for the async transaction API.

SQLError

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

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:

Promise<void>

exec(queries, readOnly, callback)

NameType
queriesQuery[]
readOnlyboolean
callbackSQLiteCallback

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

Returns:

void

execAsync(queries, readOnly)

NameType
queriesQuery[]
readOnlyboolean

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

readTransaction(callback, errorCallback, successCallback)

NameType
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:

Promise<void>

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:

SQLiteDatabase

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)

NameType
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)

NameType
sqlStatementstring
args
(optional)
(string | number)[]

Executes a SQL statement in async mode.

Returns:

Promise<ResultSetError | ResultSet>

Deprecated. Use SQLiteDatabase instead.

WebSQLDatabase

Extends: Database

WebSQLDatabase Methods

deleteAsync()

Delete the database file.

The database has to be closed prior to deletion.

Returns:

Promise<void>

exec(queries, readOnly, callback)

NameType
queriesQuery[]
readOnlyboolean
callbackSQLiteCallback

Returns:

void

Window

Window Properties

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

Types

DatabaseCallback()

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

NameType
transactionSQLTransaction
resultSetSQLResultSet

SQLStatementErrorCallback()

NameType
transactionSQLTransaction
errorSQLError

SQLTransactionAsyncCallback()

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

NameType
transactionSQLTransactionAsync

SQLTransactionCallback()

NameType
transactionSQLTransaction

SQLTransactionErrorCallback()

NameType
errorSQLError

SQLiteCallback()

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