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

ic_dbms_client/
lib.rs
