Skip to content

Connect clients and BI tools

The warehouse's name and ports, TLS with the EZGH CA bundle, the plaintext ports, BI tools, and ezgh warehouse connect from your laptop.

Updated View as Markdown
ezgh warehouse warehouses get whs_4k2m9x0a7qpe

The console shows the same on the warehouse’s Connectivity tab: its name, ports and the CA bundle, and each user’s Secret on the Users tab.

Connect from an address in the warehouse’s allowed sources, inside its VPC. Use the name, never addresses: it stays the same for the warehouse’s life.

Name and ports

A warehouse has one name, such as wh-hylq6kelvuwvn2ks4yqhp4jaqu.us-west-1.ezghcompute.com, for every shard and replica. Any node a client reaches runs its queries, and reaches every shard through the default cluster.

Port Protocol
8443 HTTPS: ClickHouse’s HTTP interface over TLS, for curl, JDBC, ODBC and most BI tools.
9440 The native protocol over TLS, for clickhouse-client and native drivers.
8123 HTTP without TLS, only while plaintext ports are on.
9000 The native protocol without TLS, only while plaintext ports are on.

endpoint holds the hostname and each port (plaintextHttpPort and plaintextNativePort are null while plaintext ports are off). Each user’s Secret holds the name (host) and ports with the username and password, and a ready-made url.

TLS

The warehouse’s certificates are for its name and chain to the EZGH CA bundle. Verify the server’s certificate and its name against the bundle:

curl -fsSO https://get.ezghcloud.com/warehouse/ca-bundle.pem
clickhouse-client --secure --host wh-hylq6kelvuwvn2ks4yqhp4jaqu.us-west-1.ezghcompute.com --port 9440 \
  --user app --password "$PASSWORD"

with the bundle in its config (~/.clickhouse-client/config.xml). extendedVerification makes the client check the warehouse’s name as well as its certificate:

<config><openSSL><client>
  <loadDefaultCAFile>false</loadDefaultCAFile><caConfig>/path/to/ca-bundle.pem</caConfig>
  <verificationMode>strict</verificationMode><extendedVerification>true</extendedVerification>
  <invalidCertificateHandler><name>RejectCertificateHandler</name></invalidCertificateHandler>
</client></openSSL></config>
curl --cacert ca-bundle.pem -u "app:$PASSWORD" \
  "https://wh-hylq6kelvuwvn2ks4yqhp4jaqu.us-west-1.ezghcompute.com:8443/" --data-binary 'SELECT version()'
import clickhouse_connect

client = clickhouse_connect.get_client(
    host="wh-hylq6kelvuwvn2ks4yqhp4jaqu.us-west-1.ezghcompute.com", port=8443, secure=True,
    username="app", password=password, ca_cert="ca-bundle.pem")
print(client.query("SELECT version()").result_rows)
pool := x509.NewCertPool()
pool.AppendCertsFromPEM(caBundle)
conn, err := clickhouse.Open(&clickhouse.Options{
	Addr: []string{"wh-hylq6kelvuwvn2ks4yqhp4jaqu.us-west-1.ezghcompute.com:9440"},
	Auth: clickhouse.Auth{Database: "default", Username: "app", Password: password},
	TLS:  &tls.Config{RootCAs: pool},
})

BI tools

A BI tool with a ClickHouse connector (Grafana’s ClickHouse data source, Metabase, Superset, DBeaver, Tableau through the ClickHouse JDBC or ODBC driver) takes:

Field Value
Host The warehouse’s name
Port 8443 (HTTPS connectors) or 9440 (native connectors)
TLS / Secure On, with the CA bundle if the tool asks for a CA
Username, password From the user’s Secret. A readOnly user suits dashboards.
Database default, or your own

Plaintext ports

With plaintextPort on, the warehouse also serves 8123 (HTTP) and 9000 (native) without TLS, for clients that can’t use TLS. Passwords and data then cross your VPC unencrypted.

ezgh warehouse warehouses update whs_4k2m9x0a7qpe --plaintext-port=true --wait

From your laptop

ezgh warehouse connect opens a local port that reaches the warehouse, without a VPN or an address in the VPC. It needs warehouse.warehouses.connect.

ezgh warehouse connect whs_4k2m9x0a7qpe                      # native protocol, 9440
ezgh warehouse connect whs_4k2m9x0a7qpe --protocol https     # HTTPS, 8443

It prints the local port, the CA bundle to download and a clickhouse-client or curl command that connects through the port. Each client connection opens its own session, and the port closes when you stop the command (Ctrl-C). A session ends after 30 minutes without traffic or after 8 hours, and a warehouse takes 20 open sessions at once: ezgh says why a connection ended and keeps listening.

For the native protocol it prints, with your warehouse’s name and port:

curl -fsSO https://get.ezghcloud.com/warehouse/ca-bundle.pem
cat > ezgh-warehouse.xml <<'EOF'
<config><openSSL><client>
  <loadDefaultCAFile>false</loadDefaultCAFile><caConfig>ca-bundle.pem</caConfig>
  <verificationMode>strict</verificationMode><extendedVerification>true</extendedVerification>
  <invalidCertificateHandler><name>RejectCertificateHandler</name></invalidCertificateHandler>
</client></openSSL></config>
EOF
clickhouse-client --config-file ezgh-warehouse.xml --secure --host 127.0.0.1 --port 9440 \
  --tls-sni-override wh-hylq6kelvuwvn2ks4yqhp4jaqu.us-west-1.ezghcompute.com --user app --password

The client connects to the local port, so --tls-sni-override gives it the warehouse’s name to check the certificate against, and the config trusts only the EZGH CA. For HTTPS, the printed curl line does the same with --resolve. Run the commands in one directory: the config reads ca-bundle.pem from it.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close