> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-trino-dialect.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Documenting your ClickHouse integration
> How to contribute integration pages to this repository, including required sections and a copy-paste skeleton.
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](/resources/develop-contribute/integrations/building-integrations) and [Testing your integration](/resources/develop-contribute/integrations/testing-your-integration) if you have not already.
Where docs live
* **Repository:** [`ClickHouse/ClickHouse`](https://github.com/ClickHouse/ClickHouse) (`docs/` in this tree)
* **Format:** MDX, built with [Mintlify](https://www.mintlify.com/)
* **Location:** `docs/integrations///`, where `` reflects what your product does (`data-visualization`, `data-ingestion`, `language-clients`, and so on)
* **Process:** open a pull request against `master`. The ClickHouse integrations team reviews. First-time contributors sign the Contributor License Agreement when the bot prompts on the PR. See the [docs contribution guide](https://github.com/ClickHouse/ClickHouse/tree/master/docs#readme) for local preview (`mint dev` from `docs/`)
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](/integrations/connectors/data-visualization/tableau/tableau-and-clickhouse) and [Metabase](/integrations/connectors/data-visualization/metabase-and-clickhouse).
Choosing a category
Pick the category that best matches what your product does. Browse existing categories under [Integrations](/integrations/home) 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:
1. **Purpose.** What problem the integration solves, in two or three sentences. Avoid marketing copy. Readers are usually engineers scoping a setup
2. **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
3. **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)
4. **Authentication.** Which auth modes you support (username and password over TLS at minimum, plus mTLS, SSL client cert, IP allow-list notes if relevant)
5. **End-to-end example.** At least one realistic example from connection through a meaningful result. Use a [ClickHouse example dataset](/get-started/sample-datasets/index) so readers can reproduce it
6. **Known limits and performance characteristics.** Type-system gaps, result-set thresholds, throughput notes, unsupported features. Honesty here saves support cycles
7. **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 Mintlify 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///index.mdx`, and open a PR.
```mdx theme={null}
---
title: '[Your product] and ClickHouse'
sidebarTitle: '[Your product]'
slug: /integrations/[your-product]
description: '[One sentence: what the integration does.]'
doc_type: 'guide'
keywords: ['[your product]', 'integration']
---
[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.