ClickHouse

Run read-only SQL on a hosted ClickHouse service or your own ClickHouse server over its HTTP interface.

Connect it in the console under Integrations > Connectors. See Connectors for how connectors work and who can use them.

Create a read-only credential

Create a user that is read-only on the server:

CREATE USER vaif_reader IDENTIFIED BY 'a-long-random-password' SETTINGS readonly = 1;
GRANT SELECT ON analytics.* TO vaif_reader;

The host must resolve to a public address: VAIF Studio refuses private, loopback, link-local and cloud metadata addresses, and connects to the address it checked, so a DNS change cannot redirect it.

Settings

Setting		Notes
Host	Required	For example abc123.us-east-1.aws.clickhouse.cloud.
Protocol	Optional	One of: HTTPS, HTTP (unencrypted). Default: HTTPS.
Port	Optional	Default 8443.
Database	Optional	For example default.
Username	Optional	For example default.
Password	Optional	Stored encrypted and never shown again.

HTTP sends the password unencrypted; keep HTTPS unless the server is on a network you trust. The port defaults to 8443 for HTTPS and 8123 for HTTP.

Tables

Table	Filters	Returns
tables	None	Tables in the configured database.
sql	query (required)	Run one read-only SQL statement. Needs the developer role.

Query from the API

curl -s -X POST "https://api.vaif.studio/database/connector/$VAIF_PROJECT_ID/query" \
  -H "Authorization: Bearer $VAIF_TOKEN" -H "Content-Type: application/json" \
  -d '{"wrapperId":"clickhouse_fdw","table":"sql","filters":{"query":"SELECT toDate(ts) AS day, count() AS events FROM events GROUP BY day ORDER BY day"},"limit":50}'

$VAIF_TOKEN is a console access token. See Connectors for the routes.

How it stays read-only

Every request runs with readonly = 2, which allows reads only and cannot be changed back, a 15-second max_execution_time and a row cap. For a user whose profile is already readonly = 1, the query runs with that setting instead. Leave out any FORMAT clause: results always come back as rows.