[API reference](https://evolu.dev/docs/api-reference) › [@evolu/common](https://evolu.dev/docs/api-reference/common) › NativeSqlite

Evolu's native SQLite binding and the [SqliteDriver](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/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](https://evolu.dev/docs/api-reference/common/Object/variables/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](https://evolu.dev/docs/api-reference/common/NativeSqlite/interfaces/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](https://evolu.dev/docs/api-reference/common/NativeSqlite/interfaces/NativeSqliteStatement#run) binds, steps to the end and resets, also
  when it fails, and returns a [NativeSqliteRunResult](https://evolu.dev/docs/api-reference/common/NativeSqlite/type-aliases/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](https://evolu.dev/docs/api-reference/common/NativeSqlite/interfaces/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](https://evolu.dev/docs/api-reference/common/NativeSqlite/interfaces/NativeSqliteStatement#step) returns a row or null and never resets.
  [NativeSqliteStatement.reset](https://evolu.dev/docs/api-reference/common/NativeSqlite/interfaces/NativeSqliteStatement#reset) and
  [NativeSqliteStatement.finalize](https://evolu.dev/docs/api-reference/common/NativeSqlite/interfaces/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](https://evolu.dev/docs/api-reference/common/NativeSqlite/interfaces/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](https://evolu.dev/docs/api-reference/common/NativeSqlite/variables/DatabaseFileHeldError) before it touches the file, and so does
  [NativeSqlite.deleteFile](https://evolu.dev/docs/api-reference/common/NativeSqlite/interfaces/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](https://evolu.dev/docs/api-reference/common/NativeSqlite/interfaces/NativeSqliteError) as its cause. A SQL text that prepare refuses has a
[NativeSqliteSqlTextError](https://evolu.dev/docs/api-reference/common/NativeSqlite/type-aliases/NativeSqliteSqlTextError) as its cause, and a held file a
[DatabaseFileHeldError](https://evolu.dev/docs/api-reference/common/NativeSqlite/variables/DatabaseFileHeldError).

## Functions

| Function                                                                                                   | Description                                                                                                                                                                                                                                                                                                                                                                                 |
| ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [createNativeSqliteDriver](https://evolu.dev/docs/api-reference/common/NativeSqlite/functions/createNativeSqliteDriver) | Creates the [CreateSqliteDriver](https://evolu.dev/docs/api-reference/common/Sqlite/type-aliases/CreateSqliteDriver) of Evolu over a [NativeSqlite](https://evolu.dev/docs/api-reference/common/NativeSqlite/interfaces/NativeSqlite) binding.                                                                                                                                                                        |
| [retryWhileHeld](https://evolu.dev/docs/api-reference/common/NativeSqlite/functions/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](https://evolu.dev/docs/api-reference/common/Sqlite/variables/databaseHeldTimeout) or more after the first started, as the web waits for a database another context holds. |

## Interfaces

| Interface                                                                                                                               | Description                                                                                                                                                                      |
| --------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [DatabaseFileHeldError](https://evolu.dev/docs/api-reference/common/NativeSqlite/interfaces/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](https://evolu.dev/docs/api-reference/common/NativeSqlite/interfaces/DatabasePathDep)                                               | Dependency wrapper for where the files of the databases are.                                                                                                                     |
| [NativeSqlite](https://evolu.dev/docs/api-reference/common/NativeSqlite/interfaces/NativeSqlite)                                                     | The binding the native code creates for a JavaScript runtime.                                                                                                                    |
| [NativeSqliteCodecFailure](https://evolu.dev/docs/api-reference/common/NativeSqlite/interfaces/NativeSqliteCodecFailure)                             | The failure Evolu's codec recorded for the call.                                                                                                                                 |
| [NativeSqliteDatabase](https://evolu.dev/docs/api-reference/common/NativeSqlite/interfaces/NativeSqliteDatabase)                                     | -                                                                                                                                                                                |
| [NativeSqliteDep](https://evolu.dev/docs/api-reference/common/NativeSqlite/interfaces/NativeSqliteDep)                                               | Dependency wrapper for [NativeSqlite](https://evolu.dev/docs/api-reference/common/NativeSqlite/interfaces/NativeSqlite).                                                                      |
| [NativeSqliteEncryptionUnsupportedError](https://evolu.dev/docs/api-reference/common/NativeSqlite/interfaces/NativeSqliteEncryptionUnsupportedError) | SQLite asked for something the codec can't keep encrypted.                                                                                                                       |
| [NativeSqliteError](https://evolu.dev/docs/api-reference/common/NativeSqlite/interfaces/NativeSqliteError)                                           | The cause of an error SQLite reported, as `@evolu/sqlite-wasm`'s `SqliteError`.                                                                                                  |
| [NativeSqlitePageAuthenticationError](https://evolu.dev/docs/api-reference/common/NativeSqlite/interfaces/NativeSqlitePageAuthenticationError)       | A page failed to authenticate, as with a wrong key or a damaged page.                                                                                                            |
| [NativeSqliteRandomSourceError](https://evolu.dev/docs/api-reference/common/NativeSqlite/interfaces/NativeSqliteRandomSourceError)                   | The platform's random source failed while the codec wrote a page.                                                                                                                |
| [NativeSqliteStatement](https://evolu.dev/docs/api-reference/common/NativeSqlite/interfaces/NativeSqliteStatement)                                   | -                                                                                                                                                                                |

## Type Aliases

| Type Alias                                                                                                    | Description                                                                                                                                                                                                                                                                              |
| ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [NativeSqliteOperation](https://evolu.dev/docs/api-reference/common/NativeSqlite/type-aliases/NativeSqliteOperation)       | The binding function an error comes from; the completion of a statement that `reset` or `finalize` reports is its `step`.                                                                                                                                                                |
| [NativeSqliteRunResult](https://evolu.dev/docs/api-reference/common/NativeSqlite/type-aliases/NativeSqliteRunResult)       | What a run returns: its changes when it returned no row, its rows when it changed none, and a [SqliteExecResult](https://evolu.dev/docs/api-reference/common/Sqlite/interfaces/SqliteExecResult) when it returned and changed rows, so a query or a write without RETURNING creates no result object. |
| [NativeSqliteSqlTextError](https://evolu.dev/docs/api-reference/common/NativeSqlite/type-aliases/NativeSqliteSqlTextError) | Why [NativeSqliteDatabase.prepare](https://evolu.dev/docs/api-reference/common/NativeSqlite/interfaces/NativeSqliteDatabase#prepare) refused the SQL itself.                                                                                                                                          |

## Variables

| Variable                                                                                             | Description                                                                                                                                                                      |
| ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [DatabaseFileHeldError](https://evolu.dev/docs/api-reference/common/NativeSqlite/variables/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. |