IC DBMS Canister

This project is in a very early stage of development. The goal is to provide a framework for building database canisters on the Internet Computer.

Overview

IC DBMS Canister is an Internet Computer framework which provides an easy way to implement a database canister by just providing the database schema.

The user can just define the data entity by defining the tables:

use candid::CandidType;
use ic_dbms_api::prelude::{Text, Uint32};
use ic_dbms_canister::prelude::{DbmsCanister, Table};
use serde::Deserialize;

#[derive(Debug, Table, CandidType, Deserialize, Clone, PartialEq, Eq)]
#[table = "users"]
pub struct User {
    #[primary_key]
    id: Uint64,
    name: Text,
    email: Text,
    age: Nullable<Uint32>,
}

You can also define relationships between tables:

#[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] Mind that deriving CandidType, Deserialize and Clone is required for the tables to be used in the canister.

And once you have defined all your tables, you can instantiate the database canister by deriving the DbmsCanister macro on any struct, providing the table names and their corresponding Rust struct entity:

#[derive(DbmsCanister)]
#[tables(User = "users", Post = "posts")]
pub struct IcDbmsCanisterGenerator;

And you will have a fully functional database canister with all the CRUD operations implemented for you.

The canister API will be automatically generated based on the defined tables, with the following methods:

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);
}

API Documentation

The API generated by the ic-dbms-canister is the following:

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. The user must own the transaction to commit it.
• rollback(transaction_id): Rolls back the transaction with the given ID. The user must own the transaction to roll it back.

Data Manipulation

For each table defined in the schema, the following methods are generated:

• insert_<table_name>(records, transaction_id): Inserts records into the specified table. Optionally within a transaction.
• select_<table_name>(query, transaction_id): Selects records from the specified table based on the query. Optionally within a transaction.
• update_<table_name>(updates, transaction_id): Updates records in the specified table. Optionally within a transaction.
• delete_<table_name>(delete_behavior, filter, transaction_id): Deletes records from the specified table based on the filter and delete behavior. Optionally within a transaction.

Getting Started

See the Getting Started Guide for more information on how to setup and deploy the DBMS canister.

Interacting with the Canister

See the ic-dbms-client for more information on how to interact with the canister.

Features

• Define tables with common attributes
• CRUD operations
• Complex queries with filtering and pagination
• Relationships between tables with foreign keys
• Transactions with commit and rollback
• Access Control Lists (ACL) to restrict access to the database
• JOIN operations between tables (coming soon)
• Migrations to update the database schema without losing data (coming soon)
• Indexes on columns to optimize queries (coming soon)
• Custom data types (coming soon)

Documentation

• Memory Management

License

This project is licensed under the MIT License. See the LICENSE file for details.