ic_dbms_client/
lib.rs

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

ic_dbms_client/
lib.rs
