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

ic_dbms_client/
lib.rs
