Connections

A SQLite connection is an open handle to a database file. Queries on that connection share its transaction state and can refer to tables in the file. Nitro SQLite's open() gives you a connection to keep and close when you finish using it.

Open a database

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

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

open(options: NitroSQLiteConnectionOptions): NitroSQLiteConnection opens or creates the file. name is required. By convention, location is a relative directory under the platform's database root, such as open({ name: 'app.sqlite', location: 'databases' }). It is not a path to the database file. The library creates the directory if needed, but does not validate path segments in name or location. Use application-controlled values rather than arbitrary user input. See iOS storage and Android storage for the default roots.

Only one connection with a given name can be open at a time. Keep the returned connection and close it before opening the same name again. Opening a different name creates a separate connection.

Close and delete

db.close(): void closes the native handle. db.delete(): void removes the database file using the name and location passed to open(). Deleting an open database also closes its connection. Neither operation returns a promise. They throw if the connection's queue is busy; wait for pending async work before calling them. Do not reuse the connection after closing or deleting it.

const db = open({ name: 'scratch.sqlite' })
await db.executeAsync('CREATE TABLE IF NOT EXISTS entries (id INTEGER)')
db.close()
db.delete()

Opening the same name again creates a new database file. On iOS, when a database is being moved from Documents to Application Support, deletion also cleans up copies and SQLite sidecar files from both locations.

Attach and detach

SQLite can attach another database file to a connection, making its tables available through an alias such as archive.notes. Detaching removes that file from the connection; it does not delete the file.

db.attach(dbNameToAttach, alias, location?): void attaches another database file to the open connection. The optional location follows the same relative-directory convention as open(). db.detach(alias): void removes the attachment from that connection. The native implementation inserts the attached file path and alias into SQL, so use application-controlled database names, locations, and aliases.

db.attach('archive.sqlite', 'archive')
const { rows } = db.execute('SELECT id FROM archive.notes')
db.detach('archive')

Load a SQL file

db.loadFile(path): FileLoadResult and db.loadFileAsync(path): Promise<FileLoadResult> read a file at a native filesystem path and execute its commands inside an exclusive transaction. The parser treats each non-empty line as a complete SQL command, so statements spread over several lines are not supported.

const result = await db.loadFileAsync('/absolute/path/to/import.sql')
console.log(result.commands, result.rowsAffected)

FileLoadResult has optional commands and rowsAffected numbers. Use the async method for a large import so the work runs off the JavaScript thread. The path must refer to a file the app can access on the device; a bundled asset name alone is not a filesystem path.

See Queries and results for SQL execution and Transactions and batches for grouping statements.