clickhouse-js-node-coding/reference/ping.md

Ping the Server

Applies to: all versions. ping() returns a discriminated union PingResult = { success: true } | { success: false, error: Error } — it does not throw on connection failures.

Answer checklist

When answering "how do I health-check / readiness-probe ClickHouse?":

• Use await client.ping() (or ping({ select: true })) and branch on result.success directly — do not wrap in try/catch as the only check, and do not substitute query('SELECT 1').
• For a readiness probe / "can it serve traffic", recommend client.ping({ select: true }) so credentials and the query layer are validated, not just the socket.
• Always contrast the two forms explicitly in your answer, even when you're recommending one: plain client.ping() hits /ping (TCP/HTTP reachability only — does not validate credentials or query processing); client.ping({ select: true }) issues a lightweight SELECT 1 (validates auth and query path). Name both and say which to use for liveness vs readiness.
• Recommend lowering request_timeout on the client used for probes so they fail fast instead of hanging on the default timeout — pick a value comparable to the probe interval (e.g., 1500–2000 ms for a 2-second-interval probe).

Successful ping

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

const client = createClient({
  url: process.env.CLICKHOUSE_URL,
  password: process.env.CLICKHOUSE_PASSWORD,
});

const pingResult = await client.ping();
if (pingResult.success) {
  console.info("ClickHouse is reachable");
} else {
  console.error("Ping failed:", pingResult.error);
}
await client.close();

Use ping() to:

• Probe ClickHouse at application startup.
• Wake up a ClickHouse Cloud instance that may be idling (a ping is enough to bring it out of sleep).
• Implement a /healthz / readiness endpoint.

Failure: host unreachable

ping() does not throw — it resolves with { success: false, error: Error }, so you can branch without try/catch:

import type { PingResult } from "@clickhouse/client";
import { createClient } from "@clickhouse/client";

const client = createClient({
  url: "http://localhost:8100", // non-existing host
  request_timeout: 50, // keep failure fast
});

const pingResult = await client.ping();
if (hasConnectionRefusedError(pingResult)) {
  console.info("Connection refused, as expected");
} else {
  console.error("Ping expected ECONNREFUSED, got:", pingResult);
}
await client.close();

function hasConnectionRefusedError(
  pingResult: PingResult,
): pingResult is PingResult & { error: { code: "ECONNREFUSED" } } {
  return (
    !pingResult.success &&
    "code" in pingResult.error &&
    pingResult.error.code === "ECONNREFUSED"
  );
}

Mapping to an HTTP health endpoint

app.get("/healthz", async (_req, res) => {
  const r = await client.ping();
  if (r.success) {
    res.status(200).json({ ok: true });
  } else {
    res.status(503).json({ ok: false, error: String(r.error) });
  }
});

ping() vs ping({ select: true })

The default ping() hits ClickHouse's /ping HTTP endpoint — it verifies network connectivity but does not check credentials or query processing. A server that is reachable but has a bad password (or a broken query pipeline) will still return { success: true } from a plain ping().

Pass { select: true } to run a lightweight SELECT 1 instead:

const r = await client.ping({ select: true });
// success only if the server is reachable AND auth is correct AND it can run queries

	client.ping()	client.ping({ select: true })
Endpoint	/ping (HTTP)	SELECT 1 query
Checks auth	No	Yes
Checks query processing	No	Yes
Overhead	Minimal	Slightly higher

When to use which:

• Liveness probe (is the process alive?) — plain ping() is fine.
• Readiness probe (can it serve traffic?) — use ping({ select: true }) so the probe fails if credentials are wrong or the query layer is broken.
• Waking a ClickHouse Cloud idle instance — plain ping() is enough.

Common pitfalls

• Do not wrap ping() in try/catch as your only check. It resolves on failure; the success boolean is the source of truth.
• Lower request_timeout if you want pings to fail fast (the example above uses 50 ms). The default is high enough to be unsuitable for liveness probes.
• Plain ping() does not check credentials. If auth is part of what you want to verify, use ping({ select: true }).
• For ping that times out specifically, see the troubleshooting skill.
• Only ping the ClickHouse server in your app's liveness probe if the app has to be restarted to recover from a ClickHouse outage. If the app can recover the connection to ClickHouse without a restart, put the ping in a readiness probe instead so the app doesn't get killed unnecessarily.