Documenting your ClickHouse integration

How partners contribute integration pages to clickhouse-docs, including required sections and a copy-paste skeleton.

Your integration documentation lives in the official ClickHouse docs alongside ClickHouse pages. End users get one place to scope and troubleshoot setups. This page describes what to include, where files go, and how to open a pull request.

Start with Building integrations and Testing your integration if you have not already.

Where docs live

• Repository: ClickHouse/clickhouse-docs
• Format: Markdown, built with Docusaurus
• Location: /docs/integrations/<category>/<your-integration>/, where <category> reflects what your product does (data-visualization, data-ingestion, language-clients, and so on)
• Process: open a pull request against main. The ClickHouse integrations team reviews. First-time contributors sign the Contributor License Agreement when the bot prompts on the PR

Good exemplars: Tableau and Metabase.

Required sections

Every partner integration page should cover the following, ideally in this order:

• Purpose. What problem the integration solves, in two or three sentences. Avoid marketing copy. Readers are usually engineers scoping a setup
• Prerequisites and supported version matrix. What the user needs installed and which versions you support for both ClickHouse Cloud and self-hosted (OSS). A small table works well
• Setup walkthrough. Step-by-step instructions to a working connection, with side-by-side coverage of Cloud and self-hosted where they differ (host, port, TLS)
• Authentication. Which auth modes you support (username and password over TLS at minimum, plus mTLS, SSL client cert, IP allow-list notes if relevant)
• End-to-end example. At least one realistic example from connection through a meaningful result. Use a ClickHouse example dataset so readers can reproduce it
• Known limits and performance characteristics. Type-system gaps, result-set thresholds, throughput notes, unsupported features. Honesty here saves support cycles
• Troubleshooting. Common errors and resolutions. Two or three frequent cases are enough for a first version

Style notes

• Show both Cloud and self-hosted. Cloud typically uses HTTPS on port 8443 and native TCP on 9440. Self-hosted defaults to 8123 and 9000
• Use Docusaurus admonitions (:::note, :::warning, :::tip) for callouts instead of bold paragraphs
• Link out for depth. Link to existing docs for data types, formats, JDBC, ClickPipes, and similar topics instead of re-explaining them
• No marketing. Partner pages here are technical reference. Promotional content belongs on your site; we can link to it from the partner directory

Copy-paste skeleton

Fill in the bracketed sections, save as /docs/integrations/<category>/<your-integration>/index.md, and open a PR.

# [Your product] and ClickHouse

[One to three sentences: what the integration does and why a
ClickHouse user would want it.]

## Prerequisites

- [Your product, version X.Y or later]
- ClickHouse Cloud, or self-hosted ClickHouse version [X.Y] or later
- [Anything else: driver, plugin, network access requirements]

### Version matrix

| [Your product] | ClickHouse Cloud | ClickHouse OSS | Notes      |
| -------------- | ---------------- | -------------- | ---------- |
| X.Y            | ✅               | ✅ 24.x+       | [if any]   |

## Setup

### Connect to ClickHouse Cloud

1. In the ClickHouse Cloud console, select your service and click **Connect**.
2. Choose **HTTPS**. Copy the host, port (8443), username, and password.
3. In [your product], [steps to configure the connection].

### Connect to self-hosted ClickHouse

1. [How to point at a self-hosted instance — host, port 8123 or 9000, TLS notes.]
2. In [your product], [steps to configure the connection].

## Authentication

[List supported auth modes — username/password over TLS, mTLS, etc. — and how
to configure each.]

## Example: querying the [dataset] dataset

[Walkthrough using one of the ClickHouse example datasets, end-to-end.]

## Known limits

- [Types not yet supported, e.g., deeply nested JSON]
- [Result-set size thresholds or other performance notes]
- [Feature gaps]

## Troubleshooting

### [Common error message]

[Cause and resolution.]

### [Another common error]

[Cause and resolution.]

Review

The ClickHouse integrations team reviews PRs for technical accuracy, Cloud and self-hosted coverage, and docs style. Iterate in the PR until reviewers approve. That approval is the merge gate.