WebAssembly, a.k.a. WASM, is a standard defining a low-levelprogramming language suitable (A) as a target for cross-compilationfrom many other languages and (B) for running via a virtual machine ina browser. Designed with scriptability via JavaScript in mind, itprovides a way to compile C code (among others) to WASM and script itvia JavaScript with relatively little friction despite the vastdifferences between JavaScript and C.

Folks have been buildingsqlite3 for the web sinceasfar back as 2012 but this subproject is the firsteffort "officially" associated with the SQLite project, created withthe goal of making WASM builds of the library first-class members ofthe family of supported SQLite deliverables.

Specific Goals of this Project

The concrete goals of this project include...

• Except where noted in the non-goals, provide a more-or-lessfeature-complete wrapper to the sqlite3 C API, insofar as WASMfeature parity with C allows for. In fact, provideat leastthe following APIs...

  1. Bind alow-level sqlite3 API which is asclose to the native one as feasible in terms of usage.
  2. Ahigher-level OO API, more akin to sql.jsand node.js-style implementations. This one speaks directly tothe low-level API. This API must be used from the same thread asthe low-level API.
  3. AWorker-based API which speaks to theprevious APIs via Worker messages. This one is intended for usein the main thread, with the lower-level APIs installed in aWorker thread, and talking to them via Worker messages. BecauseWorkers are asynchronous and have only a single message channel,some acrobatics are needed here to feed async work results backto the client (as we cannot simply pass around callbacks betweenthe main and Worker threads).
  4. APromise-based variant of the Worker API(#3, above) which entirely hides the cross-thread communicationaspects from the user.

• Insofar as possible, supportpersistent client-side storageusing available JS APIs. As of this writing, that includes theOrigin-Private FileSystem (OPFS) and (very limited) storage viathewindow.localStorage andwindow.sessionStorage backend.

Specific Non-goals

Things we specifically donot aim to achieve:

• As WASM is a web-centric technology and UTF-8 is the King ofEncodings in that realm, there areno current plans to support theUTF16-related sqlite3 APIs. They would add a complication to thebindings for no appreciable benefit.

• Though support for out-of-browser WASM runtimes is widespread, thisproject is currentlyfocused only on browser targets. Thoughweb-related implementation details take priority, and the JavaScriptcomponents of the API specifically focus on browser clients, thelower-level WASM module "should" work in non-web WASM environments,assuming that the environment can provide the "imports" which theWASM file needs.

• Supporting old or niche-market platforms. WASM isbuilt for amodern web and requires modern platforms. Similarly, sqlite3library options which have been deprecated are not included in theWASM interface.

Attribution

Several projects have helped us considerably along the way. We aregreatly indebted to (in the order we investigated them)...

Emscripten

https://emscripten.org

The Emscripten WASM toolchain is, as of this writing, the onlyfull-featured WASM toolchain available. Though other toolchains exist,Emscripten offers several "killer features" which others do not, mostnotably transparent emulation of POSIX file I/O APIs, which allowssqlite3 to function as-is in a WASM build, with no changes or tweakingnecessary.

Additionally, Emscripten developers directly offered invaluablesupport during the development ofthe OPFS-based features.

sql.js

https://github.com/sql-js/sql.js

Alon Zakai'ssql.js was an essential stepping stone in this code'sdevelopment as it demonstrates how to handle some of the WASM-relatedvoodoo (like handling pointers-to-pointers and adding JSimplementations of C-bound callback functions). These APIs have aconsiderably different shape thansql.js, however.

As far as we're aware,sql.js wasthe first-ever published use ofsqlite3 for the web.

absurd-sql

https://github.com/jlongster/absurd-sql

James Long'sabsurd-sql demonstrates persistent browser-side SQLitedatabases by storing the databases in IndexedDB storage. Weexperimented with that approach but it didn't suit us. Even so, it wasan interesting experiment.

wa-sqlite

https://github.com/rhashimoto/wa-sqlite

Roy Hashimoto'swa-sqlite was the first project to publish an OPFSstorage option for sqlite3. His ongoing work in SQLite VFSes has beena continual source of inspiration.