ic-rusqlite 0.5.0

The project provides easy-to-use library to enable SQLite in your Internet Computer canister.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106

# ic-rusqlite
This is a convenience package to create a canister with the Sqlite support. 


## Prerequisites

It is assumed that you have [rust](https://doc.rust-lang.org/book/ch01-01-installation.html), [dfx](https://internetcomputer.org/docs/current/developer-docs/setup/install/).

To compile a project with this dependency, you will need to:
- install wasi2ic: `cargo install wasi2ic`
- install WASI target: `rustup target add wasm32-wasip1`


## 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:
```sh
cargo add ic-rusqlite --features precompiled
```

## Compiling SQLite

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](https://github.com/WebAssembly/wasi-sdk/releases/). 
- set the `WASI_SDK_PATH` and `PATH` variables:
```bash
export WASI_SDK_PATH=/opt/wasi-sdk
export PATH=$WASI_SDK_PATH/bin:$PATH
```

You can automate this by launching the preparation script:
```sh
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:
```bash
cargo add ic-rusqlite --features compile_sqlite
```

## Developing Canister

You will need to update the `dfx.json` and 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:
```json
{
  "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"
        }
      ]
    }
  },
  "version": 1
}
```

## Example

Use the `with_connection()` function to access your database:

```rust
    //...
    
    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

* A minimal example is available in the `"examples/backend"` folder.
* Also see the [demo Svelte canister](https://github.com/wasm-forge/ic-sqlite-svelte-demo).

For more detailed explanations, see the [`ic-rusqlite` book](https://wasm-forge.github.io/ic-rusqlite/).