iOS configuration

Native build settings take effect after installing Pods and rebuilding the app. The database directory settings are read from the app's Info.plist when the native module loads.

Database location

By default, the database root is the app's Documents directory. open({ name: 'app.sqlite', location: 'databases' }) puts the file in a databases directory below that root. Use location as a relative directory by convention; the library does not validate path segments in the name or location. See database lifecycle for the trust requirement.

To use Library/Application Support as the root, add this to the app's Info.plist:

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

The supported values are Documents and ApplicationSupport. Application Support keeps the database outside the Documents directory shown through Files app sharing. When you switch from Documents to Application Support, the library moves an existing database, including its SQLite sidecar files, when that database is next opened or attached. Switching the setting back does not move it to Documents. An app group setting takes precedence over this setting.

App groups

Enable the App Groups capability for the app and any extension that shares the database. Set the same group identifier in the app's Info.plist:

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

The library uses the group's container as its database root and throws during initialization if the identifier has no valid container. An optional location passed to open() follows the same relative-directory convention under that root.

Bundled or system SQLite

The pod compiles the bundled SQLite source by default. To link iOS's system SQLite instead, set NITRO_SQLITE_USE_PHONE_VERSION=1 for Pod installation:

NITRO_SQLITE_USE_PHONE_VERSION=1 npx pod-install

The bundled source is where the pod's compile settings apply. Changing the pod's SQLITE_THREADSAFE or performance flags cannot change how the system library was built.

RTree support

R*Tree indexes find bounding boxes that overlap a spatial or time range. The bundled SQLite build includes rtree and rtree_i32 by default on iOS, macOS, and visionOS. See query spatial ranges for SQL examples and limitations.

To omit R*Tree from the bundled build, set this boolean in your app's package.json, install Pods again, and rebuild:

{
  "nitroSQLite": {
    "enableRTree": false
  }
}

enableRTree defaults to true independently of performanceMode. A non-boolean value fails Pod installation. Disabling it omits SQLITE_ENABLE_RTREE; defining that macro as 0 still enables SQLite's module. This setting cannot change system SQLite's capabilities when you use NITRO_SQLITE_USE_PHONE_VERSION=1.

Thread safety and performance mode

The bundled SQLite build defaults to SQLITE_THREADSAFE=1 and enables the project's performance compile flags. Set either option in the app's package.json:

{
  "nitroSQLite": {
    "threadSafe": true,
    "performanceMode": true
  }
}

Both keys require booleans. For one Pod installation, NITRO_SQLITE_THREADSAFE and NITRO_SQLITE_PERFORMANCE_MODE override the package values. Each accepts true, false, 1, or 0.

threadSafe: false compiles SQLite with SQLITE_THREADSAFE=0 and removes its mutex code. Nitro SQLite rejects independent connections in that build. Separate database handles can still run concurrently, so an app using this setting must serialize SQLite calls across the process. performanceMode: false removes the pod's extra SQLite compile flags independently of thread safety. Those flags include SQLITE_DQS=0, SQLITE_DEFAULT_MEMSTATUS=0, SQLITE_DEFAULT_WAL_SYNCHRONOUS=1, and several SQLITE_OMIT_* options; this switch does not set a runtime SQLite pragma.

Additional compile flags

SQLite has optional features selected when its source is compiled. For example, FTS5 adds full-text search tables that can search words in stored text.

To compile optional SQLite features into the bundled source, add the definition to the RNNitroSQLite pod target. For example, in an existing post_install block in ios/Podfile:

installer.pods_project.targets.each do |target|
  next unless target.name == 'RNNitroSQLite'

  target.build_configurations.each do |config|
    definitions = Array(config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] || '$(inherited)')
    config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] = definitions + ['SQLITE_ENABLE_FTS5=1']
  end
end

To use the licensed SQLite Encryption Extension, follow encrypt a database for the matching source files, symbol prefix, and SQLITE_ENABLE_SEE flag.

Vector search

Install react-native-nitro-sqlite-vec, then set NITRO_SQLITE_VEC=1 when installing Pods:

NITRO_SQLITE_VEC=1 npx pod-install

The flag is read by both the core and companion podspecs. Rebuild the app, then use isVecAvailable(db) to check the linked extension. See the vector search guide.