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
5
docs/docs/databases/clickhouse/_category_.json
Normal file
@ -0,0 +1,5 @@
|
||||
{
|
||||
"label": "ClickHouse",
|
||||
"position": 90,
|
||||
"className": "beta-cat"
|
||||
}
|
@ -0,0 +1,4 @@
|
||||
{
|
||||
"label": "Getting Started",
|
||||
"position": 10
|
||||
}
|
179
docs/docs/databases/clickhouse/getting-started/cloud.mdx
Normal file
@ -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)
|
54
docs/docs/databases/clickhouse/getting-started/docker.mdx
Normal file
@ -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)
|
20
docs/docs/databases/clickhouse/getting-started/index.mdx
Normal file
@ -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.
|
52
docs/docs/databases/clickhouse/index.mdx
Normal file
@ -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)
|
@ -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
|
||||
|
BIN
docs/static/img/databases/clickhouse/add-agent.png
vendored
Normal file
After Width: | Height: | Size: 66 KiB |
BIN
docs/static/img/databases/clickhouse/choose-clickhouse.png
vendored
Normal file
After Width: | Height: | Size: 85 KiB |
BIN
docs/static/img/databases/clickhouse/configure-agent.png
vendored
Normal file
After Width: | Height: | Size: 122 KiB |
BIN
docs/static/img/databases/clickhouse/database-config.png
vendored
Normal file
After Width: | Height: | Size: 63 KiB |
BIN
docs/static/img/databases/clickhouse/query.png
vendored
Normal file
After Width: | Height: | Size: 266 KiB |
BIN
docs/static/img/databases/clickhouse/track-tables-1.png
vendored
Normal file
After Width: | Height: | Size: 252 KiB |
BIN
docs/static/img/databases/clickhouse/track-tables-2.png
vendored
Normal file
After Width: | Height: | Size: 117 KiB |
BIN
docs/static/img/databases/logos/clickhouse.png
vendored
Normal file
After Width: | Height: | Size: 8.1 KiB |
62
install-manifests/enterprise/clickhouse/docker-compose.yaml
Normal file
@ -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:
|