ic-dbms-client

This crate exposes all the types which may be used by an external canister to interact with an IC DBMS Canister instance.

Client

All the client methods can be accessed through the Client trait.

The crate provides an implementation of the client for IC DBMS Canister, called IcDbmsCanisterClient, which can be used on ic canisters.

If you want to use the client in integration tests with pocket-ic, you can use the IcDbmsPocketIcClient implementation, but first you need to enable the pocket-ic feature.

If you want to use the client from external systems (such as frontend applications, backend services, or CLI tools), you can use the IcDbmsAgentClient implementation, which requires the ic-agent feature.

Usage

Add the dependencies

[dependencies]
candid = "0.10"
ic-dbms-api = "0.1"
ic-dbms-client = "0.1"
serde = "1"

Implement the record types

You can define your table as you did for the database, or use a common crate to share the types between the canisters.

use candid::{CandidType, Principal};
use ic_dbms_api::prelude::{Nullable, Query, Table, TableSchema, Text, Uint32, Uint64};
use ic_dbms_client::prelude::{Client as _, IcDbmsCanisterClient};
use serde::Deserialize;

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

Use the client


async fn main() -> anyhow::Result<()> {
    let principal = Principal::from_text("...")?;
    let client = IcDbmsCanisterClient::new(principal);

    let alice = UserInsertRequest {
        id: 1.into(),
        name: "Alice".into(),
        email: "alice@example.com".into(),
        age: Nullable::Value(30.into()),
    };

    client
        .insert::<User>(User::table_name(), alice, None)
        .await?;
}

Use the client from external systems (ic-agent)

If you want to use the client from external systems (such as frontend applications, backend services, or CLI tools), you need to enable the ic-agent feature and use the IcDbmsAgentClient implementation.

[dependencies]
ic-dbms-client = { version = "0.1", features = ["ic-agent"] }
ic-agent = "0.45"

use candid::Principal;
use ic_agent::Agent;
use ic_dbms_client::prelude::{Client as _, IcDbmsAgentClient};

async fn main() -> anyhow::Result<()> {
    let agent = Agent::builder()
        .with_url("https://ic0.app")
        .build()?;

    let canister_id = Principal::from_text("...")?;
    let client = IcDbmsAgentClient::new(&agent, canister_id);

    let alice = UserInsertRequest {
        id: 1.into(),
        name: "Alice".into(),
        email: "alice@example.com".into(),
        age: Nullable::Value(30.into()),
    };

    client
        .insert::<User>(User::table_name(), alice, None)
        .await?;
}

Available Clients

IcDbmsCanisterClient: Client implementation for IC canisters.
IcDbmsAgentClient: Client implementation for external systems (frontend, backend services, CLI tools) using ic-agent. Requires the ic-agent feature.
IcDbmsPocketIcClient: Client implementation for pocket-ic integration tests. Requires the pocket-ic feature.

Available Methods

All the client methods are defined in the Client trait.

acl_add_principal
acl_remove_principal
acl_allowed_principals
begin_transaction
commit
rollback
select
insert
update
delete

Available Types

You can import all the useful types and traits by using the prelude module:

use ic_dbms_client::prelude::*;

Query

Table

Types

Value

Value

License

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

ic-dbms-client 0.4.0