Database lifecycle

Use open({ name }) to open an existing database or create a new one. Keep the returned connection for queries, then call close() when done. See databases and connections for the difference between the file and its open handles.

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. See file lifetimes for WAL companion files.

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

A JavaScript runtime can be destroyed while the app process stays alive. Nitro SQLite closes that runtime's connections and rolls back unfinished transactions. A replacement runtime can reopen the same databases without restarting the process; the older runtime's cleanup leaves the new connections open.

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.