Database lifecycle

Use open({ name }) to open an existing database or create a new one. It returns a connection for queries. A SQLite database usually lives in a file; the connection is your app's open handle to that file. close() releases the handle, while delete() removes the data.

Open and close a connection

Keep the returned connection while you need to query the database. Only one default connection can be open for a database name at a time. Close it before opening another default connection, or use connection: 'independent' for a separate connection to the same file. See multiple connections.

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

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

// Finish all pending async work before closing.
await db.executeAsync(
  'CREATE TABLE IF NOT EXISTS settings (key TEXT PRIMARY KEY, value TEXT)',
)
db.close()

Delete a database file

delete() removes the database file and closes that connection if it is open. Deletion fails while another connection still has the file open. You can call delete() after close(); the connection remembers its name and location. Do not use a closed or deleted connection for more queries.

const temporary = open({ name: 'temporary.sqlite' })
temporary.close()
temporary.delete()

Both methods are synchronous. They fail if an operation on that connection is queued or running. Await outstanding promises first, and finalize prepared statements before closing. delete() also fails if the named file does not exist.

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.

File location and prepopulated databases

Pass location to open() to select a subdirectory under the platform's database root. Use a relative directory, not an absolute file path:

const db = open({ name: 'catalog.sqlite', location: 'databases' })

Only pass database names and locations you control. The library does not validate path segments such as ...

To open a prepopulated database, copy the SQLite file into the intended app directory before calling open(). Use the same name and location when you open it. A missing file creates a new, empty database, so verify the copy if your schema must already exist. If you use WAL mode, account for the database's companion files when moving or backing it up.

The platform pages describe the database roots and storage settings for iOS, Android, and macOS. The generated NitroSQLiteConnection reference lists the lifecycle methods.

Runtime teardown

SQLite connections are native resources. A JavaScript runtime can be destroyed while the app process stays alive, such as when an app switches between React Native hosts. Closing a connection preserves committed data on disk and rolls back any unfinished transaction.

When the runtime's native NitroSQLite instance is destroyed, it closes its connections. A replacement runtime can open the same database names without restarting the process. An older runtime's cleanup does not close connections opened by a newer one.

Operations and prepared statements from the old connection fail after it closes. They do not use a replacement connection with the same name. Await pending work and finalize prepared statements before an intentional runtime teardown when your app controls that transition.