This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.
Expo SQLite
提供访问数据库功能的库，可通过 SQLite API 对数据库进行查询。
原文内容已经是简体中文，无需翻译。
使用 expo-sqlite/kv-store 的一大好处是增加了同步 API，使用起来更加方便：
如果你的项目当前使用的是 @react-native-async-storage/async-storage，切换到 expo-sqlite/kv-store 只需更改导入语句：
- import AsyncStorage from '@react-native-async-storage/async-storage'; + import AsyncStorage from 'expo-sqlite/kv-store';
localStorage API
expo-sqlite/localStorage/install 模块提供了 localStorage API 的即插即用实现。如果你已经熟悉 Web 上的此 API，或者希望能够在 Web 和其他平台之间共享存储代码，那么这可能会很有用。要使用它，只需导入 expo-sqlite/localStorage/install 模块：
注意：
import 'expo-sqlite/localStorage/install';在 Web 上是无操作的，并且会从生产环境的 JS 包中排除。
安全
SQL 注入是一类漏洞，攻击者会诱骗你的应用将用户输入作为 SQL 代码执行。你必须对传递给 SQLite 的所有用户输入进行转义，以防御 SQL 注入。预处理语句是防御此问题的有效方法。它们明确地将 SQL 查询的逻辑与其输入参数分离开来，并且 SQLite 在执行预处理语句时会自动对输入进行转义。
第三方库集成
expo-sqlite 库旨在提供稳健的 SQLite 基础。它支持与第三方库进行更广泛的集成，以实现更高级的功能。以下是一些可以与 expo-sqlite 一起使用的库。
Drizzle ORM
Drizzle 是一个"具有头部的无头 TypeScript ORM"。它可以在 Node.js、Bun、Deno 和 React Native 上运行。它还提供了一个名为 drizzle-kit 的 CLI 配套工具，用于生成 SQL 迁移。
如需了解更多详情，请参阅 Drizzle ORM 文档 和 expo-sqlite 集成指南。
Knex.js
Knex.js 是一个 SQL 查询构建器，"灵活、可移植且使用起来很有趣！"
如需了解更多详情，请参阅 expo-sqlite 集成指南。
SQLCipher
注意： SQLCipher 不支持在 Expo Go 上使用。
SQLCipher 是 SQLite 的一个分支，为数据库添加了加密和身份验证功能。expo-sqlite 库支持在 Android、iOS 和 macOS 上使用 SQLCipher。要使用 SQLCipher，您需要按照应用配置中的配置部分所示，将 useSQLCipher 配置添加到 app.json，然后运行 npx expo prebuild。
打开数据库后，需要立即使用 PRAGMA key = 'password' 语句为数据库设置密码。
API
常用 API 速查表
下表总结了 SQLiteDatabase 和 SQLiteStatement 类的常用 API：
Constants
Type: SQLiteStorage
This default instance of the SQLiteStorage class is used as a drop-in replacement for the AsyncStorage module from @react-native-async-storage/async-storage.
Type: Record<string, {
entryPoint: string,
libPath: string
} | undefined>
The pre-bundled SQLite extensions.
Type: any
The default directory for SQLite databases.
Type: MemoExoticComponent<(__namedParameters: SQLiteProviderProps) => Element>
Context.Provider component that provides a SQLite database to all children.
All descendants of this component will be able to access the database using the useSQLiteContext hook.
Type: SQLiteStorage
Alias for AsyncStorage, given the storage not only offers asynchronous methods.
Hooks
A global hook for accessing the SQLite database across components.
This hook should only be used within a <SQLiteProvider> component.
SQLiteDatabaseExample
export default function App() { return ( <SQLiteProvider databaseName="test.db"> <Main /> </SQLiteProvider> ); } export function Main() { const db = useSQLiteContext(); console.log('sqlite version', db.getFirstSync('SELECT sqlite_version()')); return <View /> }
Classes
A SQLite database.
SQLiteDatabase Properties
NativeDatabaseSQLiteOpenOptionsSQLiteDatabase Methods
Close the database.
Promise<void>Create a new session for the database.
Note: Running heavy tasks with this function can block the JavaScript thread and affect performance.
SQLiteSessionExecute all SQL queries in the supplied string.
Note: The queries are not escaped for you! Be careful when constructing your queries.
Promise<void>Execute all SQL queries in the supplied string.
Note: The queries are not escaped for you! Be careful when constructing your queries.
Note: Running heavy tasks with this function can block the JavaScript thread and affect performance.
voidA convenience wrapper around SQLiteDatabase.prepareAsync(), SQLiteStatement.executeAsync(), SQLiteExecuteAsyncResult.getAllAsync(), and SQLiteStatement.finalizeAsync().
Promise<T[]>Example
// For unnamed parameters, you pass values in an array. db.getAllAsync('SELECT * FROM test WHERE intValue = ? AND name = ?', [1, 'Hello']); // For unnamed parameters, you pass values in variadic arguments. db.getAllAsync('SELECT * FROM test WHERE intValue = ? AND name = ?', 1, 'Hello'); // For named parameters, you should pass values in object. db.getAllAsync('SELECT * FROM test WHERE intValue = $intValue AND name = $name', { $intValue: 1, $name: 'Hello' });
A convenience wrapper around SQLiteDatabase.prepareSync(), SQLiteStatement.executeSync(), SQLiteExecuteSyncResult.getAllSync(), and SQLiteStatement.finalizeSync().
Note: Running heavy tasks with this function can block the JavaScript thread and affect performance.
T[]A convenience wrapper around SQLiteDatabase.prepareAsync(), SQLiteStatement.executeAsync(), SQLiteExecuteAsyncResult AsyncIterator, and SQLiteStatement.finalizeAsync().
AsyncIterableIterator<T>Rather than returning Promise, this function returns an AsyncIterableIterator. You can use for await...of to iterate over the rows from the SQLite query result.
A convenience wrapper around SQLiteDatabase.prepareSync(), SQLiteStatement.executeSync(), SQLiteExecuteSyncResult Iterator, and SQLiteStatement.finalizeSync().
Note: Running heavy tasks with this function can block the JavaScript thread and affect performance.
IterableIterator<T>This function returns an IterableIterator. You can use for...of to iterate over the rows from the SQLite query result.
A convenience wrapper around SQLiteDatabase.prepareAsync(), SQLiteStatement.executeAsync(), SQLiteExecuteAsyncResult.getFirstAsync(), and SQLiteStatement.finalizeAsync().
Promise<T | null>A convenience wrapper around SQLiteDatabase.prepareSync(), SQLiteStatement.executeSync(), SQLiteExecuteSyncResult.getFirstSync(), and SQLiteStatement.finalizeSync().
Note: Running heavy tasks with this function can block the JavaScript thread and affect performance.
T | nullAsynchronous call to return whether the database is currently in a transaction.
Promise<boolean>Synchronous call to return whether the database is currently in a transaction.
booleanLoad a SQLite extension.
Promise<void>Example
// Load `sqlite-vec` from `bundledExtensions`. You need to enable `withSQLiteVecExtension` to include `sqlite-vec`. const extension = SQLite.bundledExtensions['sqlite-vec']; await db.loadExtensionAsync(extension.libPath, extension.entryPoint); // You can also load a custom extension. await db.loadExtensionAsync('/path/to/extension');
Load a SQLite extension.
voidExample
// Load `sqlite-vec` from `bundledExtensions`. You need to enable `withSQLiteVecExtension` to include `sqlite-vec`. const extension = SQLite.bundledExtensions['sqlite-vec']; db.loadExtensionSync(extension.libPath, extension.entryPoint); // You can also load a custom extension. db.loadExtensionSync('/path/to/extension');
Create a prepared SQLite statement.
Note: Running heavy tasks with this function can block the JavaScript thread and affect performance.
SQLiteStatementA convenience wrapper around SQLiteDatabase.prepareAsync(), SQLiteStatement.executeAsync(), and SQLiteStatement.finalizeAsync().
Promise<SQLiteRunResult>A convenience wrapper around SQLiteDatabase.prepareSync(), SQLiteStatement.executeSync(), and SQLiteStatement.finalizeSync().
Note: Running heavy tasks with this function can block the JavaScript thread and affect performance.
SQLiteRunResultSerialize the database as Uint8Array.
Note: Running heavy tasks with this function can block the JavaScript thread and affect performance.
Uint8ArrayExecute SQL queries using tagged template literals (Bun-style API). Queries are automatically protected against SQL injection using prepared statements.
The query result is directly awaitable and returns an array of objects by default.
Use .values(), .first(), or .each() for different result formats.
SQLiteTaggedQuery<T>Example
// Direct await - returns array of objects const users = await sql<User>`SELECT * FROM users WHERE age > ${21}`; // Get first row only const user = await sql<User>`SELECT * FROM users WHERE id = ${userId}`.first(); // Get values as arrays const rows = await sql`SELECT name, age FROM users`.values(); // Returns: [["Alice", 30], ["Bob", 25]] // INSERT/UPDATE/DELETE - returns SQLiteRunResult const result = await sql`INSERT INTO users (name, age) VALUES (${name}, ${age})` as SQLiteRunResult; console.log('Inserted row:', result.lastInsertRowId); // Iteration for await (const user of db<User>`SELECT * FROM users`.each()) { console.log(user.name); } // Synchronous API const users = sql<User>`SELECT * FROM users WHERE age > ${21}`.allSync(); const user = sql<User>`SELECT * FROM users WHERE id = ${userId}`.firstSync();
Synchronize the local database with the remote libSQL server. This method is only available from libSQL integration.
Promise<void>Execute a transaction and automatically commit/rollback based on the task result.
The transaction may be exclusive.
As long as the transaction is converted into a write transaction,
the other async write queries will abort with database is locked error.
Note: This function is not supported on web.
Promise<void>Example
db.withExclusiveTransactionAsync(async (txn) => { await txn.execAsync('UPDATE test SET name = "aaa"'); });
Execute a transaction and automatically commit/rollback based on the task result.
Note: This transaction is not exclusive and can be interrupted by other async queries.
Promise<void>Example
db.withTransactionAsync(async () => { await db.execAsync('UPDATE test SET name = "aaa"'); // // We cannot control the order of async/await order, so order of execution is not guaranteed. // The following UPDATE query out of transaction may be executed here and break the expectation. // const result = await db.getFirstAsync<{ name: string }>('SELECT name FROM Users'); expect(result?.name).toBe('aaa'); }); db.execAsync('UPDATE test SET name = "bbb"');
If you worry about the order of execution, use withExclusiveTransactionAsync instead.
A class that represents an instance of the SQLite session extension.
See: Session Extension
SQLiteSession Methods
Apply a changeset synchronously.
Note: Running heavy tasks with this function can block the JavaScript thread and affect performance.
voidAttach a table to the session synchronously.
Note: Running heavy tasks with this function can block the JavaScript thread and affect performance.
voidClose the session synchronously.
Note: Running heavy tasks with this function can block the JavaScript thread and affect performance.
voidCreate a changeset synchronously.
Note: Running heavy tasks with this function can block the JavaScript thread and affect performance.
ChangesetCreate an inverted changeset asynchronously.
This is a shorthand for createChangesetAsync() + invertChangesetAsync().
Create an inverted changeset synchronously.
This is a shorthand for createChangesetSync() + invertChangesetSync().
Note: Running heavy tasks with this function can block the JavaScript thread and affect performance.
ChangesetEnable or disable the session synchronously.
Note: Running heavy tasks with this function can block the JavaScript thread and affect performance.
voidInvert a changeset synchronously.
Note: Running heavy tasks with this function can block the JavaScript thread and affect performance.
ChangesetA prepared statement returned by SQLiteDatabase.prepareAsync() or SQLiteDatabase.prepareSync() that can be binded with parameters and executed.
SQLiteStatement Methods
Run the prepared statement and return the SQLiteExecuteAsyncResult instance.
Promise<SQLiteExecuteAsyncResult<T>>Run the prepared statement and return the SQLiteExecuteSyncResult instance.
Note: Running heavy tasks with this function can block the JavaScript thread and affect performance.
SQLiteExecuteSyncResult<T>Finalize the prepared statement. This will call the sqlite3_finalize() C function under the hood.
Attempting to access a finalized statement will result in an error.
Note: While
expo-sqlitewill automatically finalize any orphaned prepared statements upon closing the database, it is considered best practice to manually finalize prepared statements as soon as they are no longer needed. This helps to prevent resource leaks. You can use thetry...finallystatement to ensure that prepared statements are finalized even if an error occurs.
Promise<void>Finalize the prepared statement. This will call the sqlite3_finalize() C function under the hood.
Attempting to access a finalized statement will result in an error.
Note: While
expo-sqlitewill automatically finalize any orphaned prepared statements upon closing the database, it is considered best practice to manually finalize prepared statements as soon as they are no longer needed. This helps to prevent resource leaks. You can use thetry...finallystatement to ensure that prepared statements are finalized even if an error occurs.
voidGet the column names of the prepared statement.
Promise<string[]>Key-value store backed by SQLite. This class accepts a databaseName parameter in its constructor, which is the name of the database file to use for the storage.
SQLiteStorage Methods
Alias for clearAsync() method.
Promise<void>Clears all key-value pairs from the storage asynchronously.
Promise<boolean>Clears all key-value pairs from the storage synchronously.
booleanAlias for closeAsync() method.
Promise<void>Closes the database connection asynchronously.
Promise<void>Alias for getAllKeysAsync() method.
Promise<string[]>Retrieves all keys stored in the storage asynchronously.
Promise<string[]>Retrieves all keys stored in the storage synchronously.
string[]Retrieves the value associated with the given key synchronously.
string | nullRetrieves the key at the given index synchronously.
string | nullRetrieves the number of key-value pairs stored in the storage asynchronously.
Promise<number>Retrieves the number of key-value pairs stored in the storage synchronously.
numberMerges the given value with the existing value for the given key asynchronously. If the existing value is a JSON object, performs a deep merge.
Promise<void>Merges multiple key-value pairs asynchronously. If existing values are JSON objects, performs a deep merge.
Promise<void>Removes the value associated with the given key synchronously.
booleanSets the value for the given key asynchronously. If a function is provided, it computes the new value based on the previous value.
Promise<void>Type: Class implements PromiseLike<SQLiteTaggedQueryResult<T>>
A SQL query with tagged template literals API that can be awaited directly (returns array of objects by default), or transformed using .values() or .first() methods.
This API is inspired by Bun's SQL interface:
Example
// Default: returns array of objects const users = await sql`SELECT * FROM users WHERE age > ${21}`; // Get values as arrays const values = await sql`SELECT name, age FROM users`.values(); // Returns: [["Alice", 30], ["Bob", 25]] // Get first row only const user = await sql`SELECT * FROM users WHERE id = ${1}`.first(); // With type parameter const users = await sql<User>`SELECT * FROM users`; // Mutable queries return SQLiteRunResult const result = await sql`INSERT INTO users (name) VALUES (${"Alice"})` as SQLiteRunResult; console.log(result.lastInsertRowId, result.changes); // Synchronous API const users = sql<User>`SELECT * FROM users WHERE age > ${21}`.allSync(); const user = sql<User>`SELECT * FROM users WHERE id = ${userId}`.firstSync();
SQLiteTaggedQuery Methods
Execute a query synchronously that returns rows or metadata based on query type.
Note: Running heavy tasks with this function can block the JavaScript thread and affect performance.
SQLiteTaggedQueryResult<T>Execute the query and return an async iterator over the rows.
AsyncIterableIterator<T>Example
for await (const user of sql`SELECT * FROM users`.each()) { console.log(user.name); }
Execute the query synchronously and return an iterator.
Note: Running heavy tasks with this function can block the JavaScript thread and affect performance.
IterableIterator<T>Execute the query and return the first row only. Returns null if no rows match.
Promise<T | null>Example
const user = await sql`SELECT * FROM users WHERE id = ${1}`.first();
Execute the query synchronously and return the first row.
Note: Running heavy tasks with this function can block the JavaScript thread and affect performance.
T | nullExecute the query and return rows as arrays of values (Bun-style). Each row is an array where values are in column order.
Promise<any[][]>Example
const rows = await sql`SELECT name, age FROM users`.values(); // Returns: [["Alice", 30], ["Bob", 25]]
Props
SQLiteProviderAssetSourceImport a bundled database file from the specified asset module.
Example
assetSource={{ assetId: require('./assets/db.db') }}
string • Default: defaultDatabaseDirectoryThe directory where the database file is located.
(error: Error) => void • Default: rethrow the errorHandle errors from SQLiteProvider.
(db: SQLiteDatabase) => Promise<void>A custom initialization handler to run before rendering the children. You can use this to run database migrations or other setup tasks.
boolean • Default: falseEnable React.Suspense integration.
Example
export default function App() { return ( <Suspense fallback={<Text>Loading...</Text>}> <SQLiteProvider databaseName="test.db" useSuspense={true}> <Main /> </SQLiteProvider> </Suspense> ); }
Methods
Backup a database to another database.
Note: Running heavy tasks with this function can block the JavaScript thread and affect performance.
voidCompares two objects deeply for equality.
booleanDelete a database file.
Note: Running heavy tasks with this function can block the JavaScript thread and affect performance.
voidGiven a Uint8Array data and deserialize to memory database.
Note: Running heavy tasks with this function can block the JavaScript thread and affect performance.
SQLiteDatabaseOpen a database.
Note: Running heavy tasks with this function can block the JavaScript thread and affect performance.
SQLiteDatabaseEvent subscriptions
Add a listener for database changes.
Note: to enable this feature, you must set
enableChangeListenertotruewhen opening the database.
EventSubscriptionA Subscription object that you can call remove() on when you would like to unsubscribe the listener.
Interfaces
Extends: AsyncIterableIterator<T>
A result returned by SQLiteStatement.executeAsync().
Example
The result includes the lastInsertRowId and changes properties. You can get the information from the write operations.
const statement = await db.prepareAsync('INSERT INTO test (value) VALUES (?)'); try { const result = await statement.executeAsync(101); console.log('lastInsertRowId:', result.lastInsertRowId); console.log('changes:', result.changes); } finally { await statement.finalizeAsync(); }
Example
The result implements the AsyncIterator interface, so you can use it in for await...of loops.
const statement = await db.prepareAsync('SELECT value FROM test WHERE value > ?'); try { const result = await statement.executeAsync<{ value: number }>(100); for await (const row of result) { console.log('row value:', row.value); } } finally { await statement.finalizeAsync(); }
Example
If your write operations also return values, you can mix all of them together.
const statement = await db.prepareAsync('INSERT INTO test (name, value) VALUES (?, ?) RETURNING name'); try { const result = await statement.executeAsync<{ name: string }>('John Doe', 101); console.log('lastInsertRowId:', result.lastInsertRowId); console.log('changes:', result.changes); for await (const row of result) { console.log('name:', row.name); } } finally { await statement.finalizeAsync(); }
SQLiteExecuteAsyncResult Methods
Get all rows of the result set. This requires the SQLite cursor to be in its initial state. If you have already retrieved rows from the result set, you need to reset the cursor first by calling resetAsync(). Otherwise, an error will be thrown.
Promise<T[]>Get the first row of the result set. This requires the SQLite cursor to be in its initial state. If you have already retrieved rows from the result set, you need to reset the cursor first by calling resetAsync(). Otherwise, an error will be thrown.
Promise<T | null>Reset the prepared statement cursor. This will call the sqlite3_reset() C function under the hood.
Promise<void>Extends: IterableIterator<T>
A result returned by SQLiteStatement.executeSync().
Note: Running heavy tasks with this function can block the JavaScript thread and affect performance.
Example
The result includes the lastInsertRowId and changes properties. You can get the information from the write operations.
const statement = db.prepareSync('INSERT INTO test (value) VALUES (?)'); try { const result = statement.executeSync(101); console.log('lastInsertRowId:', result.lastInsertRowId); console.log('changes:', result.changes); } finally { statement.finalizeSync(); }
Example
The result implements the Iterator interface, so you can use it in for...of loops.
const statement = db.prepareSync('SELECT value FROM test WHERE value > ?'); try { const result = statement.executeSync<{ value: number }>(100); for (const row of result) { console.log('row value:', row.value); } } finally { statement.finalizeSync(); }
Example
If your write operations also return values, you can mix all of them together.
const statement = db.prepareSync('INSERT INTO test (name, value) VALUES (?, ?) RETURNING name'); try { const result = statement.executeSync<{ name: string }>('John Doe', 101); console.log('lastInsertRowId:', result.lastInsertRowId); console.log('changes:', result.changes); for (const row of result) { console.log('name:', row.name); } } finally { statement.finalizeSync(); }
SQLiteExecuteSyncResult Methods
Get all rows of the result set. This requires the SQLite cursor to be in its initial state. If you have already retrieved rows from the result set, you need to reset the cursor first by calling resetSync(). Otherwise, an error will be thrown.
T[]Get the first row of the result set. This requires the SQLite cursor to be in its initial state. If you have already retrieved rows from the result set, you need to reset the cursor first by calling resetSync(). Otherwise, an error will be thrown.
T | nullReset the prepared statement cursor. This will call the sqlite3_reset() C function under the hood.
voidA result returned by SQLiteDatabase.runAsync or SQLiteDatabase.runSync.
Types
The event payload for the listener of addDatabaseChangeListener
Literal type: Record
Acceptable values are: Record<string, SQLiteBindValue>
Literal type: union
Bind parameters to the prepared statement. You can either pass the parameters in the following forms:
Example
A single array for unnamed parameters.
const statement = await db.prepareAsync('SELECT * FROM test WHERE value = ? AND intValue = ?'); const result = await statement.executeAsync(['test1', 789]); const firstRow = await result.getFirstAsync();
Example
Variadic arguments for unnamed parameters.
const statement = await db.prepareAsync('SELECT * FROM test WHERE value = ? AND intValue = ?'); const result = await statement.executeAsync('test1', 789); const firstRow = await result.getFirstAsync();
Example
A single object for named parameters
We support multiple named parameter forms such as :VVV, @VVV, and $VVV. We recommend using $VVV because JavaScript allows using $ in identifiers without escaping.
const statement = await db.prepareAsync('SELECT * FROM test WHERE value = $value AND intValue = $intValue'); const result = await statement.executeAsync({ $value: 'test1', $intValue: 789 }); const firstRow = await result.getFirstAsync();
Acceptable values are: string | number | null | boolean | SQLiteBindBlobValue
Update function for the setItemAsync() or setItemSync() method. It computes the new value based on the previous value. The function returns the new value to set for the key.
string
Type: SQLiteBindValue[]