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.
Android Device | Android Emulator | iOS Device | iOS Simulator | Web |
---|---|---|---|---|
-Â
npx expo install expo-sqlite
If you're installing this in a bare React Native app, you should also follow these additional installation instructions.
An example to-do list app is available that uses this module for storage.
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:
-Â
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');
}
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')
);
import * as SQLite from 'expo-sqlite';
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
andsize
arguments are ignored, but are accepted by the function for compatibility with the WebSQL specification.
Returns
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 |
args (optional) | (null | string | number)[] | An array of values (numbers, strings or nulls) to substitute for |
callback (optional) | SQLStatementCallback | Called when the query is successfully completed during the transaction. Takes
two parameters: the transaction itself, and a |
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
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 | - |
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)[] | - |