Android configuration

Android builds Nitro SQLite's bundled SQLite source into the native library. Its compile options come from the app's root Gradle properties and require a native rebuild.

Database location

The default database root is the app's internal filesDir. open({ name: 'app.sqlite', location: 'databases' }) places the database in a databases directory below that root. The library creates the directory if needed. 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 open an existing file from elsewhere, copy it to the intended app directory first.

SQLite 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.

Set nitroSqliteFlags in the app's android/gradle.properties to pass definitions into the native CMake build. For example, to enable FTS5:

nitroSqliteFlags="-DSQLITE_ENABLE_FTS5=1"

These are SQLite compile definitions, so they affect the bundled source when the native library is rebuilt. The Apple NITRO_SQLITE_USE_PHONE_VERSION pod switch does not apply to Android.

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

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. 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 and rebuild the native app:

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

enableRTree defaults to true independently of performanceMode. A non-boolean value fails Gradle configuration. Disabling it omits the default SQLITE_ENABLE_RTREE definition. Do not add -DSQLITE_ENABLE_RTREE=0 to nitroSqliteFlags to disable it: SQLite checks whether the macro is defined, so that value still enables the module. Custom compile definitions can enable the module even when the package setting is false.

Threading

The native library opens each database with SQLITE_OPEN_FULLMUTEX and serializes calls on each handle. The JavaScript connection helper coordinates work per managed connection and rejects conflicting synchronous work. nitroSqliteFlags can change compile-time SQLite behavior, including SQLITE_THREADSAFE. Nitro SQLite rejects independent connections when SQLite was built with SQLITE_THREADSAFE=0; other database handles can still run concurrently, so an app disabling mutexes must serialize SQLite calls across the process.

The app's nitroSQLite.threadSafe and nitroSQLite.performanceMode settings also configure Android's SQLite defaults. Custom nitroSqliteFlags override individual defaults. The native build additionally applies its CMake compiler options, including -O2.

Vector search

Install react-native-nitro-sqlite-vec and enable it in the app's android/gradle.properties:

nitroSqliteVec=true

The core library then compiles sqlite-vec with the bundled SQLite source and registers it before opening a database. Rebuild the app after changing the property. See the vector search guide for the helper API.