> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lovable.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect your app to ClickHouse

> Connect a ClickHouse database to your Lovable app over the HTTP interface. Run SQL queries, explore schemas, and build analytics features against self-hosted or ClickHouse Cloud databases.

export const connector_0 = "ClickHouse"

The **ClickHouse** app connector lets your Lovable app **run SQL queries** against your [ClickHouse](https://clickhouse.com/) database over the [HTTP interface](https://clickhouse.com/docs/interfaces/http). It works with both **self-hosted ClickHouse** and **ClickHouse Cloud**.

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 **`LIMIT`** and **`OFFSET`**
* 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 Lovable to build**.

## How ClickHouse connections work

* **HTTP interface**: The connector talks to the [ClickHouse HTTP interface](https://clickhouse.com/docs/interfaces/http) 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 Lovable's gateway and are never exposed to the browser or your app's frontend code.
* **Gateway**: Queries are proxied through Lovable's **connector gateway**, which injects the host and credentials so your app never sends them. See [Gateway-based connectors](/integrations/introduction#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.

<Tip>
  **Use a read-only ClickHouse user.** Create a dedicated user with read-only access to only the databases and tables your app needs. The user's permissions determine what every app using the connection can query, so scoping it down limits what a query can reach.
</Tip>

## How to connect ClickHouse

Who can connect ClickHouse depends on your plan and workspace settings. See [Who can create connections](/integrations/introduction#who-can-create-connections) for details.

### Prerequisites

Before connecting in Lovable, 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 Lovable workspace

### Set up your ClickHouse connection

<Steps>
  <Step title="Navigate to ClickHouse connector">
    Open **Connectors** → **App connectors** and select **ClickHouse**.
  </Step>

  <Step title="Add a new connection">
    Click **Add connection**.
  </Step>

  <Step title="Name the connection">
    In **Display name**, name the connection (for example, `ClickHouse Production` or `ClickHouse read-only`).
  </Step>

  <Step title="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 `default` user. See the [HTTP interface docs](https://clickhouse.com/docs/interfaces/http) for details.
  </Step>

  <Step title="Choose who can use this connection">
    Under **Who can use this connection**, decide who in your workspace can use the connection:

    * **Only you** (default): only the person creating the connection can use it and its associated data.
    * **Invite specific people**: only you and explicitly added workspace members can use the connection and its associated data.
    * **Invite entire workspace**: click **Invite entire workspace** to make the connection available to everyone in your Lovable workspace.

    See [Who can manage connections](/integrations/introduction#who-can-manage-connections) for more information.
  </Step>

  <Step title="Connect">
    Click **Connect**. Lovable verifies the connection through the gateway with a `SELECT 1` query.
  </Step>
</Steps>

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](/integrations/introduction#gateway-based-connectors).

## How to unlink projects from a {connector_0} connection

Editors and above can remove specific projects from a connection without deleting the connection entirely. The connection will remain available for other projects.

To unlink projects:

<Steps>
  <Step title="Open Connectors">
    Open **Connectors**, then go to **App connectors**, and select **{connector_0}**.
  </Step>

  <Step title="Open the connection">
    Open the connection you want to manage.
  </Step>

  <Step title="Select projects">
    Under **Linked projects**, check the projects you want to unlink.
  </Step>

  <Step title="Confirm">
    Click **Unlink projects** and confirm.
  </Step>
</Steps>

When unlinked, those projects will no longer have access to {connector_0} through this connection. If a project needs {connector_0} again, you can link it to any available connection.

## How to delete a {connector_0} connection

Workspace admins and owners can delete {connector_0} connections. Other members can delete a connection if they created it, or if they have been explicitly granted access to it.

<Warning>
  Deleting a connection is permanent and cannot be undone. It will remove the credentials from all linked projects, and any apps using this connection will stop working until a new connection is added.
</Warning>

Before deleting, review the **Linked projects** section to see which projects are currently using the connection.

To delete a connection:

<Steps>
  <Step title="Open Connectors">
    Open **Connectors**, then go to **App connectors**, and select **{connector_0}**.
  </Step>

  <Step title="Open the connection">
    Open the connection you want to remove.
  </Step>

  <Step title="Review linked projects">
    Review the **Linked projects** section.
  </Step>

  <Step title="Delete">
    Under **Delete this connection**, click **Delete** and confirm.
  </Step>
</Steps>