docs: consolidate shared SQLite configuration

docs/content/docs/configuration/android.mdx

@@ -1,77 +1,49 @@
 ---
-title: Android configuration
-description: Database storage and supported SQLite compile options on Android.
+title: Android
+description: Database storage, batch atomic writes, and Gradle overrides.
 ---
 
-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.
+<span id="threading" />
+<span id="rtree-support" />
 
-## 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](/docs/guides/database-lifecycle) for the trust requirement. To open an existing file from elsewhere, copy it to the intended app directory first.
-
-## SQLite compile flags
+See [Configuration](/docs/configuration) for shared `package.json` settings.
 
-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:
-
-```properties
-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](/docs/guides/encryption) for the matching source files, symbol prefix, and `SQLITE_ENABLE_SEE` flag.
+## Database location
 
-## RTree support
+Databases use the app's internal `filesDir`. See [file locations](/docs/guides/database-lifecycle#file-location-and-prepopulated-databases) for the `location` option and prepopulated databases.
 
-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](/docs/concepts/queries-and-indexes#query-spatial-ranges) for SQL examples and limitations.
+## Commit I/O
 
-To omit R\*Tree from the bundled build, set this boolean in your app's `package.json` and rebuild the native app:
+To disable batch atomic writes, set this in your app's `package.json`:
 
 ```json
 {
   "nitroSQLite": {
-    "enableRTree": false
+    "enableBatchAtomicWrite": 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`.
+`enableBatchAtomicWrite` defaults to `true` on Android, independently of `performanceMode`. It uses atomic filesystem commits when supported and otherwise falls back to SQLite's journal. Rebuild after changing it.
 
-## Commit I/O
-
-SQLite makes a committed transaction durable by writing it to storage and asking the operating system to flush the written data. In the default rollback journal mode, a commit first copies the original pages into a journal file and flushes it, then writes the new pages to the database file and flushes again, and finally removes the journal. For small writes, these flushes take most of a commit's time.
-
-Android builds compile SQLite with two I/O options that Android's own platform SQLite also uses. Neither changes `PRAGMA synchronous`, and a commit is as durable as before:
-
-- `HAVE_FDATASYNC=1` flushes with `fdatasync()` instead of `fsync()`. On Linux, `fdatasync()` still flushes the metadata needed to read the data back, such as the file size, and skips metadata such as modification times.
-- `SQLITE_ENABLE_BATCH_ATOMIC_WRITE=1` commits a transaction through the F2FS filesystem's atomic write when the database file supports it. The filesystem then stores either all of the transaction's pages or none of them, so SQLite does not need a journal file. When the filesystem lacks the feature or the atomic write fails, SQLite commits with the rollback journal as usual.
+## SQLite compile flags
 
-To build without batch atomic writes, set this boolean in your app's `package.json` and rebuild the native app:
+Use `nitroSqliteFlags` in `android/gradle.properties` for additional SQLite features or to override individual build defaults. For example, to enable FTS5:
 
-```json
-{
-  "nitroSQLite": {
-    "enableBatchAtomicWrite": false
-  }
-}
+```properties
+nitroSqliteFlags="-DSQLITE_ENABLE_FTS5=1"
 ```
 
-`enableBatchAtomicWrite` defaults to `true`, and a non-boolean value fails Gradle configuration. As with R\*Tree, SQLite only checks whether the macro is defined, so `-DSQLITE_ENABLE_BATCH_ATOMIC_WRITE=0` in `nitroSqliteFlags` does not disable it. To flush with `fsync()` instead, add `-DHAVE_FDATASYNC=0` to `nitroSqliteFlags`.
-
-## Threading
-
-The native library serializes all work on each database handle with its own lock, so it opens handles with `SQLITE_OPEN_NOMUTEX` instead of also taking SQLite's per-call connection mutex. Each connection runs its async queries, batches, and file imports one at a time on a native thread of its own. The thread starts with the connection's first such call and stops once the connection is closed and its pending work has finished. 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](/docs/guides/multiple-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.
+Custom definitions take precedence over `package.json` defaults. To disable batch atomic writes, use `enableBatchAtomicWrite: false` and remove custom `SQLITE_ENABLE_BATCH_ATOMIC_WRITE` definitions; setting that flag to `0` still enables it.
 
-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`.
+Android flushes data with `fdatasync()`. To use `fsync()`, add `-DHAVE_FDATASYNC=0`. Rebuild after changing flags.
 
 ## Vector search
 
-Install `react-native-nitro-sqlite-vec` and enable it in the app's `android/gradle.properties`:
+Install `react-native-nitro-sqlite-vec` and add this to `android/gradle.properties`:
 
 ```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](/docs/integrations/vector-search) for the helper API.
+Rebuild and follow the [vector search guide](/docs/integrations/vector-search). For SEE build settings, see [encryption](/docs/guides/encryption).

docs/content/docs/configuration/index.mdx

@@ -0,0 +1,36 @@
+---
+title: Configuration
+description: Shared SQLite settings in package.json.
+---
+
+Add the options you want to change to your app's `package.json`. These are the defaults for bundled SQLite on iOS, Android, macOS, and visionOS:
+
+```json
+{
+  "nitroSQLite": {
+    "threadSafe": true,
+    "performanceMode": true,
+    "enableRTree": true
+  }
+}
+```
+
+All values are booleans. Rebuild your app after changes; on Apple platforms, install Pods again first.
+
+## Thread safety
+
+Keep `threadSafe` enabled. Disabling it rejects [independent connections](/docs/guides/multiple-connections) and requires serializing all SQLite calls across the process, including calls to different databases.
+
+## Performance mode
+
+`performanceMode` applies SQLite's [recommended build optimizations](https://www.sqlite.org/compile.html#recommended_compile_time_options), independently of `threadSafe` and `enableRTree`. Use single quotes for SQL strings; `LIKE` and `GLOB` do not match BLOBs.
+
+WAL databases default to `synchronous = NORMAL`, which can lose recent commits after a power failure. Set `PRAGMA synchronous = FULL` on each connection if you need that durability. See [SQLite's synchronous settings](https://www.sqlite.org/pragma.html#pragma_synchronous). Performance mode does not enable WAL.
+
+## RTree support
+
+`enableRTree` includes spatial and interval indexes. Disabling it can cause `no such module: rtree` for schemas using them. See [query examples](/docs/concepts/queries-and-indexes#query-spatial-ranges).
+
+When supplying custom flags, omit `SQLITE_ENABLE_RTREE` to disable it. Defining it as `0` still enables the module.
+
+For platform settings and alternative build flags, see [iOS](/docs/configuration/ios), [Android](/docs/configuration/android), or [macOS](/docs/configuration/macos).

docs/content/docs/configuration/ios.mdx

@@ -1,82 +1,45 @@
 ---
-title: iOS configuration
-description: Database storage, app groups, bundled SQLite options, and vector search on iOS.
+title: iOS
+description: Database storage, app groups, and CocoaPods overrides.
 ---
 
-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.
+<span id="rtree-support" />
 
-## Database location
+See [Configuration](/docs/configuration) for shared `package.json` settings.
 
-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](/docs/guides/database-lifecycle) for the trust requirement.
+## Database location
 
-To use `Library/Application Support` as the root, add this to the app's `Info.plist`:
+Databases use Documents by default. To use `Library/Application Support`, add this to your app's `Info.plist`:
 
 ```xml
 <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.
+Existing databases and their sidecar files move when next opened or attached. Switching back to `Documents` does not move them back. See [file locations](/docs/guides/database-lifecycle#file-location-and-prepopulated-databases) for the `location` option.
 
 ## 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`:
+Enable the App Groups capability for your app and extension, then add the group identifier to `Info.plist`:
 
 ```xml
 <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.
+The group container takes precedence over the database location setting. An invalid or inaccessible container causes initialization to throw.
 
 ## 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:
-
-```sh
-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](/docs/concepts/queries-and-indexes#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:
-
-```json
-{
-  "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`.
+To use system SQLite instead of the bundled library, install Pods with `NITRO_SQLITE_USE_PHONE_VERSION=1`. The shared build settings cannot change system SQLite's capabilities.
 
 ## 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`:
-
-```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](/docs/guides/multiple-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.
+For one Pod installation, `NITRO_SQLITE_THREADSAFE` and `NITRO_SQLITE_PERFORMANCE_MODE` override the corresponding [`package.json` settings](/docs/configuration). Both accept `true`, `false`, `1`, or `0`.
 
 ## 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`:
+To enable FTS5 full-text search, add this inside your existing `post_install` block in `ios/Podfile`:
 
 ```ruby
 installer.pods_project.targets.each do |target|
@@ -89,14 +52,12 @@ installer.pods_project.targets.each do |target|
 end
 ```
 
-To use the licensed SQLite Encryption Extension, follow [encrypt a database](/docs/guides/encryption) 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:
+Install `react-native-nitro-sqlite-vec`, then run:
 
 ```sh
 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](/docs/integrations/vector-search).
+Rebuild and follow the [vector search guide](/docs/integrations/vector-search). For SEE build settings, see [encryption](/docs/guides/encryption).

docs/content/docs/configuration/macos.mdx

@@ -1,20 +1,22 @@
 ---
-title: macOS configuration
-description: Install Nitro SQLite in a React Native macOS app and run the repository example.
+title: macOS
+description: Installation, database storage, and Apple build options.
 ---
 
-Nitro SQLite supports React Native macOS. Install `react-native-nitro-sqlite` and `react-native-nitro-modules` in your app, then install CocoaPods from its `macos` directory and rebuild the native app:
+Use [Configuration](/docs/configuration) for shared `package.json` settings. Install `react-native-nitro-sqlite` and `react-native-nitro-modules`, then install Pods and rebuild:
 
 ```sh
 cd macos && pod install
 ```
 
-By default, macOS databases live in an app-specific Application Support directory. `open({ name: 'app.sqlite', location: 'databases' })` puts the file in a `databases` directory beneath that root. A sandboxed app cannot open files outside its accessible containers.
+Databases use an app-specific Application Support directory. See [file locations](/docs/guides/database-lifecycle#file-location-and-prepopulated-databases) for the `location` option. Sandboxed apps can access only their permitted containers.
 
-## Run the example
+## Apple build options
+
+Use the [iOS build options](/docs/configuration/ios#bundled-or-system-sqlite), running CocoaPods from `macos`.
 
-The repository's macOS example targets macOS 14 or later with React Native macOS 0.81. Install the workspace and example's Ruby dependencies, then run the example's `pods:macos` and `macos` scripts. It includes the SQLite, TypeORM, sqlite-vec, SQL console, and benchmark screens used by the mobile example.
+For vector search, install `react-native-nitro-sqlite-vec` and run `NITRO_SQLITE_VEC=1 pod install` from `macos`. Rebuild and follow the [vector search guide](/docs/integrations/vector-search).
 
-To keep Metro in a separate terminal, run the `start` script in `example/macos` and launch the `macos` script with `--no-packager`. Pass `--mode Release --no-packager` to build and launch the production bundle.
+## Run the example
 
-The [iOS configuration guide](/docs/configuration/ios) describes the shared Apple build flags for bundled SQLite, R\*Tree, thread safety, performance mode, and vector search. Run CocoaPods from `macos` when applying those settings to a macOS app.
+The repository example requires macOS 14 or later. Install its workspace and Ruby dependencies, then run the `pods:macos` and `macos` scripts. To run Metro separately, use the `start` script and pass `--no-packager` to `macos`. For a release build, pass `--mode Release --no-packager`.

docs/content/docs/configuration/meta.json

@@ -1,4 +1,4 @@
 {
-  "title": "Native configuration",
+  "title": "Configuration",
   "pages": ["ios", "android", "macos"]
 }

docs/content/docs/index.mdx

@@ -21,7 +21,7 @@ The default database location needs no custom SQLite settings. If your project h
 npx pod-install
 ```
 
-Android needs no additional Nitro SQLite configuration for the default setup. For a React Native macOS project, install CocoaPods from its `macos` directory. The [iOS](/docs/configuration/ios), [Android](/docs/configuration/android), and [macOS](/docs/configuration/macos) guides cover platform setup, storage locations, and build flags.
+Android needs no additional Nitro SQLite configuration for the default setup. For a React Native macOS project, install CocoaPods from its `macos` directory. Use [Configuration](/docs/configuration) for the shared `package.json` options. The [iOS](/docs/configuration/ios), [Android](/docs/configuration/android), and [macOS](/docs/configuration/macos) pages cover platform settings and build alternatives.
 
 ## 3. Rebuild the app
 

docs/next.config.mjs

@@ -8,6 +8,11 @@ const config = {
   turbopack: { root: process.cwd() },
   async redirects() {
     return [
+      {
+        source: '/docs/configuration/common',
+        destination: '/docs/configuration',
+        permanent: true,
+      },
       {
         source: '/docs/api',
         destination: '/api',