Initial Clickhouse documentation

PR-URL: https://github.com/hasura/graphql-engine-mono/pull/10104
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Rob Dominguez <24390149+robertjdominguez@users.noreply.github.com>
GitOrigin-RevId: 836b823c13f62d9cfd7e1c1e6bcbfdd0c8f88b40

docs/docs/databases/clickhouse/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "ClickHouse",
+  "position": 90,
+  "className": "beta-cat"
+}

docs/docs/databases/clickhouse/getting-started/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Getting Started",
+  "position": 10
+}

docs/docs/databases/clickhouse/getting-started/cloud.mdx

@@ -0,0 +1,179 @@
+---
+sidebar_label: Hasura Cloud
+sidebar_position: 1
+description: Hasura Cloud for ClickHouse
+keywords:
+  - hasura
+  - docs
+  - databases
+  - clickhouse
+  - hasura cloud
+---
+
+import Thumbnail from '@site/src/components/Thumbnail';
+
+# Get Started with Hasura Cloud & ClickHouse
+
+## Try it out
+
+:::info Connecting ClickHouse to Hasura
+
+To connect ClickHouse to Hasura, you'll need to take advantage of
+[Hasura Data Connectors](/databases/data-connectors/index.mdx). You can deploy any custom data connector agent to Hasura
+Cloud using our CLI plugin. For more information, refer to the [docs](/hasura-cli/connector-plugin/index.mdx).
+
+If you're curious what other connectors are available, check out our [NDC Hub](https://github.com/hasura/ndc-hub).
+
+:::
+
+### Step 1: Create an account on Hasura Cloud and create a new Hasura Project
+
+Navigate to
+[cloud.hasura.io](https://cloud.hasura.io/signup/?pg=docs&plcmt=body&cta=navigate-to-cloud-hasura-io&tech=default&skip_onboarding=true),
+and create a new Hasura Cloud account.
+
+Once you create a project on Hasura Cloud, hit the "Launch Console" button to open the Hasura Console for your project.
+
+<Thumbnail
+  src="/img/databases/data-connector/create-project.png"
+  alt="Connect new or existing database"
+  width="1000px"
+/>
+
+### Step 2: Deploy a data connector agent
+
+We'll use the Hasura CLI to deploy a custom data connector agent to Hasura Cloud. Below, we're using the `create`
+command and naming our connector `clickhouse-connector:v1`. We're also passing in the GitHub repo URL for the connector
+agent using the `--github-repo-url` flag:
+
+```bash
+hasura connector create clickhouse-connector:v1 --github-repo-url https://github.com/hasura/clickhouse_gdc_v2/tree/main
+```
+
+We can check on the progress of the deployment using the `status` command:
+
+```bash
+hasura connector status clickhouse-connector:v1
+```
+
+Once the `DONE` status is returned, we can grab the URL for our data connector agent using the `list` command:
+
+```bash
+hasura connector list
+```
+
+This will return a list of all the custom data connector agents you own. **The second value returned is the URL which
+we'll use in the next step; copy it to your clipboard.**
+
+### Step 3: Add the data connector agent to your Hasura Cloud project
+
+In your Cloud project, navigate to the `Data` tab and click `Manage` in the left-hand sidebar.
+
+At the bottom of the screen, you'll see an expandable section titled `Data Connector Agents`.
+
+<Thumbnail
+  src="/img/databases/clickhouse/add-agent.png"
+  alt="Add the agent for a ClickHouse database"
+  width="1000px"
+/>
+
+Click this and scroll down to `Add Agent`.
+
+Name this agent `clickhouse` and paste the URL you copied from the CLI into the `URL` field and click `Connect`.
+
+<Thumbnail
+  src="/img/databases/clickhouse/configure-agent.png"
+  alt="Add the agent for a ClickHouse database"
+  width="1000px"
+/>
+
+### Step 4: Add your ClickHouse database as a source to Hasura
+
+Head to the `Data > Manage databases` section on the Console to add your ClickHouse database as a source to Hasura.
+
+:::info Make sure your ClickHouse service is reachable by Hasura Cloud:
+
+1.  **Allow public connections or
+    [whitelist the Hasura Cloud IP](/hasura-cloud/projects/create.mdx#cloud-projects-create-allow-nat-ip) on your
+    [Clickhouse firewall](https://clickhouse.com/docs/en/manage/security/ip-access-list#create-or-modify-an-ip-access-list):**
+    This is good for testing and will allow you to quickly try out Hasura with your database!
+2.  **VPC peering:** VPC peering and private network access is available on Hasura Cloud paid tiers and is recommended
+    for production. Get in touch with us if you'd like to try this out against your existing databases.
+
+:::
+
+#### Step 4.1: Begin by clicking `Connect Database`
+
+<Thumbnail src="/img/databases/data-connector/manage-databases.png" alt="Manage databases" width="1000px" />
+
+#### Step 4.2: Next, choose the `Clickhouse` driver
+
+<Thumbnail src="/img/databases/clickhouse/choose-clickhouse.png" alt="temp" width="1000px" />
+
+#### Step 4.3: Enter your ClickHouse JDBC Connection string
+
+<Thumbnail
+  src="/img/databases/clickhouse/database-config.png"
+  alt="Setting the ClickHouse connection details."
+  width="1000px"
+/>
+
+You can get create your connection URL by logging in to ClickHouse and selecting `Connect -> View connection string` for the
+database to which you want to connect.
+
+Once you add the ClickHouse service, you will find it listed as an available database on the sidebar.
+
+:::info Setting the connection string as an environment variable
+
+It's generally accepted that setting the password as an environment variable is a better practice as it's more secure
+and prevents any secrets from being exposed in your instance's metadata.
+
+An example would be to create a new
+[environment variable](/deployment/graphql-engine-flags/index.mdx#using-environment-variables) called
+`CLICKHOUSE_PASSWORD` and set it equal to your ClickHouse password.
+
+Then, export the metadata - in JSON form - using the Console's `Settings` page or by making a call using the
+[metadata API](api-reference/metadata-api/manage-metadata.mdx#metadata-export-metadata) and add the following key-value
+pair to the `metadata.json`'s `configuration` object:
+
+```json
+"template": "{\"url\": \"your_clickhouse_url_here\", \"user\": \"your_clickhouse_user\", \"password\": \"{{getEnvironmentVariable(\"CLICKHOUSE_PASSWORD\")}}\", \"tables\": null}"
+```
+
+You can then apply the metadata to your instance by either using the Console's `Settings` page or by making a call using
+the [metadata API](api-reference/metadata-api/manage-metadata.mdx#metadata-apply-metadata).
+
+:::
+
+### Step 5: Track existing tables
+
+To query your ClickHouse service using Hasura, you'll need to have existing tables to select. Those tables will appear
+under the database as shown below:
+
+<Thumbnail src="/img/databases/clickhouse/track-tables-1.png" alt="Tracking tables." width="1000px" />
+
+You can select all or select individual tables to track. Click `Track Selected` for Hasura to introspect them and create
+the corresponding GraphQL schema.
+
+<Thumbnail src="/img/databases/clickhouse/track-tables-2.png" alt="Tracking tables selected." width="1000px" />
+
+### Step 6: Try out a GraphQL query
+
+Head to the `API` tab in the Console and try running a GraphQL query! Use the explorer sidebar on GraphiQL to get help in
+creating a GraphQL query.
+
+<Thumbnail src="/img/databases/clickhouse/query.png" alt="Try a GraphQL query" width="1000px" />
+
+## Keep up to date
+
+:::info Note
+
+Currently, Hasura supports read-only queries, relationships, and permissions on ClickHouse. Column comparison operators
+are not supported with permissions on ClickHouse.
+
+:::
+
+If you'd like to stay informed about the status of ClickHouse support, subscribe to our newsletter and join our discord!
+
+- [https://hasura.io/newsletter/](https://hasura.io/newsletter/)
+- [https://discord.com/invite/hasura](https://discord.com/invite/hasura)

docs/docs/databases/clickhouse/getting-started/docker.mdx

@@ -0,0 +1,54 @@
+---
+sidebar_label: Docker
+sidebar_position: 2
+description: Hasura with Docker for ClickHouse
+keywords:
+  - hasura
+  - docs
+  - databases
+  - clickhouse
+  - docker
+---
+
+import Thumbnail from '@site/src/components/Thumbnail';
+
+# Get Started with Docker (Hasura & ClickHouse)
+
+Testing is currently underway on the ClickHouse connector for use in self-hosted environments. Our suggested
+installation method is to use Docker Compose to deploy a working instance of Hasura with the ClickHouse Connector
+enabled.
+
+In order to do this, follow the instructions for
+[Hasura Enterprise Edition](/enterprise/getting-started/quickstart-docker.mdx), but change out the Docker Compose files
+listed in that documentation to these values:
+
+```bash
+# in a new directory run
+wget https://raw.githubusercontent.com/hasura/graphql-engine/master/install-manifests/enterprise/clickhouse/docker-compose.yaml
+# or run
+curl https://raw.githubusercontent.com/hasura/graphql-engine/master/install-manifests/enterprise/clickhouse/docker-compose.yaml -o docker-compose.yml
+```
+
+When you use these to launch the services, you'll see three containers running instead of two. The third container is
+the ClickHouse GraphQL Connector agent. By navigating to the Hasura Console after execution, you'll find the ClickHouse
+data source as a type that can now be added to your Hasura GraphQL Service instance.
+
+You can follow the instructions from [this step](/databases/clickhouse/getting-started/cloud.mdx#step-22-next-choose-the-clickhouse-driver) onward to connect to your ClickHouse instance and begin using it with
+Hasura.
+
+## Keep up to date
+
+:::info Note
+
+Currently, Hasura supports read-only queries, relationships, and permissions on ClickHouse. Column comparison operators
+are not supported with permissions on ClickHouse.
+
+:::
+
+Please watch this space to get the latest docs on how you can try these features out via the Console or by manipulating
+Metadata in JSON/YAML directly.
+
+If you'd like to stay informed about the status of ClickHouse support, subscribe to our newsletter and join our discord!
+
+- [https://hasura.io/newsletter/](https://hasura.io/newsletter/)
+- [https://discord.com/invite/hasura](https://discord.com/invite/hasura)

docs/docs/databases/clickhouse/getting-started/index.mdx

@@ -0,0 +1,20 @@
+---
+slug: index
+description: Get started with ClickHouse
+keywords:
+  - hasura
+  - docs
+  - databases
+  - ClickHouse
+---
+
+# Get Started with ClickHouse
+
+To try Hasura with ClickHouse, you'll need a new or existing ClickHouse database.
+
+Here are 2 ways you can get started with Hasura and ClickHouse:
+
+1.  [Hasura Cloud](/databases/snowflake/getting-started/cloud.mdx): You'll need to be able to access your ClickHouse
+    service from Hasura Cloud.
+2.  [Docker](/databases/snowflake/getting-started/docker.mdx): Run Hasura with Docker and then connect your ClickHouse
+    service to Hasura.

docs/docs/databases/clickhouse/index.mdx

@@ -0,0 +1,52 @@
+---
+slug: index
+description: Hasura ClickHouse database support
+keywords:
+  - hasura
+  - docs
+  - databases
+  - clickhouse
+  - olap
+  - oltp
+---
+
+# ClickHouse
+
+## Introduction
+
+Hasura supports connecting to a [Clickhouse](https://www.clickhouse.com) service to automatically build a GraphQL API
+based on its schema.
+
+:::tip Supported versions:
+
+1.  Hasura GraphQL Engine `v2.30.0` onwards
+
+:::
+
+## Get Started
+
+To try Hasura with ClickHouse, you'll need a new or existing ClickHouse instance.
+
+Here are 2 ways you can get started with Hasura and ClickHouse:
+
+1.  [Hasura Cloud](/databases/clickhouse/getting-started/cloud.mdx): You'll need to be able to access your ClickHouse
+    instance service from Hasura Cloud.
+2.  [Docker](/databases/clickhouse/getting-started/docker.mdx): Run Hasura with Docker and then connect your ClickHouse
+    instance to Hasura.
+
+## Keep up to date
+
+:::info Note
+
+Currently, Hasura supports read-only queries, subscriptions, relationships, and permissions on ClickHouse.
+
+:::
+
+If you'd like to stay informed about the status of ClickHouse support, subscribe to our newsletter and join our discord!
+
+- [https://hasura.io/newsletter/](https://hasura.io/newsletter/)
+- [https://discord.com/invite/hasura](https://discord.com/invite/hasura)
+
+## Know more
+
+- [Get started](/databases/clickhouse/getting-started/index.mdx)

docs/docs/databases/overview.mdx

@@ -22,6 +22,7 @@ import MySQL from '@site/static/img/databases/logos/mysql.png';
 import Snowflake from '@site/static/img/databases/logos/snowflake.png';
 import AmazonAthena from '@site/static/img/databases/logos/amazon-athena.png';
 import Oracle from '@site/static/img/databases/logos/oracle.png';
+import Clickhouse from '@site/static/img/databases/logos/clickhouse.png';
 
 # <Database /> Databases
 
@@ -129,6 +130,14 @@ import Oracle from '@site/static/img/databases/logos/oracle.png';
       <h5>MongoDB (Beta)</h5>
     </div>
   </VersionedLink>
+  <VersionedLink to="/databases/clickhouse/index/">
+    <div className="card-wrapper">
+      <div className="card">
+        <img src={Clickhouse} style={{ width: '172px' }} title="ClickHouse" alt="Connect ClickHouse to Hasura" />
+      </div>
+      <h5>ClickHouse</h5>
+    </div>
+  </VersionedLink>
 </div>
 
 ## Using Databases

install-manifests/enterprise/clickhouse/docker-compose.yaml

@@ -0,0 +1,62 @@
+version: "3.7"
+services:
+  redis:
+    image: redis:7
+    restart: always
+    # ports:
+    #   - 6379:6379
+  postgres:
+    image: postgres:15
+    restart: always
+    volumes:
+      - db_data:/var/lib/postgresql/data
+    environment:
+      POSTGRES_PASSWORD: postgrespassword
+  hasura:
+    image: hasura/graphql-engine:v2.31.0
+    restart: always
+    ports:
+      - 8080:8080
+    environment:
+      ## Add your license key below
+      # HASURA_GRAPHQL_EE_LICENSE_KEY: ""
+      HASURA_GRAPHQL_ADMIN_SECRET: myadminsecretkey
+      ## The metadata database for this Hasura GraphQL project. Can be changed to a managed postgres instance
+      HASURA_GRAPHQL_DATABASE_URL: postgres://postgres:postgrespassword@postgres:5432/postgres
+      # HASURA_GRAPHQL_READ_REPLICA_URLS: postgres://postgres:postgrespassword@postgres:5432/postgres
+
+      ## Optional settings
+      ## enable the console served by server
+      HASURA_GRAPHQL_ENABLE_CONSOLE: "true"
+      ## enable required apis; metrics api exposes a prometheus endpoint, uncomment to enable
+      # HASURA_GRAPHQL_ENABLED_APIS: 'graphql,metadata,config,developer,pgdump,metrics'
+      ## secure metrics endpoint with a secret, uncomment to enable
+      # HASURA_GRAPHQL_METRICS_SECRET: 'secret'
+      ## enable debugging mode. It is recommended to disable this in production
+      HASURA_GRAPHQL_DEV_MODE: "true"
+      # HASURA_GRAPHQL_LOG_LEVEL: debug
+      ## enable offline console assets if you wish to access console without internet connectivity
+      # HASURA_GRAPHQL_CONSOLE_ASSETS_DIR: "/srv/console-assets"
+      HASURA_GRAPHQL_REDIS_URL: redis://redis:6379
+      HASURA_GRAPHQL_RATE_LIMIT_REDIS_URL: "redis://redis:6379"
+      HASURA_GRAPHQL_MAX_CACHE_SIZE: "200"
+      # Configures the connection to the Data Connector agent for Clickhouse by default
+      # You can also omit this and manually configure the same thing via the 'Data' tab, then 'Add Agent'
+      # in the Hasura console
+      HASURA_GRAPHQL_METADATA_DEFAULTS: '{"backend_configs":{"dataconnector":{"clickhouse":{"uri":"http://data-connector-agent:8080"}}}}'
+    depends_on:
+      data-connector-agent:
+        condition: service_healthy
+  data-connector-agent:
+    image: hasura/clickhouse-data-connector:v2.32.0
+    restart: always
+    ports:
+      - 8080:8081
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
+      interval: 5s
+      timeout: 10s
+      retries: 5
+      start_period: 5s
+volumes:
+  db_data: