clickhouse_utils/lib.rs
1//! Clickhouse Utils
2//!
3//! This crate provides a set of utilities for working with Clickhouse.
4//!
5//! # Features
6//!
7//! - fastnum: Enable support for Fastnum D256.
8//!
9//! # Usage
10//!
11//! ## Migration
12//!
13//! create a migrations folder in your project and add your migrations files.
14//! Example:
15//! ```text
16//! migrations/
17//! ├── 0001_create_users_table.sql
18//! └── 0002_add_email_column.sql
19//! ```
20//!
21//! Run the migrations:
22//! ```rust,no_run
23//! #[tokio::main]
24//! async fn main() {
25//! let client = clickhouse::Client::default()
26//! .with_user("default")
27//! .with_password("default")
28//! .with_url("http://localhost:8123")
29//! .with_database("default");
30//!
31//! clickhouse_utils::migrate(&client).await.expect("failed to run migrations");
32//! }
33//! ```
34//!
35//! ## Serde
36//!
37//! Serialize and Deserialize common types for Clickhouse.
38//!
39//! - Std Hashmap of <String, String>
40//! - Fastnum : any decimals with a fix size scale mandated by the clickhouse schema
41//!
42//! ## Examples
43//!
44//! ```rust,no_run
45//! use std::collections::HashMap;
46//!
47//! use serde::{Deserialize, Serialize};
48//! use fastnum::decimal::D256;
49//!
50//! #[derive(Debug, Serialize, Deserialize, clickhouse::Row)]
51//! pub struct SomeTable {
52//! #[serde(with = "clickhouse_utils::serde::fastnum::Decimal::<25, {256 / 64}>")]
53//! pub decimal: D256,
54//! #[serde(with = "clickhouse_utils::serde::map")]
55//! pub attributes: HashMap<String, String>,
56//! }
57//!
58//!
59//! For the decimal fastnum::D256, we use:
60//! - Decimal with { 256 / 64 } or Uint<4>
61//! - 25 decimals, that should corelate with you clickhouse schema
62//!
63//! The database schema used:
64//! ```sql
65//! CREATE TABLE clickhouse_utils (
66//! decimal Decimal256(25),
67//! attributes Map(String, String),
68//! ) ENGINE = MergeTree()
69//! ORDER BY (decimal)
70//! ```
71//! ```
72
73mod error;
74mod migration;
75pub mod serde;
76
77pub use error::ClickhouseUtilsError;
78pub use migration::migrate;