Skip to content

ClickHouse stack guide

The Wodby ClickHouse catalog stack runs a single ClickHouse server. The current service and defaults are documented in wodby/stack-clickhouse.

Connect an application

Link your application's app service to the ClickHouse app service. See Links. The app service receives the host, port and the tokens below in variables named by the linking service. Read them in code. Do not copy the password into your repository.

Port Use
8123 HTTP interface
9000 Native protocol, private

Applications in the same app environment use both ports directly, without TLS.

The tokens are on the ClickHouse app service's Configuration > Tokens tab:

  • database: default
  • username: wodby
  • password: generated by Wodby

The account can create other users, roles and databases with SQL. Create further databases, users and grants with SQL instead of adding environment variables. Server settings are not exposed as settings or config files.

Public address

Port 8123 is the main HTTP endpoint, so it gets a public HTTPS address. Port 9000 has no route.

The address answers Ok. at its root. Open /play to run queries and /dashboard for the built-in charts. Sign in with the account above.

Anyone with the password can run SQL from anywhere

The public address accepts any SQL the account allows, including statements that change or delete data. Requests without the password are refused. /play and /dashboard send the password in the URL of every query, so it can appear in ingress logs. A link such as /play?password=... also carries it.

To protect the address:

  • Keep the generated password, or replace it with one as long and random.
  • Do not share /play or /dashboard URLs or copy them into tickets or chat. Do not add the password to a URL.
  • Restrict who can reach the address with Private App Access, or disable the route. Services in the same app environment keep connecting directly. Private App Access needs an active paid subscription.
  • Do not turn on Wodby Basic Auth for this service. ClickHouse uses the Authorization header for its own login, so /play, /dashboard and HTTP clients stop working behind Basic Auth.

Resources, data and backups

ClickHouse runs as a single node and does not scale. The stack requests 0.5 CPU and 1024 MiB and limits it to 2 CPU and 4096 MiB. Change resources under Runtime > Resources.

The stack adds a 20 GiB ClickHouse data volume. The service has no backup or import support.

Check that it works

From any service in the app environment, GET http://<app service name>:8123/ping answers Ok. In a web terminal on the ClickHouse app service, run:

clickhouse-client --user "$CLICKHOUSE_USER" --password "$CLICKHOUSE_PASSWORD" --query "SHOW DATABASES"