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. The workflow below is the high-level path; each step links to a full walkthrough with complete code in references/implementation.md.

Prerequisites

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

Instructions

Follow these five steps. Read the current project for an existing .env before writing one; write credentials to .env (never commit it).

Install the official client. Node.js uses the HTTP-based @clickhouse/client; Python uses clickhouse-connect.
```
npm install @clickhouse/client   # Node.js
pip install clickhouse-connect   # Python
```
Configure environment variables. Put host, user, and password in .env and add it to .gitignore. Cloud hosts use port 8443 (HTTPS); self-hosted uses 8123 (HTTP).

Create the client. Pass url, username, and password to createClient() (Node.js) or get_client() (Python). Cloud requires TLS — supply an https:// URL and the client handles it.

import { createClient } from '@clickhouse/client';
const client = createClient({
  url: process.env.CLICKHOUSE_HOST,
  username: process.env.CLICKHOUSE_USER,
  password: process.env.CLICKHOUSE_PASSWORD,
});

Verify the connection with client.ping() plus a SELECT version() probe.
Python alternative — same shape via clickhouse_connect.get_client(...) with secure=True for Cloud.

Full code for every step (Cloud + self-hosted variants, the verify routine, and the Python client): references/implementation.md. Every createClient() option and a Cloud-vs-self-hosted comparison: references/connection-reference.md.

Output

After completing the workflow you have:

The official client installed (@clickhouse/client or clickhouse-connect).
A .env holding CLICKHOUSE_HOST / CLICKHOUSE_USER / CLICKHOUSE_PASSWORD (gitignored).
An initialized client module that reads those variables.
A successful ping() returning success: true and a SELECT version() probe printing the server version and uptime — proof the connection and auth both work.

Error Handling

Error	Cause	Solution
`ECONNREFUSED`	Server not running	Check host/port, verify ClickHouse is up
`Authentication failed`	Wrong user/password	Verify credentials in ClickHouse users.xml or Cloud console
`CERTIFICATE_VERIFY_FAILED`	TLS mismatch	Use `https://` for Cloud, check CA certs for self-hosted
`TIMEOUT`	Network/firewall	Check IP allowlists in Cloud console, firewall rules
`Database not found`	Wrong database name	Run `SHOW DATABASES` to list available databases

Examples

Connect to ClickHouse Cloud (Node.js). With .env populated, create the client against the https://…:8443 host and verify:

const alive = await client.ping();        // { success: true }
const rs = await client.query({
  query: 'SELECT version() AS ver',
  format: 'JSONEachRow',
});
console.log((await rs.json())[0].ver);    // e.g. "24.8.1"

Connect to a local self-hosted instance (no TLS). Point at the HTTP interface on 8123 with an empty password:

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

The full Cloud + self-hosted + Python set is in references/implementation.md.

Resources

Next Steps

Proceed to clickhouse-hello-world to create your first table and run an insert-and-select round trip against the connection you just verified.

clickhouse-install-auth