Wasmtime Example

• Overview
• How It Works
  • WIT Interface
  • Guest Component
  • Host Binary
• FileMemoryProvider
• Key-Value Guest Variant
• Building and Running
  • Prerequisites
  • Build
  • Run
• Extending with Custom Tables
• Key Concepts

This guide explains how to use wasm-dbms with the WebAssembly Component Model (WIT) and Wasmtime. It walks through the example in crates/wasm-dbms/example/.

Overview

The WebAssembly Component Model defines a standard way for WASM modules to expose typed interfaces using WIT (WebAssembly Interface Types). This example shows how to:

1. Define a WIT interface for the wasm-dbms CRUD and transaction API
2. Build a guest WASM component that wraps wasm-dbms behind the WIT interface
3. Run the guest inside a native Wasmtime host

This approach makes wasm-dbms usable from any Component Model host, not just Rust. The WIT contract at /wit/dbms.wit can be consumed by hosts written in Go, Python, JavaScript, or any language with Component Model tooling.

How It Works

WIT Interface

The WIT definition (/wit/dbms.wit) exposes a database interface with these operations:

• select — query rows from a table with optional filter, ordering, limit, and offset
• insert — insert a row into a table, optionally within a transaction
• update — update rows matching a filter, optionally within a transaction
• delete — delete rows matching a filter, optionally within a transaction
• begin-transaction — start a new ACID transaction
• commit / rollback — finalize or abort a transaction

Values are passed as a value variant type that covers booleans, integers, floats, strings, blobs, and null. Filters are JSON-serialized strings matching the wasm_dbms_api::Filter type.

Decimals, dates, date-times, JSON documents, and UUIDs travel as strings. The guest parses them strictly and returns an invalid-query error for a malformed value, such as 2025-02-30 or {, instead of storing a default or null value:

This raw/dynamic API is intentional: WIT cannot express Rust generics or user-defined table schemas, so type safety is enforced inside the guest by the wasm-dbms engine.

Guest Component

The guest (crates/wasm-dbms/example/guest/) compiles to wasm32-wasip2 and exports the WIT database interface. Internally it:

1. Initializes a file-backed or key-value DbmsContext lazily on first call; if storage cannot be opened or the tables cannot be registered, the call returns a dbms-error (for example memory-error) instead of trapping, and the next call retries
2. Registers example tables (users, posts) using #[derive(Table)]
3. Converts between WIT variant values and wasm-dbms Value types
4. Dispatches operations through a DatabaseSchema implementation

The bridge layer in lib.rs handles all the type conversions between the WIT boundary and the typed wasm-dbms internals.

Host Binary

The host (crates/wasm-dbms/example/host/) is a native Rust binary using Wasmtime. It:

1. Creates a Wasmtime engine with Component Model enabled
2. Creates a fresh, uniquely named directory under the system temporary directory and preopens it as the guest’s root, so the database file never touches existing data
3. Loads the guest .wasm component and instantiates it
4. Calls the exported database functions to demonstrate all operations

FileMemoryProvider

The FileMemoryProvider implements the MemoryProvider trait using std::fs file I/O. It provides persistent, file-backed storage so that data survives across invocations.

#![allow(unused)]
fn main() {
use wasm_dbms_memory::prelude::MemoryProvider;

pub struct FileMemoryProvider {
    file: File, // open file handle
    size: u64,  // current size in bytes
    pages: u64, // allocated pages (size / PAGE_SIZE)
}
}

Operations:

• grow(n) — extends the file by n × 65536 bytes
• read(offset, buf) — seeks to offset and reads into buffer
• write(offset, buf) — seeks to offset, writes buffer, and flushes

The provider is initialized with a file path relative to the WASI preopened directory (defaults to wasm-dbms.db).

Note: FileMemoryProvider does not handle concurrent access. It assumes single-writer usage.

Key-Value Guest Variant

The guest also has a key-value feature. Build and test it with:

just test_wasm_dbms_key_value_example
wasm-tools component wit .artifact/wasm-dbms-example-guest-key-value.wasm

This variant opens bucket default and database namespace example. It imports only wasi:keyvalue/store@0.2.0-draft2 and wasi:keyvalue/batch@0.2.0-draft2 for persistence; it does not require a filesystem preopen. Successful WIT operations checkpoint through ctx.flush(). The host must retain the bucket across component restarts, provide durable backing, and coordinate a single writer. See the key-value provider guide for the checkpoint and failure model.

Building and Running

Prerequisites

• Rust 1.91.1+

• wasm32-wasip2 target:

  rustup target add wasm32-wasip2
  

• just command runner

Build

# Build guest + host
just build_wasm_dbms_example

This compiles the guest to wasm32-wasip2 (producing a WASM component at .artifact/wasm-dbms-example-guest.wasm) and builds the native host binary.

Run

just test_wasm_dbms_example

Or run manually:

cargo run --release -p wasm-dbms-example-host -- .artifact/wasm-dbms-example-guest.wasm

The demo inserts users and posts, queries them with filters and ordering, demonstrates transaction commit (data persists) and rollback (data discarded), then removes the directory it created for this run. A wasm-dbms.db file in your current directory is never read, modified, or deleted.

Extending with Custom Tables

To add your own tables to the example:

1. Define the table in guest/src/schema.rs:

   #![allow(unused)]
   fn main() {
   #[derive(Debug, Table, Clone, PartialEq, Eq)]
   #[table = "comments"]
   pub struct Comment {
       #[primary_key]
       pub id: Uint32,
       pub body: Text,
       #[foreign_key(entity = "Post", table = "posts", column = "id")]
       pub post_id: Uint32,
   }
   }

2. Add dispatch arms for "comments" in every method of ExampleDatabaseSchema in guest/src/schema.rs (select, insert, update, delete, validate_insert, validate_update, referenced_tables).

3. Register the table in register_tables():

   #![allow(unused)]
   fn main() {
   ctx.register_table::<Comment>()?;
   }

4. Update the column lookup in table_columns() (guest/src/lib.rs):

   #![allow(unused)]
   fn main() {
   "comments" => Ok(schema::Comment::columns()),
   }

5. Register the table name in registered_table_names() (guest/src/lib.rs). The guest resolves caller-provided table names against this finite list, so unknown names are rejected with table-not-found and are never retained:

   #![allow(unused)]
   fn main() {
   fn registered_table_names() -> [&'static str; 3] {
       [
           schema::User::table_name(),
           schema::Post::table_name(),
           schema::Comment::table_name(),
       ]
   }
   }

6. Rebuild with just build_wasm_dbms_example.

Key Concepts

Next Steps

• Getting Started — Set up wasm-dbms from scratch with the Database trait
• CRUD Operations — Detailed guide on all database operations
• Transactions — ACID transactions with commit/rollback
• Schema Definition — Complete schema reference