技能 数据科学 ClickHouse客户端配置与认证

ClickHouse客户端配置与认证

v20260423
clickhouse-install-auth
本技能详细指导如何配置和认证官方ClickHouse客户端(支持Node.js和Python)。覆盖了连接ClickHouse Cloud或自建服务器的全部流程,包括环境配置、关键环境参数设置和代码实现,适用于进行数据分析项目或构建数据管道。
获取技能
231 次下载
概览

ClickHouse Install & Auth

Overview

Set up the official ClickHouse client for Node.js or Python and configure authentication
to ClickHouse Cloud or a self-hosted instance.

Prerequisites

  • Node.js 18+ or Python 3.8+
  • A running ClickHouse instance (Cloud or self-hosted)
  • Connection credentials (host, port, user, password)

Instructions

Step 1: Install the Official Client

# Node.js — official client (HTTP-based, supports streaming)
npm install @clickhouse/client

# Python — official client
pip install clickhouse-connect

Step 2: Configure Environment Variables

# .env (NEVER commit — add to .gitignore)
CLICKHOUSE_HOST=https://abc123.us-east-1.aws.clickhouse.cloud:8443
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=your-password-here

# Self-hosted (HTTP interface on port 8123, native on 9000)
# CLICKHOUSE_HOST=http://localhost:8123

Step 3: Create the Client (Node.js)

import { createClient } from '@clickhouse/client';

// ClickHouse Cloud
const client = createClient({
  url: process.env.CLICKHOUSE_HOST,           // https://<host>:8443
  username: process.env.CLICKHOUSE_USER,       // default
  password: process.env.CLICKHOUSE_PASSWORD,
  // ClickHouse Cloud requires TLS — the client handles it via https:// URL
});

// Self-hosted (no TLS)
const localClient = createClient({
  url: 'http://localhost:8123',
  username: 'default',
  password: '',
});

Step 4: Verify Connection

async function verifyConnection() {
  // Ping returns true if the server is reachable
  const alive = await client.ping();
  console.log('ClickHouse ping:', alive.success);  // true

  // Run a test query
  const rs = await client.query({
    query: 'SELECT version() AS ver, uptime() AS uptime_sec',
    format: 'JSONEachRow',
  });
  const rows = await rs.json<{ ver: string; uptime_sec: number }>();
  console.log('Server version:', rows[0].ver);
  console.log('Uptime (sec):', rows[0].uptime_sec);
}

verifyConnection().catch(console.error);

Step 5: Python Alternative

import clickhouse_connect

client = clickhouse_connect.get_client(
    host='abc123.us-east-1.aws.clickhouse.cloud',
    port=8443,
    username='default',
    password='your-password-here',
    secure=True,
)

result = client.query('SELECT version(), uptime()')
print(f"Version: {result.result_rows[0][0]}")

Connection Options Reference

OptionDefaultDescription
urlhttp://localhost:8123Full URL including protocol and port
usernamedefaultClickHouse user
password''User password
databasedefaultDefault database for queries
request_timeout30000Query timeout in ms
compression.requestfalseCompress request bodies (gzip)
compression.responsetrueDecompress responses
max_open_connections10HTTP keep-alive pool size
clickhouse_settings{}Server-side settings per session

ClickHouse Cloud vs Self-Hosted

FeatureCloudSelf-Hosted
Port8443 (HTTPS)8123 (HTTP) / 8443 (HTTPS)
TLSRequiredOptional
EngineSharedMergeTreeMergeTree family
AuthUser/password, Cloud API keysUser/password, LDAP, Kerberos

Error Handling

ErrorCauseSolution
ECONNREFUSEDServer not runningCheck host/port, verify ClickHouse is up
Authentication failedWrong user/passwordVerify credentials in ClickHouse users.xml or Cloud console
CERTIFICATE_VERIFY_FAILEDTLS mismatchUse https:// for Cloud, check CA certs for self-hosted
TIMEOUTNetwork/firewallCheck IP allowlists in Cloud console, firewall rules
Database not foundWrong database nameRun SHOW DATABASES to list available databases

Resources

Next Steps

Proceed to clickhouse-hello-world for your first table and query.

信息
分类 数据科学
名称 clickhouse-install-auth
版本 v20260423
大小 4.84KB
更新时间 2026-04-27
语言