SQLite Wasm Rust

Provide sqlite solution for wasm32-unknown-unknown target.

Usage

[dependencies]
# using `bundled` default feature causes us to automatically compile and link in an up to date
#
# requires the emscripten toolchain
sqlite-wasm-rs = "0.3"

[dependencies]
# using precompiled binaries
sqlite-wasm-rs = { version = "0.3", default-features = false, features = ["precompiled"] }

use sqlite_wasm_rs::export::{self as ffi, install_opfs_sahpool};

async fn open_db() -> anyhow::Result<()> {
    // open with memory vfs
    let mut db = std::ptr::null_mut();
    let ret = unsafe {
        ffi::sqlite3_open_v2(
            c"mem.db".as_ptr().cast(),
            &mut db as *mut _,
            ffi::SQLITE_OPEN_READWRITE | ffi::SQLITE_OPEN_CREATE,
            std::ptr::null()
        )
    };
    assert_eq!(ffi::SQLITE_OK, ret);

    // install opfs-sahpool persistent vfs and set as default vfs
    install_opfs_sahpool(None, true).await?;

    // open with opfs-sahpool vfs
    let mut db = std::ptr::null_mut();
    let ret = unsafe {
        ffi::sqlite3_open_v2(
            c"opfs-sahpool.db".as_ptr().cast(),
            &mut db as *mut _,
            ffi::SQLITE_OPEN_READWRITE | ffi::SQLITE_OPEN_CREATE,
            std::ptr::null()
        )
    };
    assert_eq!(ffi::SQLITE_OK, ret);
}

About multithreading

This library is not thread-safe:

• JsValue is not cross-threaded, see Ensure that JsValue isn't considered Send for details.
• sqlite is compiled with -DSQLITE_THREADSAFE=0

About VFS

The following vfs have been implemented:

• memory-vfs: as the default vfs, no additional conditions are required, just use.
• opfs-sahpool: ported from sqlite-wasm, it provides the best performance persistent storage method.

See https://github.com/Spxg/sqlite-wasm-rs/blob/master/VFS.md

Use external libc

As mentioned above, sqlite is now directly linked to emscripten's libc. But we provide the ability to customize libc.

Cargo provides a links field that can be used to specify which library to link to.

We created a new sqlite-wasm-libc library with no implementation and only a links = "libc" configuration.

Then with the help of Overriding Build Scripts, you can overriding its configuration in your crate and link sqlite to your custom libc.

More see custom-libc example.

Why provide precompiled library

In the shim feature, since wasm32-unknown-unknown does not have libc, emscripten is used here for compilation, otherwise we need to copy a bunch of c headers required for sqlite3 compilation, which is a bit of a hack for me. If sqlite3 is compiled at compile time, the emscripten toolchain is required, and we cannot assume that all users have it installed. (Believe me, because rust mainly supports the wasm32-unknown-unknown target, most people do not have the emscripten toolchain). Considering that wasm is cross-platform, vendor compilation products are acceptable.

About security issues:

• You can specify the bundled feature to compile sqlite locally, which requires the emscripten toolchain.
• Currently all precompiled products are compiled and committed through Github Actions, which can be tracked, downloaded and compared.

Precompile workflow: https://github.com/Spxg/sqlite-wasm-rs/blob/master/.github/workflows/precompile.yml

Change History: https://github.com/Spxg/sqlite-wasm-rs/commits/master/sqlite-wasm-rs/library

Actions: https://github.com/Spxg/sqlite-wasm-rs/actions?query=event%3Aworkflow_dispatch

Related Project

• sqlite-wasm: SQLite Wasm conveniently wrapped as an ES Module.
• sqlite-web-rs: A SQLite WebAssembly backend for Diesel.
• rusqlite: Ergonomic bindings to SQLite for Rust.