The ClickHouse app + chat connector lets your RShift Sites app run SQL queries against your ClickHouse database over the HTTP interface. It works with both self-hosted ClickHouse and ClickHouse Cloud.
ClickHouse is available as an app + chat connector: one shared connection that works in the project chat while you build and in your published apps.
With ClickHouse connected, your app can:
- Run SQL queries over the ClickHouse HTTP interface
- Explore schema and table metadata via system tables
- Paginate large result sets with
LIMITandOFFSET - Enforce per-query time limits to keep requests bounded
Common use cases and example apps
| Example app | Example prompt | Description |
|---|---|---|
| Real-time analytics dashboard | Build a dashboard that shows event counts and trends from my ClickHouse events table, refreshed every minute. |
Turn high-volume event data into live charts. The app runs SQL against ClickHouse and renders metrics that stay current. |
| Log explorer | Build a tool to search and filter our application logs stored in ClickHouse by service, level, and time range. | Self-serve search over large log tables. The app submits filtered queries and returns results without console access. |
| Schema explorer | Build a tool that lists databases and tables and shows column types and row counts. | Browse what’s in the database. The app reads system tables to describe schemas. |
| Usage metering view | Show per-customer usage aggregated from our ClickHouse usage table, with date filters. |
Surface aggregates from curated tables. The app queries summary tables your pipelines maintain. |
Exact behavior depends on your tables, the permissions of the ClickHouse user you connect with, and what you ask RShift Sites to build.
How ClickHouse connections work
- HTTP interface: The connector talks to the ClickHouse HTTP interface over HTTPS. You provide the full HTTPS URL of the interface, including the port (for example
https://abc123.eu-central-1.aws.clickhouse.cloud:8443). - Authentication: ClickHouse uses HTTP basic auth. Provide the username and password of the database user you want to connect with. Credentials are stored securely in RShift Sites’ gateway and are never exposed to the browser or your app’s frontend code.
- Gateway: Queries are proxied through RShift Sites’ connector gateway, which injects the host and credentials so your app never sends them. See Gateway-based connectors for token handling and per-project request limits.
- Data access: What you can read or run depends entirely on the permissions of the ClickHouse user you connect with.
How to connect ClickHouse
Who can connect ClickHouse depends on your plan and workspace settings. See Who can create connections and clients for details.
Prerequisites
Before connecting in RShift Sites, make sure you have:
- A ClickHouse database (self-hosted or ClickHouse Cloud) with the HTTP interface reachable over HTTPS
- The HTTPS URL of your HTTP interface, including the port
- A ClickHouse user (a read-only user is recommended) with access to the data your app needs
- Permission to create connections in your RShift Sites workspace
Set up your ClickHouse connection
Navigate to ClickHouse connector
Open Connectors and select ClickHouse.
Add a new connection
Click Add connection.
Name the connection
In Display name, name the connection (for example, ClickHouse Production or ClickHouse read-only).
Enter your connection details
-
HTTP Interface URL: the full HTTPS URL of your ClickHouse HTTP interface, including the port (e.g.
https://abc123.eu-central-1.aws.clickhouse.cloud:8443).- Username: the ClickHouse user for HTTP basic authentication.
- Password: that user’s password.
To connect without authentication, leave both Username and Password empty. No auth header is sent and ClickHouse uses its
defaultuser. See the HTTP interface docs for details.
Choose who can use this connection
Under Sharing, the connection is private to you by default and shows a Private label. To share it, click Share with others. Then add workspace members by email, or click Invite entire workspace to make the connection available to everyone in your RShift Sites workspace.
See Who can use connections and clients for more information.
Connect
Click Connect. RShift Sites verifies the connection through the gateway with a SELECT 1 query.
When connected, you can link the connection to projects and start building apps that query your ClickHouse data.
Limitations
- No per-user data scoping. Everyone using a connection queries with the same ClickHouse user. Use a read-only user scoped to the right databases, and restrict who can use the connection.
- Queries are synchronous. There is no polling or server-side cursor. Paginate with SQL
LIMIT/OFFSET, and raise the per-query time limit for long queries. - No default database. Qualify table names with the database (e.g.
mydb.users). - Gateway limits apply as described in Gateway-based connectors.
Manage your {connector_0} connection
Connections are managed from Connectors: select {connector_0}, then open the connection.
- Unlink projects to remove {connector_0} access from specific projects while keeping the connection available for others. See Unlink projects from a connection for the steps.
- Delete the connection to remove it from the workspace entirely. Deleting is permanent. It removes the credentials from all linked projects, and app features that use {connector_0} stop working until a new connection is added. See Delete a connection for the steps and who can delete.