How to Connect Rust to Starwift ClickHouse: A Step‑by‑Step Guide

Create Cluster

Log in to the JD Cloud console (https://console.jdcloud.com/) and create a Starwift cluster using the default configuration.

Create User

After the cluster is ready, create a database user in the Starwift console.

Enable Whitelist

To allow external access, edit the default security group and set the IP whitelist to 0.0.0.0/0 for testing (in production, restrict this appropriately).

Enable Public Connection

Open public network access to simplify development and testing.

macOS ClickHouse Client Installation

Install the ClickHouse client on macOS:

curl -O 'https://builds.clickhouse.com/master/macos/clickhouse' && chmod a +x ./clickhouse

Refer to the official ClickHouse documentation for other platforms.

Test Connectivity

Verify the connection using the client:

clickhouse-client --host service-terrabase-9s29mdlsb7.terrabase-9s2mdsb-hb-public.jvessel2.jdcloud.com --port 9000 \
--user sample \
--password xxxxxx

clickhouse:) show databases

Rust Connect to Starwift

Starwift supports both TCP and HTTP protocols. Below are example Rust projects for each.

TCP Connection

Add the following dependencies to Cargo.toml:

# clickhouse tcp
tokio = { version = "1.21.2", features = ["full"] }
clickhouse-rs = { git = "https://github.com/suharev7/clickhouse-rs", features = ["default"] }

Example code:

use clickhouse_rs::Pool;

#[tokio::main]
async fn main() {
    let database_url = "tcp://username:password@service-terrabase-9s29mdlsb7.terrabase-9s2mdsb-hb-public.jvessel2.jdcloud.com:9000?compression=lz4".to_string();
    let pool = Pool::new(database_url);
    let mut client = pool.get_handle().await.unwrap();
    let sql = "show databases;";
    let r = client.query(sql).fetch_all().await;
    println!("result is: {:?}", r);
}

HTTP Connection

Add the following dependency:

# clickhouse http
clickhouse = { git = "https://github.com/loyd/clickhouse.rs", features = ["test-util"] }

Example code:

use clickhouse::Client;
use clickhouse::Row;
use serde::{Deserialize, Serialize};

#[derive(Debug, Row, Serialize, Deserialize)]
struct Database {
    name: String,
}

#[tokio::main]
async fn main() {
    let client = Client::default()
        .with_url("https://service-terrabase-9s29mdlsb7.terrabase-9sdlb7-hb-public.jvessel2.jdcloud.com:8123")
        .with_user("username")
        .with_password("password");
    let sql = "SHOW databases";
    let r = client.query(sql).fetch_all::<Database>().await;
    println!("result is: {:?}", r);
}

During testing, a dependency conflict arose because clickhouse-rs and clickhouse.rs both depend on different versions of clickhouse-rs-cityhash-sys, causing compilation failures. Future posts will detail the troubleshooting steps.

Thanks to the JD Cloud database team for providing the Starwift test instance.