ic-rusqlite

This is a convenience package to create a canister with the Sqlite support.

Prerequisites

It is assumed that you have rust, dfx.

To compile a project with this dependency, you will need to:

• install wasi2ic: cargo install wasi2ic
• install WASI target: rustup target add wasm32-wasip1

Compiling

If you intend to compile the SQLite from the source, you will need to install WASI-SDK:

• install WASI-SDK and WASI-oriented clang: WASI-SDK.
• Finally, set the WASI_SDK_PATH and PATH variables:

export WASI_SDK_PATH=/opt/wasi-sdk
export PATH=$WASI_SDK_PATH/bin:$PATH

You can automate this by launching the preparation script:

curl -fsSL https://raw.githubusercontent.com/wasm-forge/ic-rusqlite/main/prepare.sh | sh

Finally, to enable rusqlite in your canister, add the helper dependency into your backend canister:

cargo add ic-rusqlite

Using Precompiled SQLite

If you don't want to install WASI-SDK, you can use the precompiled SQLite version for WASI, just activate the precompiled feature and disable the default features:

cargo add ic-rusqlite --no-default-features --features precompiled

Developing casniter

You will need to update the dfx.json to specify path to wasm, set type to custom, and specify custom build steps to enforce compilation to the wasm32-wasip1 target. Finally, use wasi2ic to produce wasm executable on the Internet Computer.

Example:

{
  "canisters": {
    "backend": {
      "candid": "can.did",
      "package": "backend",
      "build": [
        "cargo build --release --target wasm32-wasip1",
        "wasi2ic target/wasm32-wasip1/release/backend.wasm target/wasm32-wasip1/release/backend_nowasi.wasm"
      ],
      "wasm": "target/wasm32-wasip1/release/backend_nowasi.wasm",
      "type": "custom",
      "metadata": [
        {
          "name": "candid:service"
        }
      ]
    }
  },
  "dfx": "0.28.0",
  "version": 1
}

Example use in your Rust code

Finally, use the with_connection() function to access your database:

    //...
    
    with_connection(|conn| {
      conn.execute(
          "CREATE TABLE person (
              id    INTEGER PRIMARY KEY,
              name  TEXT NOT NULL,
              data  BLOB
          )",
          (),
      )?;

      let data: Option<Vec<u8>> = None;

      conn.execute(
          "INSERT INTO person (name, data) VALUES (?1, ?2)",
          ("Steven", &data),
      )?;

    })


    //...

Further examples

You can find a small example in the "examples/backend" folder.

For more detailed explanations, see the ic-rusqlite book.