https://github.com/veeso/wasm-dbms
IC DBMS Canister is an Internet Computer framework which provides an easy way to implement a database canister by just providing the database schema.
https://github.com/veeso/wasm-dbms
canister dfinity icp internet-computer
Last synced: 3 months ago
JSON representation
IC DBMS Canister is an Internet Computer framework which provides an easy way to implement a database canister by just providing the database schema.
- Host: GitHub
- URL: https://github.com/veeso/wasm-dbms
- Owner: veeso
- License: mit
- Created: 2025-11-12T20:42:37.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2026-03-27T09:34:09.000Z (3 months ago)
- Last Synced: 2026-03-27T09:43:01.181Z (3 months ago)
- Topics: canister, dfinity, icp, internet-computer
- Language: Rust
- Homepage: https://wasm-dbms.cc
- Size: 3.79 MB
- Stars: 3
- Watchers: 0
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# WASM DBMS
[](https://opensource.org/licenses/MIT)
[](https://github.com/veeso/wasm-dbms/stargazers)
[](https://crates.io/crates/wasm-dbms)
[](https://crates.io/crates/wasm-dbms)
[](https://conventionalcommits.org)
[](https://github.com/veeso/wasm-dbms/actions)
[](https://coveralls.io/github/veeso/wasm-dbms)
[](https://docs.rs/wasm-dbms)
An embeddable relational database engine written in Rust, designed to run inside WASM runtimes, with first-class support
for Internet Computer canisters.
## Overview
This repository contains three crate families:
- **wasi-dbms**: Crates for building a DBMS on any WASM runtime that supports WASI (Wasmtime, Wasmer, WasmEdge)
- **wasm-dbms** - A runtime-agnostic DBMS engine that runs on any WASM runtime (Wasmtime, Wasmer, WasmEdge, IC)
- **ic-dbms** - A thin IC-specific adapter that provides Internet Computer canister integration
### Crate Architecture
| Crate | Description |
|--------------------|-------------------------------------------------------------|
| `wasm-dbms-api` | Shared types, traits, validators, sanitizers |
| `wasm-dbms-memory` | Memory abstraction and page management |
| `wasm-dbms` | Core DBMS engine with transactions, joins, integrity checks |
| `wasm-dbms-macros` | Procedural macros: `Encode`, `Table`, `CustomDataType` |
| `wasi-dbms-memory` | Memory provider implementations for WASI runtimes |
| `ic-dbms-api` | IC-specific types (re-exports `wasm-dbms-api`) |
| `ic-dbms-canister` | IC canister DBMS implementation |
| `ic-dbms-macros` | IC-specific macro: `DbmsCanister` |
| `ic-dbms-client` | Client libraries for canister interaction |
## Quick Start (Generic)
Define your database schema using Rust structs with derive macros:
```rust
use wasm_dbms_api::prelude::*;
#[derive(Debug, Table, Clone, PartialEq, Eq)]
#[table = "users"]
pub struct User {
#[primary_key]
pub id: Uint32,
#[sanitizer(TrimSanitizer)]
#[validate(MaxStrlenValidator(100))]
pub name: Text,
#[validate(EmailValidator)]
pub email: Text,
}
```
Wire tables together with the `DatabaseSchema` macro and use the `Database` trait:
```rust
use wasm_dbms::prelude::*;
use wasm_dbms_api::prelude::*;
#[derive(DatabaseSchema)]
#[tables(User = "users")]
pub struct MySchema;
// Create a database context with any MemoryProvider
let ctx = DbmsContext::new(HeapMemoryProvider::default());
MySchema::register_tables(&ctx)?;
let database = WasmDbmsDatabase::oneshot(&ctx, MySchema);
// Insert
database.insert::(UserInsertRequest {
id: 1.into(),
name: "Alice".into(),
email: "alice@example.com".into(),
})?;
// Query
let users = database.select::(Query::builder().all().build())?;
```
The `MemoryProvider` trait abstracts storage — use `HeapMemoryProvider` for testing, `FileMemoryProvider` for
Wasmtime/WASI, or implement your own for any WASM runtime.
### Component Model (WIT)
wasm-dbms can be exposed as a [WebAssembly Component](https://component-model.bytecodealliance.org/) via a WIT
interface (`/wit/dbms.wit`), making it accessible from any Component Model host — Go, Python, JavaScript, or any
language with Component Model tooling. See the [Wasmtime example](https://wasm-dbms.cc/guides/wasmtime-example.html)
and the reference implementation in `crates/wasm-dbms/example/`.
## Quick Start (IC Canister)
Define your database schema using Rust structs:
```rust
use candid::CandidType;
use ic_dbms_api::prelude::{Text, Uint32};
use ic_dbms_canister::prelude::{DatabaseSchema, DbmsCanister, Table};
use serde::Deserialize;
#[derive(Debug, Table, CandidType, Deserialize, Clone, PartialEq, Eq)]
#[table = "users"]
pub struct User {
#[primary_key]
id: Uint64,
#[sanitizer(ic_dbms_api::prelude::TrimSanitizer)]
#[validate(ic_dbms_api::prelude::MaxStrlenValidator(20))]
name: Text,
#[validate(ic_dbms_api::prelude::EmailValidator)]
email: Text,
age: Nullable,
}
```
Define relationships between tables:
```rust
#[derive(Debug, Table, CandidType, Deserialize, Clone, PartialEq, Eq)]
#[table = "posts"]
pub struct Post {
#[primary_key]
id: Uint32,
title: Text,
content: Text,
#[foreign_key(entity = "User", table = "users", column = "id")]
author: Uint32,
}
```
> [!NOTE]
> Deriving `CandidType`, `Deserialize` and `Clone` is required for IC canister tables.
Instantiate the database canister:
```rust
#[derive(DatabaseSchema, DbmsCanister)]
#[tables(User = "users", Post = "posts")]
pub struct IcDbmsCanisterGenerator;
```
This generates a fully functional database canister with all CRUD operations.
## Generated Canister API
```candid
service : (IcDbmsCanisterArgs) -> {
acl_add_principal : (principal) -> (Result);
acl_allowed_principals : () -> (vec principal) query;
acl_remove_principal : (principal) -> (Result);
begin_transaction : () -> (nat);
commit : (nat) -> (Result);
delete_posts : (DeleteBehavior, opt Filter_1, opt nat) -> (Result_1);
delete_users : (DeleteBehavior, opt Filter_1, opt nat) -> (Result_1);
insert_posts : (PostInsertRequest, opt nat) -> (Result);
insert_users : (UserInsertRequest, opt nat) -> (Result);
rollback : (nat) -> (Result);
select_posts : (Query, opt nat) -> (Result_2) query;
select_users : (Query_1, opt nat) -> (Result_3) query;
update_posts : (PostUpdateRequest, opt nat) -> (Result_1);
update_users : (UserUpdateRequest, opt nat) -> (Result_1);
}
```
### ACL Management
- `acl_add_principal(principal)`: Adds a principal to the ACL.
- `acl_allowed_principals()`: Returns the list of principals in the ACL.
- `acl_remove_principal(principal)`: Removes a principal from the ACL.
### Transaction Management
- `begin_transaction()`: Starts a new transaction and returns its ID.
- `commit(transaction_id)`: Commits the transaction with the given ID.
- `rollback(transaction_id)`: Rolls back the transaction with the given ID.
### Data Manipulation
For each table defined in the schema:
- `insert_(records, transaction_id)`: Inserts records into the specified table.
- `select_(query, transaction_id)`: Selects records from the specified table.
- `update_(updates, transaction_id)`: Updates records in the specified table.
- `delete_(delete_behavior, filter, transaction_id)`: Deletes records from the specified table.
## Getting Started
See the [Getting Started Guide](https://wasm-dbms.cc/guides/get-started.html) for more information on how to setup and
deploy the DBMS canister.
## Interacting with the Canister
See the [ic-dbms-client](./crates/ic-dbms/ic-dbms-client/README.md) for more information on how to interact with the
canister.
## Features
- [x] Define tables with common attributes
- [x] CRUD operations
- [x] Complex queries with filtering and pagination
- [x] Relationships between tables with foreign keys
- [x] Transactions with commit and rollback
- [x] Access Control Lists (ACL) to restrict access to the database
- [x] Validation, Sanitizers and constraints on table columns
- [x] JOIN operations between tables
- [x] Custom data types
- [x] Runtime-agnostic core (wasm-dbms) for any WASM runtime
- [x] Indexes for faster queries
- [ ] Migrations to update the database schema on canister upgrades
- [ ] SQL query support
## Documentation
Read the documentation at
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.