The SQLite Encryption Extension (SEE)

The JavaScript/WASM build can be created using a copy of the SQLite Encryption Extension (SEE), but doing so comes with some caveats:

Creating an SEE-capable WASM Build

Building the SQLite WASM package requires a Linux system with the Emscripten tools installed. Instructions for installing those tools can be found in the canonical sqlite source tree.

With those installed, creating the SEE bundle is as easy as doing the following from the top-most directory of a checked-out copy of the SQLite canonical source tree:

$ ./configure --enable-all               # or preferred flags
$ cd ext/wasm
$ . /path/to/                # part of the Emscripten tools
$ make sqlite3.c=/path/to/sqlite3-see.c  # needs to be an absolute path

The resulting build artifacts can all be found in the jswasm subdirectory. The build time, of course, varies wildly depending on the system. A mid-range x64 machine typically runs it in about 45 seconds.

For users who exclusively, and repeatedly, create SEE-capable builds, the above can be simplified somewhat by placing a copy of, or symlink to, sqlite3-see.c in the top-most directory of the build tree:

$ ln -s /path/to/sqlite3-see.c .  # only needed once
$ ./configure --enable-all        # or preferred flags
$ cd ext/wasm
$ . /path/to/         # part of the Emscripten tools
$ make

Note that the build may be parallelized using the -j# flag to make, where # is the number of parallel make instances to run. The longest-running parts of the build do not benefit from that, however, so setting # to be arbitrarily high will not speed up the build significantly1.

Assuming all goes well, the output of the build will start with something like:

$ make
using emcc version [3.1.57]
This is an SEE build.

If that "SEE" line (or something equivalent) does not appear, the build is not SEE-capable. It is also possible to inspect the resulting JS sources to determine whether it's an SEE build:

$ grep -w sqlite3_key_v2 jswasm/sqlite3.js

If that produces any output then the resulting build is SEE-capable.

When alternating between SEE- and non-SEE builds, it is necessary to run make clean between each build, otherwise the build may either outright fail or silently fail to include the SEE APIs.

Using the SEE Build

The SEE build is used identically to the main distribution, but also includes the various sqlite3 API functions related to encryption, such as sqlite3_key_v2(). Those functions are not required for using encryption, as each such API is also accessible via pragmas, as documented in the SEE docs. The existence of the SEE-specific functions in a JS/WASM build can be used to distinguish it from a non-SEE build.

As of version 3.46, the oo1 API supports SEE in the form of an optional argument to the constructors of the DB class and its subclasses.

  1. ^ For long and boring technical reasons involving how sqlite3.wasm needs to be built.