Sync and async

SQLite work can take time, especially when a query reads many rows or a transaction writes many of them. A synchronous JavaScript call waits for that work to finish before the app can continue on the same thread. An asynchronous call lets JavaScript continue while the database work runs elsewhere.

NitroSQLite's connection offers synchronous execute, executeBatch, and loadFile methods, with matching Async methods. Synchronous calls return before JavaScript continues, so a slow query blocks that JavaScript call. Asynchronous calls run the database work off the JavaScript thread and return a promise.

import { open } from 'react-native-nitro-sqlite'

const db = open({ name: 'app.sqlite' })

const smallResult = db.execute('SELECT 1 AS value')
const largerResult = await db.executeAsync('SELECT * FROM notes')

console.log(smallResult.results, largerResult.results)

Use synchronous calls when immediate results are useful and the work is small. Prefer async calls for queries that may scan many rows, batches, or file imports. Performance guidance covers other ways to keep work bounded.

The open() connection queues async operations for the same database name in submission order. A synchronous operation, close(), or delete() throws a busy error if that queue has pending or active work. Await async work before calling a synchronous method on the same connection:

await db.executeAsync('INSERT INTO notes (body) VALUES (?)', ['Queued write'])
const total = db.execute<{ total: number }>(
  'SELECT COUNT(*) AS total FROM notes',
).rows.item(0)?.total
console.log(total)

db.transaction() also occupies the queue until its callback finishes. Inside that callback, use the provided tx methods. Awaiting db.executeAsync() or another queued operation for the same database inside it leaves both operations waiting for each other. See transactions.

The low-level native API does not use this JavaScript queue. If you use it alongside an open() connection, coordinate access yourself.