Global and native API

The NitroSQLite export provides JavaScript helpers and a .native property holding the Nitro hybrid object. open(options) returns the preferred connection API. The global helpers below retain a database-name argument for code that manages names itself.

JavaScript helpers on NitroSQLite

The generic Row must extend QueryResultRow. The global execute helpers default it to never, so supply a type argument when you want typed rows. isExclusive defaults to false; pass true to begin with BEGIN EXCLUSIVE TRANSACTION. The connection's db.transaction() method has no isExclusive argument.

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

const db = NitroSQLite.open({ name: 'app.sqlite' })
const result = await NitroSQLite.executeAsync<{ id: number }>(
  'app.sqlite',
  'SELECT id FROM notes',
)
console.log(result.rows.length)
db.close()

The global execute helpers join the JavaScript queue when that name was opened through open(). If no JavaScript connection exists, they call the native method directly, which still requires an open native database handle. Global batch and transaction helpers require a connection opened through open() because they use its JavaScript queue. A synchronous call conflicts with active queued work and throws NitroSQLiteError; async calls join the queue. Inside a transaction callback, use the supplied tx instead of another global or connection method for the same database.

Use NitroSQLite.native for raw native methods. The NitroSQLite object spreads the hybrid instance, but its methods are inherited from the instance's prototype and should not be assumed to appear on the top-level object.

NitroSQLite.native

NitroSQLite.native is the underlying Nitro hybrid object. Every method takes the database name explicitly. It does not add the connection's JavaScript rows container or normalize errors to NitroSQLiteError.

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

NitroSQLite.native.open('raw.sqlite')
try {
  const result = NitroSQLite.native.execute('raw.sqlite', 'SELECT 1 AS value')
  console.log(result.results[0]?.value)
} finally {
  NitroSQLite.native.close('raw.sqlite')
}

The native query result has results: Record<string, SQLiteValue>[], rowsAffected: number, optional insertId: number, and optional metadata keyed by result column name. Each metadata value has name: string, type: ColumnType, and index: number. The native result and column metadata declarations live in the Nitro specs and are not named exports from the package root. The JavaScript QueryResult<Row> adds rows to this result; see types and errors.

The raw object and query result inherit Nitro's HybridObject members: name: string, toString(): string, equals(other): boolean, and dispose(): void. dispose() makes that hybrid object unusable; it is not a database close() call. Normal garbage collection manages these objects, so do not dispose the shared NitroSQLite.native instance as part of ordinary database cleanup.

Native calls bypass the JavaScript queue. Do not mix them with an active connection transaction for the same database: a native statement may run inside that transaction without being part of its callback's intended sequence. If you build SQLite with SQLITE_THREADSAFE=0, separate database handles also need process-wide serialization. See iOS and Android configuration.