Vendor sqlite-wasm-rs 0.3.0

Cargo.toml

@@ -55,3 +55,6 @@ wasm-bindgen-test = "0.3"
 [profile.release]
 opt-level = "z"
 lto = true
+
+[patch.crates-io]
+sqlite-wasm-rs = { path = "vendor/sqlite-wasm-rs" }

vendor/sqlite-wasm-rs/Cargo.toml

@@ -0,0 +1,116 @@
+# THIS FILE IS AUTOMATICALLY GENERATED BY CARGO
+#
+# When uploading crates to the registry Cargo will automatically
+# "normalize" Cargo.toml files for maximal compatibility
+# with all versions of Cargo and also rewrite `path` dependencies
+# to registry (e.g., crates.io) dependencies.
+#
+# If you are reading this file be aware that the original Cargo.toml
+# will likely look very different (and much more reasonable).
+# See Cargo.toml.orig for the original contents.
+
+[package]
+edition = "2021"
+name = "sqlite-wasm-rs"
+version = "0.3.0"
+authors = ["Spxg <unsafe@outlook.es>"]
+build = "build.rs"
+autolib = false
+autobins = false
+autoexamples = false
+autotests = false
+autobenches = false
+description = "Provide sqlite solution for wasm32-unknown-unknown target."
+readme = "README.md"
+keywords = [
+    "sqlite",
+    "sqlite-wasm",
+    "wasm",
+    "webassembly",
+    "javascript",
+]
+categories = [
+    "development-tools::ffi",
+    "wasm",
+    "database",
+]
+license = "MIT"
+repository = "https://github.com/Spxg/sqlite-wasm-rs"
+
+[package.metadata.docs.rs]
+targets = ["wasm32-unknown-unknown"]
+
+[features]
+buildtime-bindgen = ["bindgen"]
+bundled = ["xshell"]
+custom-libc = ["sqlite-wasm-libc"]
+default = ["bundled"]
+precompiled = []
+
+[lib]
+name = "sqlite_wasm_rs"
+path = "src/lib.rs"
+
+[[test]]
+name = "main"
+path = "tests/main.rs"
+
+[dependencies.fragile]
+version = "2.0.0"
+
+[dependencies.js-sys]
+version = "0.3.76"
+
+[dependencies.once_cell]
+version = "1.20.2"
+
+[dependencies.sqlite-wasm-libc]
+version = "0.1.0"
+optional = true
+
+[dependencies.thiserror]
+version = "2.0.11"
+
+[dependencies.tokio]
+version = "1.42.0"
+features = ["sync"]
+
+[dependencies.wasm-bindgen]
+version = "0.2.99"
+
+[dependencies.wasm-bindgen-futures]
+version = "0.4.49"
+
+[dependencies.web-sys]
+version = "0.3.77"
+features = [
+    "Performance",
+    "Window",
+    "Navigator",
+    "StorageManager",
+    "FileSystemSyncAccessHandle",
+    "FileSystemDirectoryHandle",
+    "FileSystemGetDirectoryOptions",
+    "FileSystemReadWriteOptions",
+    "SharedWorkerGlobalScope",
+    "ServiceWorkerGlobalScope",
+    "WorkerGlobalScope",
+    "WorkerNavigator",
+    "FileSystemGetFileOptions",
+    "FileSystemFileHandle",
+    "Url",
+]
+
+[dev-dependencies.wasm-bindgen-test]
+version = "0.3.49"
+
+[build-dependencies.bindgen]
+version = "0.71"
+optional = true
+
+[build-dependencies.xshell]
+version = "0.2.7"
+optional = true
+
+[target.'cfg(target_feature = "atomics")'.dependencies.parking_lot]
+version = "0.12.3"

vendor/sqlite-wasm-rs/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Spxg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vendor/sqlite-wasm-rs/README.md

@@ -0,0 +1,103 @@
+# SQLite Wasm Rust
+
+[![Crates.io](https://img.shields.io/crates/v/sqlite-wasm-rs.svg)](https://crates.io/crates/sqlite-wasm-rs)
+
+Provide sqlite solution for `wasm32-unknown-unknown` target.
+
+## Usage
+
+```toml
+[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"
+```
+
+```toml
+[dependencies]
+# using precompiled binaries
+sqlite-wasm-rs = { version = "0.3", default-features = false, features = ["precompiled"] }
+```
+
+```rust
+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`](https://github.com/rustwasm/wasm-bindgen/pull/955) for details.
+* sqlite is compiled with `-DSQLITE_THREADSAFE=0`
+
+## About VFS
+
+The following vfs have been implemented:
+
+* [`memory-vfs`](https://github.com/Spxg/sqlite-wasm-rs/blob/master/sqlite-wasm-rs/src/shim/vfs/memory.rs): as the default vfs, no additional conditions are required, just use.
+* [`opfs-sahpool`](https://github.com/Spxg/sqlite-wasm-rs/blob/master/sqlite-wasm-rs/src/shim/vfs/sahpool.rs): 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`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-links-field) field that can be used to specify which library to link to.
+
+We created a new [`sqlite-wasm-libc`](https://github.com/Spxg/sqlite-wasm-rs/tree/master/sqlite-wasm-libc) library with no implementation and only a `links = "libc"` configuration.
+
+Then with the help of [`Overriding Build Scripts`](https://doc.rust-lang.org/cargo/reference/build-scripts.html#overriding-build-scripts), you can overriding its configuration in your crate and link sqlite to your custom libc.
+
+More see [`custom-libc example`](https://github.com/Spxg/sqlite-wasm-rs/tree/master/examples/custom-libc).
+
+## 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`](https://github.com/sqlite/sqlite-wasm): SQLite Wasm conveniently wrapped as an ES Module.
+* [`sqlite-web-rs`](https://github.com/xmtp/sqlite-web-rs): A SQLite WebAssembly backend for Diesel.
+* [`rusqlite`](https://github.com/rusqlite/rusqlite): Ergonomic bindings to SQLite for Rust.

vendor/sqlite-wasm-rs/VFS.md

@@ -0,0 +1,91 @@
+# memory
+
+Data is stored in memory, this is the default vfs
+
+```rust
+use sqlite_wasm_rs::export as ffi;
+
+// 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);
+```
+
+# opfs-sahpool
+
+Persistent vfs, ported from sqlite-wasm, see <https://sqlite.org/wasm/doc/trunk/persistence.md#vfs-opfs-sahpool> for details
+
+```rust
+use sqlite_wasm_rs::export::{self as ffi, install_opfs_sahpool};
+
+// 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);
+
+let mut db = std::ptr::null_mut();
+let ret = unsafe {
+    ffi::sqlite3_open_v2(
+        c"file:opfs-sahpool.db?vfs=opfs-sahpool".as_ptr().cast(),
+        &mut db as *mut _,
+        ffi::SQLITE_OPEN_READWRITE | ffi::SQLITE_OPEN_CREATE,
+        std::ptr::null()
+    )
+};
+assert_eq!(ffi::SQLITE_OK, ret);
+
+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,
+        c"opfs-sahpool".as_ptr().cast()
+    )
+};
+assert_eq!(ffi::SQLITE_OK, ret);
+```
+
+Support custom vfs and directory
+
+```rust
+use sqlite_wasm_rs::export::{
+    self as ffi,
+    install_opfs_sahpool,
+    OpfsSAHPoolCfgBuilder
+};
+
+let cfg = OpfsSAHPoolCfgBuilder::new()
+    .vfs_name("custom-vfs")
+    .directory("custom/abc")
+    .build();
+install_opfs_sahpool(Some(&cfg), true).await?;
+
+let mut db = std::ptr::null_mut();
+let ret = unsafe {
+    ffi::sqlite3_open_v2(
+        c"custom-vfs.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);
+```