> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> Introduction to using ClickHouse with Grafana
# ClickHouse data source plugin for Grafana
export const ClickHouseSupportedBadge = () => {
return ;
};
export const Image = ({img, alt, size}) => {
return
;
};
With Grafana you can explore and share all of your data through dashboards.
Grafana requires a plugin to connect to ClickHouse, which is easily installed within their UI.
1. Gather your connection details
To connect to ClickHouse with native TCP you need this information:
| Parameters | Description |
| ------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `HOST` and `PORT` | Typically, the port is 9440 when using TLS, or 9000 when not using TLS. |
| `DATABASE NAME` | Out of the box there is a database named `default`, use the name of the database that you want to connect to. |
| `USERNAME` and `PASSWORD` | Out of the box the username is `default`. Use the username appropriate for your use case. |
The details for your ClickHouse Cloud service are available in the ClickHouse Cloud console.
Select the service that you will connect to and click **Connect**:
Choose **Native**, and the details are available in an example `clickhouse-client` command.
If you're using self-managed ClickHouse, the connection details are set by your ClickHouse administrator.
2. Making a read-only user
When connecting ClickHouse to a data visualization tool like Grafana, it is recommended to make a read-only user to protect your data from unwanted modifications.
Grafana doesn't validate that queries are safe. Queries can contain any SQL statement, including `DELETE` and `INSERT`.
To configure a read-only user, follow these steps:
1. Create a `readonly` user profile following the [Creating Users and Roles in ClickHouse](/concepts/features/security/access-rights) guide.
2. Ensure the `readonly` user has enough permission to modify the `max_execution_time` setting required by the underlying [clickhouse-go client](https://github.com/ClickHouse/clickhouse-go).
3. If you're using a public ClickHouse instance, it isn't recommended to set `readonly=2` in the `readonly` profile. Instead, leave `readonly=1` and set the constraint type of `max_execution_time` to [changeable\_in\_readonly](/concepts/features/configuration/settings/constraints-on-settings) to allow modification of this setting.
3) Install the ClickHouse plugin for Grafana
Before Grafana can connect to ClickHouse, you need to install the appropriate Grafana plugin. Assuming you're logged in to Grafana, follow these steps:
1. From the **Connections** page in the sidebar, select the **Add new connection** tab.
2. Search for **ClickHouse** and click on the signed plugin by Grafana Labs:
3. On the next screen, click the **Install** button:
4) Define a ClickHouse data source
1. Once the installation is complete, click the **Add new data source** button. (You can also add a data source from the **Data sources** tab on the **Connections** page.)
2. Either scroll down and find the **ClickHouse** data source type, or you can search for it in the search bar of the **Add data source** page. Select the **ClickHouse** data source and the following page will appear:
3. Enter your server settings and credentials. The key settings are:
* **Server host address:** the hostname of your ClickHouse service.
* **Server port:** the port for your ClickHouse service. Will be different depending on server configuration and protocol.
* **Protocol** the protocol used to connect to your ClickHouse service.
* **Secure connection** enable if your server requires a secure connection.
* **Username** and **Password**: enter your ClickHouse user credentials. If you haven't configured any users, try `default` for the username. It is recommended to [configure a read-only user](#2-making-a-read-only-user).
For more settings, check the [plugin configuration](/integrations/connectors/data-visualization/grafana/config) documentation.
4. Click the **Save & test** button to verify that Grafana can connect to your ClickHouse service. If successful, you will see a **Data source is working** message:
5) Next steps
Your data source is now ready to use! Learn more about how to build queries with the [query builder](/integrations/connectors/data-visualization/grafana/query-builder).
For more details on configuration, check the [plugin configuration](/integrations/connectors/data-visualization/grafana/config) documentation.
If you're looking for more information that isn't included in these docs, check the [plugin repository on GitHub](https://github.com/grafana/clickhouse-datasource).
Upgrading plugin versions
Starting with v4, configurations and queries are able to be upgraded as new versions are released.
Configurations and queries from v3 are migrated to v4 as they're opened. While the old configurations and dashboards will load in v4, the migration isn't persisted until they're saved again in the new version. If you notice any issues when opening an old configuration/query, discard your changes and [report the issue on GitHub](https://github.com/grafana/clickhouse-datasource/issues).
The plugin can't downgrade to previous versions if the configuration/query was created with a newer version.