# 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,
name: Text,
email: Text,
age: Nullable<Uint32>,
}
```
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_<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](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
- [ ] 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](https://veeso.github.io/ic-dbms/docs/memory.html)
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.