Database lifecycle

A SQLite database usually lives in a file. Your app opens a connection to read or change that file, then closes the connection when it is done. Closing a connection leaves the data on disk; deleting the file removes the database.

In NitroSQLite, open({ name }) opens an existing SQLite file or creates a new one. A database name can have only one active open() connection in the JavaScript session. Close it before opening that name again.

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()

close() releases the connection and its queue. It keeps the file. delete() removes the database file and closes an open connection for that name. You can call delete() on the connection after close(), using its remembered 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. 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

By default, the root is the app Documents directory on iOS and the app files directory on Android. Use the optional location as a relative subdirectory under that root, not as an absolute file path:

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

The native code joins the root, location, and name without checking for .. path segments. Use application-controlled names and locations, not arbitrary user input.

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 up it.

iOS can use Application Support or an app group instead of Documents; see iOS configuration. Android uses its app files directory; see Android configuration. The generated NitroSQLiteConnection reference lists the lifecycle methods.