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

  • null binds 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 a Uint8Array as 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-wasm does: 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-wasm does, and a kept statement holds no large value between runs.
  • NativeSqliteDatabase.run prepares one statement as prepare does, runs it as a statement's run does and finalizes it, creating no statement handle, as @evolu/sqlite-wasm's SqliteDatabase.run does. 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. reset keeps 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 a Uint8Array of 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.h describes what an open, a delete and an export do. A pragma that keys a database, such as pragma key, fails on every file rather than leave it in plaintext, and an attached database is read-only, because SQLite ignores the KEY clause of ATTACH.

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

FunctionDescription
createNativeSqliteDriverCreates the CreateSqliteDriver of Evolu over a NativeSqlite binding.
retryWhileHeldRuns 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

InterfaceDescription
DatabaseFileHeldErrorAnother 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.
DatabasePathDepDependency wrapper for where the files of the databases are.
NativeSqliteThe binding the native code creates for a JavaScript runtime.
NativeSqliteCodecFailureThe failure Evolu's codec recorded for the call.
NativeSqliteDatabase-
NativeSqliteDepDependency wrapper for NativeSqlite.
NativeSqliteEncryptionUnsupportedErrorSQLite asked for something the codec can't keep encrypted.
NativeSqliteErrorThe cause of an error SQLite reported, as @evolu/sqlite-wasm's SqliteError.
NativeSqlitePageAuthenticationErrorA page failed to authenticate, as with a wrong key or a damaged page.
NativeSqliteRandomSourceErrorThe platform's random source failed while the codec wrote a page.
NativeSqliteStatement-

Type Aliases

Type AliasDescription
NativeSqliteOperationThe binding function an error comes from; the completion of a statement that reset or finalize reports is its step.
NativeSqliteRunResultWhat 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.
NativeSqliteSqlTextErrorWhy NativeSqliteDatabase.prepare refused the SQL itself.

Variables

VariableDescription
DatabaseFileHeldErrorAnother 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.