Documenting your ClickHouse integration

Integration documentation on this site gives end users 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

Integration pages in this repository are the primary reference for end users. You can link to supplementary documentation on your site from your integration page for product-specific details.

Good exemplars: Tableau and Metabase.

Choosing a category

Pick the category that best matches what your product does. Browse existing categories under Integrations before you open a PR. If you are unsure, note your proposed category in the PR description and the integrations team will help place the page.

Required sections

Every 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 (open source). 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. Integration 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 open source | 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.