You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 47e0ea5
Browse filesBrowse the repository at this point in the historyBrowse files
Co-authored-by: Ritesh Shukla <riteshshukla@Riteshs-Mac-Studio.local>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Christoph Pader <chris@margelo.com>
Copy file name to clipboardExpand all lines: docs/content/docs/configuration/android.mdx
+22-1Lines changed: 22 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -39,9 +39,30 @@ To omit R\*Tree from the bundled build, set this boolean in your app's `package.
39
39
40
40
`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`.
41
41
42
+
## Commit I/O
43
+
44
+
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.
45
+
46
+
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:
47
+
48
+
-`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.
49
+
-`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.
50
+
51
+
To build without batch atomic writes, set this boolean in your app's `package.json` and rebuild the native app:
52
+
53
+
```json
54
+
{
55
+
"nitroSQLite": {
56
+
"enableBatchAtomicWrite": false
57
+
}
58
+
}
59
+
```
60
+
61
+
`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`.
62
+
42
63
## Threading
43
64
44
-
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](/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.
65
+
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.
45
66
46
67
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`.
Copy file name to clipboardExpand all lines: docs/content/docs/guides/parameters-and-results.mdx
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -78,4 +78,4 @@ The [`NitroSQLiteExceptionType` constants](/api/react-native-nitro-sqlite/variab
78
78
79
79
`DatabaseCannotBeOpened` covers several causes, including invalid paths, an already-open default connection, and filesystem failures. It does not by itself establish that the device is low on storage.
80
80
81
-
For exact types, see [`QueryResult`](/api/react-native-nitro-sqlite/type-aliases/QueryResult), [`NitroSQLiteQueryResult`](/api/react-native-nitro-sqlite/hybrid-objects/NitroSQLiteQueryResult), and [`NitroSQLiteQueryResultRows`](/api/react-native-nitro-sqlite/type-aliases/NitroSQLiteQueryResultRows). The row generic narrows `rows._array` and `rows.item()`, but not the raw `results` array. Query results also inherit Nitro hybrid object members; see [native access](/docs/guides/sync-and-async#global-helpers-and-native-access).
81
+
For exact types, see [`QueryResult`](/api/react-native-nitro-sqlite/type-aliases/QueryResult), [`NitroSQLiteQueryResult`](/api/react-native-nitro-sqlite/interfaces/NitroSQLiteQueryResult), and [`NitroSQLiteQueryResultRows`](/api/react-native-nitro-sqlite/type-aliases/NitroSQLiteQueryResultRows). The row generic narrows `rows._array` and `rows.item()`, but not the raw `results` array. Query results are plain JavaScript objects; see [native access](/docs/guides/sync-and-async#global-helpers-and-native-access) for results returned without the connection helper.
Copy file name to clipboardExpand all lines: docs/content/docs/guides/performance.mdx
+15Lines changed: 15 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -21,6 +21,21 @@ console.log(rows._array)
21
21
22
22
An async call still consumes device CPU and database I/O. Paginate large result sets instead of bringing every row into JavaScript at once.
23
23
24
+
## Reuse SQL text
25
+
26
+
Before SQLite runs a statement, it compiles the SQL text into a program for its virtual machine. Compiling one statement is quick, but the cost adds up when the same statement runs many times, such as an `INSERT` in a loop.
27
+
28
+
Each connection keeps the compiled programs of its 32 most recently used queries and data changes: statements that start with `SELECT`, `INSERT`, `UPDATE`, `DELETE`, `REPLACE`, `WITH`, or `VALUES`. When `execute()` or `executeAsync()` receives the same SQL text again, it reuses the program with the new parameters. Pass values as parameters rather than formatting them into the SQL so the text stays identical between calls. Other statements, such as `PRAGMA`, `ATTACH`, and `BEGIN`, compile on every call because SQLite can apply their effect while compiling them. Use [prepared statements](/docs/guides/prepared-statements) when you want to manage a compiled statement's lifetime yourself.
29
+
30
+
```ts
31
+
for (const metric ofmetrics) {
32
+
db.execute('INSERT INTO metrics (key, value) VALUES (?, ?)', [
33
+
metric.key,
34
+
metric.value,
35
+
])
36
+
}
37
+
```
38
+
24
39
## Group related writes
25
40
26
41
One `executeBatchAsync()` call executes a fixed set of statements inside a native transaction. Use nested parameter arrays for repeated SQL. Use `db.transaction()` when application logic must inspect a result between writes. Both keep a transaction open while they work; keep the scope short and await each operation inside a transaction callback.
Use synchronous calls when immediate results are useful and the work is small. Prefer async calls for queries that may scan many rows, batches, or file imports. [Performance guidance](/docs/guides/performance) covers other ways to keep work bounded.
22
22
23
+
An async query still delivers its rows to JavaScript, and only the JavaScript thread can turn them into objects. For a large result, `executeAsync()` hands rows over in batches while SQLite reads the rest, so building the objects overlaps with the query instead of starting after it. The promise still resolves once, with every row in order.
24
+
23
25
An `open()` connection submits ordinary async statements in call order. Native operations on that connection run one at a time in submission order, but await a write before starting a read that depends on it so you can handle write errors. Batches and transactions wait for preceding statements and reserve the connection until complete. A synchronous operation, `close()`, or `delete()` throws a busy error if work is pending or active. Await async work before calling a synchronous method on the same connection:
24
26
25
27
```ts
@@ -38,7 +40,7 @@ Prepared statement `executeAsync()` reserves the connection queue until it finis
38
40
39
41
The [`NitroSQLite` export](/api/react-native-nitro-sqlite/variables/NitroSQLite) also has `execute`, `executeAsync`, `prepare`, `executeBatch`, `executeBatchAsync`, and `transaction` helpers that take a database name. `NitroSQLite.open(options)` is the same helper as the named [`open()` export](/api/react-native-nitro-sqlite/functions/open). Global queries join the default connection's JavaScript queue when the name was opened through `open()`. They do not address independent connections; use the object returned by `open()` for those. Without a default managed connection, global `execute` and `executeAsync` call the native methods directly and still need an open native database handle. Global `prepare`, batches, and transactions need a default connection opened through `open()`.
40
42
41
-
`NitroSQLite.native` exposes the underlying [`NitroSQLiteNative` hybrid object](/api/react-native-nitro-sqlite/hybrid-objects/NitroSQLiteNative). Its methods take a database name and return raw results without the connection helper's `rows` container. They also throw native errors without converting them to `NitroSQLiteError`.
43
+
`NitroSQLite.native` exposes the underlying [`NitroSQLiteNative` hybrid object](/api/react-native-nitro-sqlite/hybrid-objects/NitroSQLiteNative). Its methods take a database name and return raw results without the connection helper's `rows` container. They also throw native errors without converting them to `NitroSQLiteError`. Its `executeAsync()` accepts an optional `onRows` callback that receives leading rows in batches, in order; the resolved `results` then holds only the rows after the last batch.
Native calls bypass the JavaScript queue. If you use them alongside an `open()` connection, coordinate access yourself. A native statement can run inside an active connection transaction without joining its callback's sequence. The raw result is a Nitro hybrid object with `name`, `toString()`, `equals(other)`, and `dispose()` members. Disposing it makes that result unusable. `dispose()`is not a database `close()`call, and ordinary garbage collection handles these objects. Do not dispose the shared `NitroSQLite.native`instance during normal database cleanup.
57
+
Native calls bypass the JavaScript queue. If you use them alongside an `open()` connection, coordinate access yourself. A native statement can run inside an active connection transaction without joining its callback's sequence. The raw result is a plain JavaScript object with `rowsAffected`, `insertId`, `results`, and `metadata`; ordinary garbage collection reclaims it. `NitroSQLite.native` itself is a Nitro hybrid object with a `dispose()`member. Do not dispose that shared instance during normal database cleanup; `dispose()` is not a database `close()` call.
56
58
57
59
The `NitroSQLite` export spreads the hybrid instance, but inherited native methods do not appear on that top-level object. Call them through `.native`. If you compile SQLite with `SQLITE_THREADSAFE=0`, also serialize access across separate database handles and native threads. See the [iOS](/docs/configuration/ios#thread-safety-and-performance-mode) and [Android](/docs/configuration/android#threading) configuration pages.
0 commit comments