API Reference / react-native-nitro-sqlite / NitroSQLite

Variable: NitroSQLite

TypeScript

Source files: TypeScript

const NitroSQLite: object

Database entry point. Prefer open for a managed connection. native exposes the Nitro object directly and bypasses the JavaScript queue.

Type Declaration

execute

execute: <Row>(dbName, query, params?) => QueryResult<Row>

Execute one SQL statement synchronously by database name. Uses the managed queue when the database has an open managed connection.

Type Parameters

Row

Row extends QueryResultRow = never

Parameters

dbName

string

Name of an open native database.

query

string

SQL statement with optional positional placeholders.

params?

SQLiteQueryParams

Values bound to the placeholders.

Returns

QueryResult<Row>

The query result with typed rows.

executeAsync

executeAsync: <Row>(dbName, query, params?) => Promise<QueryResult<Row>>

Execute one SQL statement asynchronously by database name. Uses the managed queue when the database has an open managed connection.

Type Parameters

Row

Row extends QueryResultRow = never

Parameters

dbName

string

Name of an open native database.

query

string

SQL statement with optional positional placeholders.

params?

SQLiteQueryParams

Values bound to the placeholders.

Returns

Promise<QueryResult<Row>>

A promise of the query result with typed rows.

executeBatch

executeBatch: (dbName, commands, queueKey) => BatchQueryResult

Execute a batch synchronously in one exclusive transaction. Requires an open managed connection; throws if it is busy or the batch is empty.

Parameters

dbName

string

Name of the open database.

commands

BatchQueryCommand[]

SQL commands and optional parameter sets.

queueKey?

DatabaseQueueKey = dbName

Returns

BatchQueryResult

Total affected row count.

executeBatchAsync

executeBatchAsync: (dbName, commands, queueKey) => Promise<BatchQueryResult>

Queue a batch in one exclusive transaction. Requires an open managed connection; a failed command rolls back the batch.

Parameters

dbName

string

Name of the open database.

commands

BatchQueryCommand[]

SQL commands and optional parameter sets.

queueKey?

DatabaseQueueKey = dbName

Returns

Promise<BatchQueryResult>

A promise of the total affected row count.

native

native: NitroSQLiteNative = HybridNitroSQLite

open

open: (options) => NitroSQLiteConnection

Open a database and return a managed connection. The default connection is addressed by its name, and opening it twice throws. Set connection to 'independent' to open another native handle to the same file. Async calls on each connection run in call order.

Parameters

options

NitroSQLiteConnectionOptions

Database name, optional directory, connection mode, and read-only setting.

Returns

NitroSQLiteConnection

A connection bound to the opened native handle.

prepare

prepare: (dbName, query, queueKey) => PreparedStatement

Prepare one SQL statement on an open managed connection for repeated execution. Synchronous preparation throws if the connection is busy. Finalize the returned statement before closing the connection.

Parameters

dbName

string

Database name or independent connection ID.

query

string

SQL statement with optional positional placeholders.

queueKey?

DatabaseQueueKey = dbName

Internal managed queue key; omit when using the public API.

Returns

PreparedStatement

A statement whose executions use the same connection queue.

transaction

transaction: <Result>(dbName, transactionCallback, isExclusive, queueKey) => Promise<Result>

Queue a transaction for an open managed connection. Use only the supplied tx for work on this database inside the callback. A successful callback commits unless it explicitly committed or rolled back; a thrown error rolls back unless the transaction was already finalized.

Type Parameters

Result

Result = void

Parameters

dbName

string

Name of the open database.

transactionCallback

(tx) => Promise<Result>

Async callback receiving the transaction handle.

isExclusive?

boolean = false

Begin an exclusive transaction when true.

queueKey?

DatabaseQueueKey = dbName

Returns

Promise<Result>

The callback's result after the transaction finishes.

attach()

attach(mainDbName, dbNameToAttach, alias, location?): void

Attach a database file to an open main database under an SQL schema alias.

Parameters

mainDbName

string

Name of the open main database.

dbNameToAttach

string

File name of the database to attach.

alias

string

SQL schema name for the attached database.

location?

string

Directory relative to the platform database directory.

Returns

void

close()

close(dbName): void

Close a default connection by name or an independent connection by ID.

Parameters

dbName

string

Returns

void

detach()

detach(mainDbName, alias): void

Detach an attached database by its alias.

Parameters

mainDbName

string

Name of the open main database.

alias

string

SQL schema name used when attaching.

Returns

void

drop()

drop(dbName, location?, connectionId?): void

Delete a database and close the indicated connection if open. Deletion fails while another connection or attachment uses the database file.

Parameters

dbName

string

Database file name.

location?

string

Directory relative to the platform database directory.

connectionId?

string

Optional ID of the independent connection to close.

Returns

void

isConnectionOpen()

isConnectionOpen(connectionId): boolean

Check whether a native connection ID is still open.

Parameters

connectionId

string

ID returned by openConnection.

Returns

boolean

loadFile()

loadFile(dbName, location): FileLoadResult

Import a SQL file in one exclusive transaction on the calling thread. Each non-empty line is treated as one statement.

Parameters

dbName

string

Name of an open database.

location

string

Path to the SQL file.

Returns

FileLoadResult

Number of executed commands and affected rows.

loadFileAsync()

loadFileAsync(dbName, location): Promise<FileLoadResult>

Import a SQL file on a background thread.

Parameters

dbName

string

Name of an open database.

location

string

Path to the SQL file.

Returns

Promise<FileLoadResult>

A promise of the command and affected row counts.

openConnection()

openConnection(dbName, location?, readOnly?): string

Open a separate native handle, even when the database file is already open. Independent connections require a thread-safe SQLite build.

Parameters

dbName

string

Database file name.

location?

string

Directory relative to the platform database directory.

readOnly?

boolean

Open an existing database without write access.

Returns

string

An opaque ID to pass to native connection operations.