API reference › @evolu/sqlite-wasm

Modules

Module	Description
c-api	SQLite's C API as the wasm exports it: the C-named functions, the SQLITE_* constants, and the struct layouts.

Interfaces

Interface	Description
OpfsDirectoryHandle	The part of FileSystemDirectoryHandle the pool uses.
OpfsFileHandle	The part of FileSystemFileHandle the pool uses.
OpfsNameError	Error returned when a string is not a valid OpfsName.
OpfsRoot	Access to the OPFS root, which navigator.storage provides in a dedicated worker.
OpfsRootDep	Dependency wrapper for OpfsRoot.
OpfsSyncAccessHandle	The part of FileSystemSyncAccessHandle the pool uses.
SahPool	A pool of sync access handles, and the VFS SQLite opens its files with, on which File and EncryptedFile databases open.
SahPoolAlreadyOpenError	This instance has a pool in the directory open, or is opening one. A retry succeeds once that pool is disposed or its open failed.
SahPoolFileNotFoundError	The pool has no file with the path.
SahPoolFullError	No slot of the pool is free for a new file, which xOpen records when it fails with SQLITE_CANTOPEN.
SahPoolHeldError	Another context or instance holds a slot of the pool. The pool wrote nothing, and a retry succeeds once the slot is released.
SahPoolInvalidPathError	A name xOpen, xDelete or xAccess cannot map to a pool path, because the suffix SQLite appends would land in its query, fragment or host, which would map a database and its journal to the same file. xOpen also records it for a path that would not fit a slot's header, or a database's path whose super-journal's path would not.
SahPoolOptions	Options for openSahPool.
SahPoolSetupError	OPFS failed while the pool was being set up, or its VFS could not be registered.
SqliteCodecFailure	The first failure Evolu's codec recorded for the main database of a File or EncryptedFile connection since the top-level operation started. It has no method or path, because the codec records a failure of the database's journal on the database.
SqliteDatabase	An open SQLite database. Disposing it while one of its operations runs, as from a callback, throws.
SqliteEmptySqlError	The SQL contains no statement, only whitespace or comments.
SqliteEncryptedDatabase	The result of createEncryptedSqliteDatabase.
SqliteEncryptedFileDatabaseOptions	A database file on a SahPool that Evolu's codec encrypts, in the format of SQLite3 Multiple Ciphers' sqlcipher scheme.
SqliteEncryptionUnsupportedError	What Evolu's codec refuses because it cannot keep a database encrypted, or because a database keyed through SQL would stay plaintext. For an encrypted database, a read or write that is not a whole page, a page 1 that would change the page size or the reserved bytes, as a VACUUM that changes the page size writes it, turning secure_delete off, or the hot journal of one opened without its key, which fails with SQLITE_CANTOPEN and stays for the key. For any database on a pool, the keying pragmas, such as PRAGMA key, and a page 1 that says WAL.
SqliteError	An error SQLite reported.
SqliteFileDatabaseOptions	An unencrypted database file on a SahPool.
SqliteInvalidSqlTextError	The SQL is text SQLite would read as other SQL, so it fails before SQLite sees it: it contains a NUL character, which SQLite reads SQL only up to, so it would silently ignore the rest, or a lone surrogate, which UTF-8 cannot encode, so it would run with U+FFFD in its place.
SqliteMemoryDatabaseOptions	An in-memory database on the default VFS, which never touches OPFS. Temporary tables and indexes stay in memory in every mode.
SqliteMultipleStatementsError	The SQL contains more than one statement.
SqliteNoMemError	sqlite3_malloc returned NULL.
SqlitePageAuthenticationError	A page of an encrypted database or its journal that failed to authenticate, because the key is wrong or the page was altered or cut short, as Evolu's codec records it.
SqliteParameterCountError	A run supplied a different number of parameters than the SQL has, or SqliteDatabase.exec, which supplies none, met a statement with parameters.
SqliteRandomSourceError	The random source failed while Evolu's codec encrypted a page, so the write failed with SQLITE_IOERR_WRITE. What the source threw went to the instance's ReportDefect.
SqliteRunResult	The result of SqliteStatement.run.
SqliteScratch	Reusable memory for output parameters and bind values, allocated once per database instead of once per call.
SqliteShortWriteError	A write that stored fewer or more bytes than requested.
SqliteStatement	A prepared statement. Running or disposing it during its own run, as from a callback, throws.
SqliteVfsFailure	A failure a pool's method recorded before returning an error code.
SqliteVfsIoError	The storage of a pool failed outside SQLite, as when SahPool.unlink deletes a file.
SqliteVfsPathError	Error returned when a string is not a valid SqliteVfsPath.
SqliteWasm	A loaded SQLite wasm instance.
SqliteWasmBuildMismatchError	The binary's sqliteWasmBuildHash differs, so it is not the build the generated code describes.
SqliteWasmCompileError	The source could not be fetched, compiled or instantiated, its memory could not be allocated, its static constructors failed, or the module that installs the default VFS's methods could not be compiled.
SqliteWasmDep	Dependency wrapper for SqliteWasm.
SqliteWasmFunction	A JavaScript function to install into the function table.
SqliteWasmFunctions	Functions installed by installWasmFunctions.
SqliteWasmInitializeError	sqlite3_initialize failed, or allocating, finding or registering the default VFS did, for example when out of memory.
SqliteWasmUnknownImportError	The binary declares imports the loader does not implement.
SubtleCryptoDep	WebCrypto, which derives legacy keys.

Type Aliases

Type Alias	Description
CStringPtr	A NUL-terminated UTF-8 string.
NullPtr	The C NULL pointer.
OpfsName	The name of a file or directory in OPFS, a valid file name of the File System Standard on every platform in one spelling: not empty, not . or .., without / or ``, which is a path separator on Windows, without NUL or a lone surrogate, and in Unicode NFC.
SahPoolError	Why openSahPool failed.
SqliteBackupPtr	An online backup from one connection's database to another's, sqlite3_backup*.
SqliteCodecError	What Evolu's codec found wrong.
SqliteContextPtr	The context of an application-defined function call, sqlite3_context*.
SqliteDatabaseOptions	How to open a database.
SqliteDbPtr	An open database connection, sqlite3*.
SqliteDestructor	The destructor argument of sqlite3_bind_text, sqlite3_bind_blob, sqlite3_result_text and sqlite3_result_blob.
SqliteExecError	Why SqliteDatabase.exec failed.
SqliteFailure	A failure the pool or Evolu's codec recorded, which SqliteError carries.
SqliteFilenamePtr	A database filename SQLite created, sqlite3_filename, as xOpen receives it.
SqliteFilePtr	A file SQLite opened through a VFS, sqlite3_file*.
SqliteFunctionPtr	A C function pointer, which in wasm is an index into the function table, not a memory address.
SqliteIndexInfoPtr	The query planner's exchange with a virtual table's xBestIndex, sqlite3_index_info*.
SqliteKeyDerivation	Which key opened an encrypted database: the raw key, or the key 2.2.4 derived from it because of a bug in SQLite3 Multiple Ciphers, which deriveLegacySqliteKey describes.
SqliteOperation	The operation a SqliteError comes from.
SqliteOwnedCStringPtr	A NUL-terminated UTF-8 string in memory allocated with sqlite3_malloc, which the holder frees with sqlite3_free.
SqliteOwnedPtr	Memory allocated with sqlite3_malloc.
SqliteOwnedValuePtr	A protected value copied with sqlite3_value_dup, which the holder frees with sqlite3_value_free.
SqlitePrepareError	Why SqliteDatabase.prepare failed.
SqliteRunError	Why SqliteStatement.run failed.
SqliteStmtPtr	A prepared statement, sqlite3_stmt*.
SqliteValuePtr	A dynamically typed SQL value, sqlite3_value*, such as a column value or an argument of an application-defined function.
SqliteVfsMethod	A VFS or I/O method that can record a SqliteVfsFailure.
SqliteVfsPath	The canonical path of a database file on a SahPool, such as /evolu1.db, one spelling per file, as SahPool.getPaths lists it.
SqliteVfsPtr	A VFS struct, sqlite3_vfs*.
SqliteWasmError	Why createSqliteWasm failed.
SqliteWasmSource	The wasm binary, compiled or not.
WasmPtr	An address in the wasm heap.

Variables

Variable	Description
maxInt32	The largest C int.
maxSqliteInt64	The largest SQLite INTEGER, 2^63 - 1.
minSqliteInt64	The smallest SQLite INTEGER, -2^63.
OpfsName	The name of a file or directory in OPFS, a valid file name of the File System Standard on every platform in one spelling: not empty, not . or .., without / or ``, which is a path separator on Windows, without NUL or a lone surrogate, and in Unicode NFC.
sahPoolDefaultCapacity	The number of slots setup ensures: a database, its journal, and spares.
sahPoolDigestV2Flag	The flag that marks a header digest as version 2.
sahPoolHeaderCorpusSize	The size of the path and flags, which the digest covers.
sahPoolHeaderDigestOffset	Where the header's digest, two platform-endian u32 values, starts.
sahPoolHeaderFlagsOffset	Where the header's big-endian u32 flags start, after the path.
sahPoolHeaderPathSize	The bytes reserved for the NUL-padded path at the start of the header.
sahPoolHeaderSize	The size of a slot's header, where the file's data starts.
sahPoolMaxDatabasePathSize	The longest path of a database a pool opens, in UTF-8 bytes, 498. SQLite names the other files of a database by appending a suffix to its path, at most the 12 bytes of a super-journal's -mjXXXXXX9XX, and each path must fit a slot's header with its NUL, as opfs-sahpool requires, which allows 510 bytes.
sahPoolOpaqueDirectoryName	The pool subdirectory that holds the slots. Renaming it orphans them.
sahPoolPersistentFileTypes	The file types that persist across sessions: SQLITE_OPEN_MAIN_DB, SQLITE_OPEN_MAIN_JOURNAL, SQLITE_OPEN_SUPER_JOURNAL and SQLITE_OPEN_WAL, combined. A slot with another type is freed at setup.
SqliteVfsPath	The canonical path of a database file on a SahPool, such as /evolu1.db, one spelling per file, as SahPool.getPaths lists it.
sqliteWasmUrl	The URL of the wasm binary the package ships, to load with createSqliteWasm.

Functions

Function	Description
allocCString	Copies a string into new memory as a NUL-terminated UTF-8 C string, which the caller frees with sqlite3_free.
allocWasm	Allocates at least one byte with sqlite3_malloc, so a zero-length value keeps a non-NULL address.
computeSahPoolDigest	Computes the digest of a header's first sahPoolHeaderCorpusSize bytes, as opfs-sahpool does.
copyWasmBytes	Copies bytes out of wasm memory into a new ArrayBuffer, so the result can be transferred to another worker.
createEncryptedSqliteDatabase	Opens an EncryptedFile database on a pool, falling back to the key @evolu/sqlite-wasm 2.2.4 derived.
createSqliteDatabase	Opens a database.
createSqliteScratch	Creates a SqliteScratch.
createSqliteWasm	Loads the wasm, following the steps in the module documentation.
deriveLegacySqliteKey	Derives the key @evolu/sqlite-wasm 2.2.4 used: PBKDF2-HMAC-SHA512 with 256000 iterations and a 32-byte output, over the UTF-8 text x' followed by the key in lowercase hex and ', salted with the database's first 16 bytes.
initializeSqliteWasm	Initializes the library as loading steps 6 and 7 do, for use after sqlite3_shutdown and sqlite3_config.
installWasmFunctions	Installs functions into the function table.
isInt32	Whether a number is a 32-bit integer, which binds with sqlite3_bind_int without a BigInt.
isSqliteInt64	Whether a bigint fits a SQLite INTEGER.
openSahPool	Opens the pool in a directory, registering its VFS on first use.
readCString	Decodes a NUL-terminated C string, such as an error message or a column name.
readUtf8	Decodes UTF-8 of a known byte length, such as a text column, keeping a leading byte order mark and embedded NUL characters.
sqliteResultCodeToPrimary	Returns the primary result code of a result code, its low 8 bits, such as SQLITE_CONSTRAINT for SQLITE_CONSTRAINT_NOTNULL. A primary result code returns itself.
writeUtf8	Encodes a string as UTF-8 into existing memory and returns the byte length, without a NUL terminator.
writeWasmBytes	Copies bytes into wasm memory.

References

SqlitePrimaryResultCode

Re-exports SqlitePrimaryResultCode

---

SqliteResultCode

Re-exports SqliteResultCode