iOS

See Configuration for shared package.json settings.

Database location

Databases use Documents by default. To use Library/Application Support, add this to your app's Info.plist:

<key>RNNitroSQLite_DatabaseLocation</key>
<string>ApplicationSupport</string>

Existing databases and their sidecar files move when next opened or attached. Switching back to Documents does not move them back. See file locations for the location option.

App groups

Enable the App Groups capability for your app and extension, then add the group identifier to Info.plist:

<key>RNNitroSQLite_AppGroup</key>
<string>group.example.shared</string>

The group container takes precedence over the database location setting. An invalid or inaccessible container causes initialization to throw.

Build settings

Swift Package Manager reads the SQLite build settings when it resolves Nitro SQLite's package, and it caches the result. Changed environment variables are picked up automatically, but changes to package.json settings are not. After changing them, delete ~/Library/Caches/org.swift.swiftpm/manifests and rebuild.

Bundled or system SQLite

To use system SQLite instead of the bundled library, set NITRO_SQLITE_USE_PHONE_VERSION=1 in the environment of the command that builds the app, for example NITRO_SQLITE_USE_PHONE_VERSION=1 npx react-native run-ios. Builds started from the Xcode app do not read your shell environment. The shared build settings cannot change system SQLite's capabilities.

Thread safety and performance mode

When set in the environment of the command that builds the app, NITRO_SQLITE_THREADSAFE and NITRO_SQLITE_PERFORMANCE_MODE override the corresponding package.json settings. Both accept true, false, 1, or 0.

Additional compile flags

Use iosSqliteFlags in your app's package.json for additional SQLite features or to override individual build defaults. For example, to enable FTS5 full-text search:

{
  "nitroSQLite": {
    "iosSqliteFlags": "-DSQLITE_ENABLE_FTS5=1"
  }
}

The value accepts only -DNAME and -DNAME=VALUE definitions, separated by spaces. Custom definitions take precedence over the defaults from your other package.json settings.

Vector search

Install react-native-nitro-sqlite-vec, then refresh the Swift packages from your app directory:

npx react-native spm

Rebuild and follow the vector search guide. For SEE build settings, see encryption.