API reference › @evolu/common › NativeSqlite
Evolu's native SQLite binding and the SqliteDriver over it, which
@evolu/react-native and @evolu/nodejs share.
The binding is the JavaScript interface that @evolu/react-native's JSI
adapter implements on React Native and @evolu/nodejs's Node-API addon in
Node.js, both over the binding layer of Evolu's SQLite core,
binding/evolu_database.h. @evolu/react-native's
test/bindingConformance.ts pins that both behave alike.
Values
nullbinds NULL, a safe integer binds as INTEGER, any other finite number as REAL, a string as text with its exact UTF-8 length, its lone surrogates as U+FFFD, and aUint8Arrayas a blob, an empty one too. Any other value, and a number of parameters other than the SQL's, throws a TypeError.- INTEGER and REAL read as numbers, so an integer beyond 2^53 rounds, as in
@evolu/sqlite-wasm. TEXT reads with its exact length, so NUL characters survive, and TEXT that isn't UTF-8 with U+FFFD in place of each ill-formed sequence, as the WHATWG decoder reads it, and so do column names and error messages. A blob is a copy with a buffer of its own. - Rows inherit nothing: their prototype is null, as Hermes creates them, or
emptyPrototype, as Node.js's binding creates them, since V8 keeps
such a row's properties as fast as an ordinary object's, which it doesn't
for a row without a prototype. Either way a column named
__proto__is an ordinary property, and of columns with the same name, the last wins. A statement reads its column names again after a schema change prepared it again.
Statements
- NativeSqliteDatabase.prepare takes exactly one statement, as
@evolu/sqlite-wasmdoes: SQL with a NUL character or a lone surrogate, which SQLite would read as other SQL, fails before SQLite sees it, SQL without a statement fails, and only semicolons, whitespace, UTF-8 byte order marks and comments may follow the statement. The rest is scanned, not prepared, since SQLite applies some pragmas when it prepares them. - NativeSqliteStatement.run binds, steps to the end and resets, also
when it fails, and returns a NativeSqliteRunResult, whose changes
are 0 when the run changed no rows or the statement is read-only, and
otherwise
sqlite3_changes64. SQLite keeps a copy of each bound value until its parameter is bound again, so a run that bound a text or blob over 64 KiB, as UTF-8 for text, clears its bindings after it resets, also when it fails, as@evolu/sqlite-wasmdoes, and a kept statement holds no large value between runs. - NativeSqliteDatabase.run prepares one statement as
preparedoes, runs it as a statement'srundoes and finalizes it, creating no statement handle, as@evolu/sqlite-wasm'sSqliteDatabase.rundoes. It reads its parameters before it prepares the statement. - NativeSqliteStatement.step returns a row or null and never resets.
NativeSqliteStatement.reset and
NativeSqliteStatement.finalize throw SQLite's error only when the
last step returned a row, which is when completing the statement can fail,
as the commit of a write with RETURNING that an iteration stopped early.
resetkeeps the bindings. - NativeSqliteDatabase.close finalizes every statement, closes the connection and releases its file, never throws for an error SQLite reports, and does nothing the second time. When SQLite can't close it, as with a backup unfinished, the connection stays open, holding its file, and a later close tries again, but the statements stay finalized. A handle used after its database closed, or a statement after its finalize or its database's close, throws, and so does a method called on another kind of object.
Files
- One connection per database file in the process: an open of a file another connection holds, through any spelling of its path, fails with DatabaseFileHeldError before it touches the file, and so does NativeSqlite.deleteFile.
- A path that contains a NUL character, isn't absolute, or whose last component
is empty,
.or..throws a TypeError, and so does a key that isn't aUint8Arrayof 32 bytes. - An encrypted file opens through Evolu's codec, also the databases
expo-sqlite's SQLCipher wrote, and a plain file with plain SQLite;
binding/evolu_database.hdescribes what an open, a delete and an export do. A pragma that keys a database, such aspragma key, fails on every file rather than leave it in plaintext, and an attached database is read-only, because SQLite ignores theKEYclause ofATTACH.
Errors
An error SQLite reports is thrown as an Error with SQLite's message and a
NativeSqliteError as its cause. A SQL text that prepare refuses has a
NativeSqliteSqlTextError as its cause, and a held file a
DatabaseFileHeldError.
Functions
| Function | Description |
|---|---|
| createNativeSqliteDriver | Creates the CreateSqliteDriver of Evolu over a NativeSqlite binding. |
| retryWhileHeld | Runs attempt at once and, until one returns ok, again 50 ms after an attempt that returned an error, then after twice the previous delay, up to a second. It returns the error of an attempt that ends databaseHeldTimeout or more after the first started, as the web waits for a database another context holds. |
Interfaces
| Interface | Description |
|---|---|
| DatabaseFileHeldError | Another connection of the process has the database file open, so an open or a delete of it fails before it touches the file. The binding throws an Error with it as its cause. |
| DatabasePathDep | Dependency wrapper for where the files of the databases are. |
| NativeSqlite | The binding the native code creates for a JavaScript runtime. |
| NativeSqliteCodecFailure | The failure Evolu's codec recorded for the call. |
| NativeSqliteDatabase | - |
| NativeSqliteDep | Dependency wrapper for NativeSqlite. |
| NativeSqliteEncryptionUnsupportedError | SQLite asked for something the codec can't keep encrypted. |
| NativeSqliteError | The cause of an error SQLite reported, as @evolu/sqlite-wasm's SqliteError. |
| NativeSqlitePageAuthenticationError | A page failed to authenticate, as with a wrong key or a damaged page. |
| NativeSqliteRandomSourceError | The platform's random source failed while the codec wrote a page. |
| NativeSqliteStatement | - |
Type Aliases
| Type Alias | Description |
|---|---|
| NativeSqliteOperation | The binding function an error comes from; the completion of a statement that reset or finalize reports is its step. |
| NativeSqliteRunResult | What a run returns: its changes when it returned no row, its rows when it changed none, and a SqliteExecResult when it returned and changed rows, so a query or a write without RETURNING creates no result object. |
| NativeSqliteSqlTextError | Why NativeSqliteDatabase.prepare refused the SQL itself. |
Variables
| Variable | Description |
|---|---|
| DatabaseFileHeldError | Another connection of the process has the database file open, so an open or a delete of it fails before it touches the file. The binding throws an Error with it as its cause. |