ic_dbms_client/
lib.rs

1#![crate_name = "ic_dbms_client"]
2#![crate_type = "lib"]
3#![cfg_attr(docsrs, feature(doc_cfg))]
4#![deny(clippy::print_stdout)]
5#![deny(clippy::print_stderr)]
6
7//! # IC DBMS Client
8//!
9//! This crate exposes all the types which may be used by an external canister to interact with
10//! an IC DBMS Canister instance.
11//!
12//! ## Available Clients
13//!
14//! - [`IcDbmsCanisterClient`](crate::prelude::IcDbmsCanisterClient): Client implementation to be used inside IC canisters.
15//! - [`IcDbmsAgentClient`](crate::prelude::IcDbmsAgentClient): Client implementation for external systems (frontend, backend services, CLI tools) using `ic-agent`. Requires the `ic-agent` feature.
16//! - [`IcDbmsPocketIcClient`](crate::prelude::IcDbmsPocketIcClient): Client implementation to be used in integration tests with the `pocket-ic` feature enabled.
17//!
18//! The generic interface is provided by the [`Client`](crate::prelude::Client) trait.
19//!
20//! ## Available Types
21//!
22//! You can import all the useful types and traits by using the prelude module:
23//!
24//! ```rust
25//! use ic_dbms_client::prelude::*;
26//! ```
27//!
28//! ### Query
29//!
30//! - [`AggregateFunction`](crate::prelude::AggregateFunction)
31//! - [`AggregatedRow`](crate::prelude::AggregatedRow)
32//! - [`AggregatedValue`](crate::prelude::AggregatedValue)
33//! - [`DeleteBehavior`](crate::prelude::DeleteBehavior)
34//! - [`Filter`](crate::prelude::Filter)
35//! - [`JsonCmp`](crate::prelude::JsonCmp)
36//! - [`JsonFilter`](crate::prelude::JsonFilter)
37//! - [`Query`](crate::prelude::Query)
38//! - [`QueryBuilder`](crate::prelude::QueryBuilder)
39//! - [`OrderDirection`](crate::prelude::OrderDirection)
40//! - [`Select`](crate::prelude::Select)
41//!
42//! ### Table
43//!
44//! - [`ColumnDef`](crate::prelude::ColumnDef)
45//! - [`ForeignKeyDef`](crate::prelude::ForeignKeyDef)
46//! - [`InsertRecord`](crate::prelude::InsertRecord)
47//! - [`TableColumns`](crate::prelude::TableColumns)
48//! - [`TableError`](crate::prelude::TableError)
49//! - [`TableRecord`](crate::prelude::TableRecord)
50//! - [`UpdateRecord`](crate::prelude::UpdateRecord)
51//! - [`ValuesSource`](crate::prelude::ValuesSource)
52//!
53//! ### Types
54//!
55//! - [`Blob`](crate::prelude::Blob)
56//! - [`Boolean`](crate::prelude::Boolean)
57//! - [`Date`](crate::prelude::Date)
58//! - [`DateTime`](crate::prelude::DateTime)
59//! - [`Decimal`](crate::prelude::Decimal)
60//! - [`Int8`](crate::prelude::Int8)
61//! - [`Int16`](crate::prelude::Int16)
62//! - [`Int32`](crate::prelude::Int32)
63//! - [`Int64`](crate::prelude::Int64)
64//! - [`Json`](crate::prelude::Json)
65//! - [`Nullable`](crate::prelude::Nullable)
66//! - [`Principal`](crate::prelude::Principal)
67//! - [`Text`](crate::prelude::Text)
68//! - [`Uint8`](crate::prelude::Uint8)
69//! - [`Uint16`](crate::prelude::Uint16)
70//! - [`Uint32`](crate::prelude::Uint32)
71//! - [`Uint64`](crate::prelude::Uint64)
72//! - [`Uuid`](crate::prelude::Uuid)
73//!
74//! ### Value
75//!
76//! - [`Value`](crate::prelude::Value)
77//!
78//! ## Interact with an IC DBMS Canister
79//!
80//! ## Client
81//!
82//! All the client methods can be accessed  through the [`Client`](crate::prelude::Client) trait.
83//!
84//! The crate provides an implementation of the client for IC DBMS Canister, called [`IcDbmsCanisterClient`](crate::prelude::IcDbmsCanisterClient),
85//! which can be used on ic canisters.
86//!
87//! If you want to use the client in integration tests with `pocket-ic`, you can use the
88//! [`IcDbmsPocketIcClient`](crate::prelude::IcDbmsPocketIcClient) implementation, but first you need to enable the `pocket-ic` feature.
89//!
90//! If you want to use the client from external systems (such as frontend applications, backend services, or CLI tools),
91//! you can use the [`IcDbmsAgentClient`](crate::prelude::IcDbmsAgentClient) implementation, which requires the `ic-agent` feature.
92//!
93//! ## Usage
94//!
95//! ### Add the dependencies
96//!
97//! ```toml
98//! [dependencies]
99//! candid = "0.10"
100//! ic-dbms-api = "0.1"
101//! ic-dbms-client = "0.1"
102//! serde = "1"
103//! ```
104//!
105//! ### Implement the record types
106//!
107//! You can define your table as you did for the database, or use a common crate to share the types between the canisters.
108//!
109//! ```rust,ignore
110//! use candid::{CandidType, Principal};
111//! use ic_dbms_api::prelude::{Nullable, Query, Table, TableSchema, Text, Uint32, Uint64};
112//! use ic_dbms_client::prelude::{Client as _, IcDbmsCanisterClient};
113//! use serde::Deserialize;
114//!
115//! #[derive(Table, CandidType, Clone, Deserialize)]
116//! #[table = "users"]
117//! pub struct User {
118//!     #[primary_key]
119//!     id: Uint64,
120//!     name: Text,
121//!     email: Text,
122//!     age: Nullable<Uint32>,
123//! }
124//! ```
125//!
126//! ### Use the client
127//!
128//! ```rust,ignore
129//! let principal = Principal::from_text("...")?;
130//! let client = IcDbmsCanisterClient::new(principal);
131//!
132//! let alice = UserInsertRequest {
133//!     id: 1.into(),
134//!     name: "Alice".into(),
135//!     email: "alice@example.com".into(),
136//!     age: Nullable::Value(30.into()),
137//! };
138//!
139//! client
140//!     .insert::<User>(User::table_name(), alice, None)
141//!     .await?;
142//! ```
143//!
144
145#![doc(html_playground_url = "https://play.rust-lang.org")]
146#![doc(
147    html_favicon_url = "https://raw.githubusercontent.com/veeso/wasm-dbms/main/assets/images/cargo/logo-128.png"
148)]
149#![doc(
150    html_logo_url = "https://raw.githubusercontent.com/veeso/wasm-dbms/main/assets/images/cargo/logo-512.png"
151)]
152
153mod client;
154mod errors;
155pub mod prelude;
156mod utils;
ic_dbms_client/lib.rs

ic_dbms_client/
lib.rs
