https://github.com/veeso/ic-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/ic-dbms
canister dfinity icp internet-computer
Last synced: 11 days 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/ic-dbms
- Owner: veeso
- License: mit
- Created: 2025-11-12T20:42:37.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2025-12-12T17:45:52.000Z (3 months ago)
- Last Synced: 2025-12-19T18:55:12.231Z (3 months ago)
- Topics: canister, dfinity, icp, internet-computer
- Language: Rust
- Homepage: https://veeso.github.io/ic-dbms/
- Size: 3.34 MB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-internet-computer - ic-dbms - An Internet Computer framework which provides an easy way to implement a database canister by just providing the database schema (Storage and Databases / Candid implementations)
README
# IC DBMS Canister
[](https://opensource.org/licenses/MIT)
[](https://github.com/veeso/ic-dbms/stargazers)
[](https://crates.io/crates/ic-dbms-canister)
[](https://crates.io/crates/ic-dbms-canister)
[](https://ko-fi.com/veeso)
[](https://conventionalcommits.org)
[](https://github.com/veeso/ic-dbms/actions)
[](https://coveralls.io/github/veeso/ic-dbms)
[](https://docs.rs/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:
```rust
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,
#[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,
}
```
You can also 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]
> 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:
```rust
#[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:
```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);
}
```
## 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_(records, transaction_id)`: Inserts records into the specified table. Optionally within a transaction.
- `select_(query, transaction_id)`: Selects records from the specified table based on the query. Optionally within a transaction.
- `update_(updates, transaction_id)`: Updates records in the specified table. Optionally within a transaction.
- `delete_(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](https://veeso.github.io/ic-dbms/docs/get-started.html) for more information on how to setup and deploy the DBMS canister.
## Interacting with the Canister
See the [ic-dbms-client](./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
- [ ] Indexes for faster queries
- [ ] Custom data types
- [ ] 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.