Skip to content

Commit e6635ca

Browse files
middtmiddt
committed
Add ClickHouse state store documentation
- Add comprehensive documentation for ClickHouse state store component - Include setup instructions for self-hosted, Kubernetes, and cloud deployments - Document supported features: CRUD, ETag, and TTL support - Add advanced configuration options and performance considerations - Update component registry with ClickHouse entry in generic.yaml - Set correct version as 1.16 (first release) - Remove actor-related content as ClickHouse is not transactional Signed-off-by: Mehmet TOSUN <[email protected]>
1 parent 246316c commit e6635ca

File tree

3 files changed

+205
-1
lines changed

3 files changed

+205
-1
lines changed

‎daprdocs/content/en/reference/components-reference/supported-state-stores/setup-clickhouse.md

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
---
2+
type: docs
3+
title: "ClickHouse"
4+
linkTitle: "ClickHouse"
5+
description: Detailed information on the ClickHouse state store component
6+
aliases:
7+
- "/operations/components/setup-state-store/supported-state-stores/setup-clickhouse/"
8+
---
9+
10+
## Component format
11+
12+
To setup ClickHouse state store create a component of type `state.clickhouse`. See [this guide]({{< ref "howto-get-save-state.md#step-1-setup-a-state-store" >}}) on how to create and apply a state store configuration.
13+
14+
```yaml
15+
apiVersion: dapr.io/v1alpha1
16+
kind: Component
17+
metadata:
18+
name: <NAME>
19+
spec:
20+
type: state.clickhouse
21+
version: v1
22+
metadata:
23+
- name: clickhouseURL
24+
value: <CONNECTION_URL>
25+
- name: databaseName
26+
value: <DATABASE_NAME>
27+
- name: tableName
28+
value: <TABLE_NAME>
29+
- name: username # Optional
30+
value: <USERNAME>
31+
- name: password # Optional
32+
value: <PASSWORD>
33+
```
34+
35+
{{% alert title="Warning" color="warning" %}}
36+
The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described [here]({{< ref component-secrets.md >}}).
37+
{{% /alert %}}
38+
39+
## Spec metadata fields
40+
41+
| Field | Required | Details | Example |
42+
|--------------------|:--------:|---------|---------|
43+
| clickhouseURL | Y | Connection URL for the ClickHouse server | `"clickhouse://localhost:9000"`, `"clickhouse://clickhouse-server:9000"` |
44+
| databaseName | Y | Name of the database to use | `"dapr_state"`, `"my_database"` |
45+
| tableName | Y | Name of the table to store state data | `"state_table"`, `"dapr_state_store"` |
46+
| username | N | Username for ClickHouse authentication. Can be `secretKeyRef` to use a secret reference | `"default"`, `"my_user"` |
47+
| password | N | Password for ClickHouse authentication. Can be `secretKeyRef` to use a secret reference | `"my_password"` |
48+
49+
## Setup ClickHouse
50+
51+
Dapr can use any ClickHouse instance: containerized, running on your local dev machine, or a managed cloud service.
52+
53+
{{< tabs "Self-Hosted" "Kubernetes" "Cloud" >}}
54+
55+
{{% codetab %}}
56+
57+
1. Run an instance of ClickHouse. You can run a local instance of ClickHouse in Docker with the following command:
58+
59+
```bash
60+
docker run -d --name clickhouse-server \
61+
-p 8123:8123 -p 9000:9000 \
62+
-e CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT=1 \
63+
-e CLICKHOUSE_PASSWORD=my_password \
64+
clickhouse/clickhouse-server
65+
```
66+
67+
2. Create a database for state data (optional, as Dapr will create it automatically):
68+
69+
```sql
70+
CREATE DATABASE IF NOT EXISTS dapr_state;
71+
```
72+
73+
{{% /codetab %}}
74+
75+
{{% codetab %}}
76+
77+
You can use [Helm](https://helm.sh/) to quickly create a ClickHouse instance in your Kubernetes cluster. This approach requires [Installing Helm](https://github.com/helm/helm#install).
78+
79+
1. Add the ClickHouse Helm repository:
80+
```bash
81+
helm repo add clickhouse https://docs.altinity.com/clickhouse-operator/
82+
helm repo update
83+
```
84+
85+
2. Install ClickHouse into your cluster:
86+
```bash
87+
helm install clickhouse clickhouse/clickhouse
88+
```
89+
90+
3. Run `kubectl get pods` to see the ClickHouse containers now running in your cluster.
91+
92+
4. Add the ClickHouse service endpoint as the `clickhouseURL` in your component configuration. For example:
93+
```yaml
94+
metadata:
95+
- name: clickhouseURL
96+
value: "clickhouse://clickhouse:9000"
97+
```
98+
99+
{{% /codetab %}}
100+
101+
{{% codetab %}}
102+
103+
ClickHouse is available as a managed service from various cloud providers:
104+
105+
- [ClickHouse Cloud](https://clickhouse.com/cloud)
106+
- [Altinity.Cloud](https://altinity.com/cloud-database/)
107+
- [Yandex Managed Service for ClickHouse](https://cloud.yandex.com/services/managed-clickhouse)
108+
109+
When using a managed service, ensure you have the correct connection URL, database name, and credentials configured in your component metadata.
110+
111+
{{% /codetab %}}
112+
113+
{{< /tabs >}}
114+
115+
## Features
116+
117+
The ClickHouse state store supports the following features:
118+
119+
### ETags
120+
121+
The ClickHouse state store supports [ETags]({{< ref state-management-overview.md >}}) for optimistic concurrency control. ETags are automatically generated and updated when state data is modified.
122+
123+
### TTL (Time-To-Live)
124+
125+
This state store supports [Time-To-Live (TTL)]({{< ref state-store-ttl.md >}}) for records stored with Dapr. When storing data using Dapr, you can set the `ttlInSeconds` metadata property to indicate after how many seconds the data should be considered "expired".
126+
127+
Example of setting TTL:
128+
129+
```json
130+
{
131+
"key": "my-key",
132+
"value": "my-value",
133+
"metadata": {
134+
"ttlInSeconds": "3600"
135+
}
136+
}
137+
```
138+
139+
Records with expired TTLs are automatically filtered out during read operations and are eligible for cleanup by ClickHouse's background processes.
140+
141+
## Advanced
142+
143+
### Table Schema
144+
145+
The ClickHouse state store creates a table with the following schema:
146+
147+
```sql
148+
CREATE TABLE IF NOT EXISTS <database>.<table> (
149+
key String,
150+
value String,
151+
etag String,
152+
expire DateTime64(3) NULL,
153+
PRIMARY KEY(key)
154+
) ENGINE = ReplacingMergeTree()
155+
ORDER BY key
156+
```
157+
158+
The table uses ClickHouse's `ReplacingMergeTree` engine, which automatically deduplicates rows with the same primary key during background merges.
159+
160+
### Connection URL Format
161+
162+
The ClickHouse connection URL follows the standard format:
163+
164+
```
165+
clickhouse://[username[:password]@]host[:port][/database][?param1=value1&...&paramN=valueN]
166+
```
167+
168+
Examples:
169+
- `clickhouse://localhost:9000`
170+
- `clickhouse://user:password@clickhouse-server:9000/my_db`
171+
- `clickhouse://localhost:9000?dial_timeout=10s&max_execution_time=60`
172+
173+
### Performance Considerations
174+
175+
- The ClickHouse state store is optimized for high-throughput scenarios
176+
- For better performance with large datasets, consider partitioning your table by date or other relevant columns
177+
- The `ReplacingMergeTree` engine provides eventual consistency for duplicate key handling
178+
- Background merges in ClickHouse will automatically clean up old versions of updated records
179+
180+
### Bulk Operations
181+
182+
The ClickHouse state store supports bulk operations for improved performance:
183+
184+
- `BulkGet`: Retrieve multiple keys in a single operation
185+
- `BulkSet`: Store multiple key-value pairs in a single operation
186+
- `BulkDelete`: Delete multiple keys in a single operation
187+
188+
## Related links
189+
190+
- [Basic schema for a Dapr component]({{< ref component-schema >}})
191+
- Read [this guide]({{< ref "howto-get-save-state.md#step-2-save-and-retrieve-a-single-state" >}}) for instructions on configuring state store components
192+
- [State management building block]({{< ref state-management >}})
193+
- [ClickHouse Official Documentation](https://clickhouse.com/docs)

‎daprdocs/data/components/state_stores/generic.yaml

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,17 @@
2020
etag: false
2121
ttl: true
2222
query: false
23+
- component: ClickHouse
24+
link: setup-clickhouse
25+
state: Alpha
26+
version: v1
27+
since: "1.16"
28+
features:
29+
crud: true
30+
transactions: false
31+
etag: true
32+
ttl: true
33+
query: false
2334
- component: CockroachDB
2435
link: setup-cockroachdb
2536
state: Stable

‎sdkdocs/python

Submodule python updated 46 files

0 commit comments

Comments
 (0)