You need to enable JavaScript to run this app.
导航
ByteHouse云数仓版
  • 文档首页
    • /ByteHouse云数仓版/用户指南/生态工具/IDE工具/DataGrip（ClickHouse）
DataGrip（ClickHouse）
最近更新时间：2025.08.20 10:58:40首次发布时间：2024.12.25 17:16:41
复制全文
我的收藏
有用
有用
无用
无用

DataGrip 是 JetBrains 公司专为数据库开发人员和管理员设计的一套集成开发环境（IDE）。它支持各种数据库管理系统，提供智能代码完成，并便于版本控制集成。
本文将介绍 DataGrip 如何通过开源 ClickHouse 驱动连接 ByteHouse 云数仓版。

背景信息

ByteHouse 支持通过 IAM 用户或数据库用户连接 DataGrip。IAM 用户与数据库用户二者差异说明如下，您可按需选择。

  • IAM 用户为火山引擎访问控制（IAM）中创建的用户，其权限由 IAM 权限策略及您授予的 ByteHouse 资源和数据权限决定。IAM 用户可访问 ByteHouse 控制台，也支持通过 CLI、连接驱动、生态工具、API 等方式访问 ByteHouse。
  • 数据库用户为 ByteHouse 中创建的数据库级别用户，可为其授予环境、资源和数据权限。数据库用户不可访问 ByteHouse 控制台，但支持通过 CLI、连接驱动、生态工具、API 等方式访问 ByteHouse。

更多 IAM 用户和数据库用户的介绍请参见以下文档：

前提条件

  1. 请提前安装好 DataGrip ，并获得相应的商用授权。
  2. 您可以在 租户管理-参数设置 页面设置默认连接的计算组/数据库。
    Image

使用 DataGrip 连接 ByteHouse

  1. 启动 DataGrip，在 Database Explorer 页签单击 + 图标，选择 Data Source -> ClickHouse。
    Image

    注意

    如果界面提示需要下载驱动，请点击“Download”完成驱动下载。
    Image

  2. 配置 ByteHouse Data Source 字段。
    Image

    参数

    使用 IAM 用户连接

    使用数据库用户连接

    Name

    自定义连接名称。

    Host

    配置为 ByteHouse 的网络域名，您可以在 ByteHouse 控制台的租户管理 > 基本信息 > 网络信息中获取。详情请参见步骤二：配置网络信息。

    Port

    数据库端口号，配置为固定取值：8123。

    User & Password

    登录 ByteHouse 数据库的用户名和密码。

    • User Name 默认为 bytehouse。
    • 密码为 <API_Key>，可以在 ByteHouse 控制台 > 租户管理 > 连接信息中获取的 API Key。详情请参见获取 API Key。
    • User Name 配置为 {accountID_or_accountName}::{username}[::{envID}]，详情请参见步骤三：获取 ByteHouse 连接串信息：
      • {accountID_or_accountName}：指火山引擎用户账号 ID 或名称，可登录 ByteHouse 控制台，单击右上角个人中心查看并复制账号 ID 或名称。
      • {username}：登录 ByteHouse 数据库账号用户名。可在 ByteHouse 控制台 > 权限管理 > 用户 > 查看数据库用户名。
      • {envID}：可选配置，数据库所在的环境名称。如果使用 default 环境，可不配置；如需使用其他环境，需指定环境名称，配置时无需添加[]。您可登录 ByteHouse 控制台，在租户管理 > 基本信息 > 当前环境中获取。
        使用示例如下：
        • 配置环境 ID：21xxxxxxxx::demouser::demoenv
        • 不配置环境 ID：21xxxxxxxx::demouser
    • password：数据库账号的密码由管理员创建数据库账号时自定义配置，您可联系管理员获取密码。如果密码丢失或遗忘，可通联系管理员重置密码，详情请参考重置密码。

    URL

    字段格式如下：

    jdbc:clickhouse://{HOST}:{PORT}/?secure=true&user=bytehouse&password={API_KEY}

    字段格式如下：

    jdbc:clickhouse://{HOST}:{PORT}/?secure=true&user={accountID_or_accountName}::{username}[::{envID}]&password={password}

  3. 切换到 SSH/SSL 页签，勾选 Use SSL。
    Image

  4. 切换到 Schemas 页签选择需要连接的数据库（可以点刷新按钮获取）。
    Image

  5. （可选）设置默认计算组。

    说明

    如果您有多个计算组，连接 ByteHouse 后使用的默认计算组，可参考本步骤设置默认计算组；如果不设置，则连接 ByteHouse 后使用控制台设置的默认计算组。

    Image
    在 Advanced 页签设置 custom_settings 为 virtual_warehouse=your_virtualwarehouse_id。
    其中your_virtualwarehouse_id为连接 ByteHouse 后使用的默认计算组 ID，您可以在 ByteHouse 控制台的计算组页面查看对应计算组的 ID。

  6. 单击 Test Connection，显示 Succeeded 则连接成功。

说明

因第三方软件对 URL 中 Password 字段包含特殊字符识别可能带来差异，如果您按上方正确设置后仍无法正确连接，请尝试在 Password 密码框中手动填写密码后再次测试连接。

常见问题处理

[22000] Code: 0 报错

如果您在连接过程中遇到以下报错：

[22000] Code: 0. DB::Exception: <Unreadable error message> (transport error: 500).

Image
您可通过调整 ClickHouse 数据源的驱动版本解决该问题：
将 ClickHouse 数据源的驱动版本调整为 0.6.3。在 Drivers 页签下单击 ClickHouse，在右侧 Driver Files 中单击 +，单击 Provided Driver，选择 ClickHouse，选择版本为 0.6.3。
Image

LZ4 is not supported（LZ4 不支持）报错

如果您在连接过程中遇到以下报错：

LZ4 is not supported. Please disable compression(compress=0), modify the algorithm(e.g. compress_algorithm=gzip), or add the missing libraries to the classpath.

您可通过禁用 compress 参数解决该问题：
单击 Data Source 页签下已添加的 ClickHouse 数据源，单击右侧的 Advanced 页签，将 compress 参数设置为 false。
Image

Connection reset（连接重置）报错

如果您在连接过程中遇到以下报错：
Image
您可通过启用 ssl 操作解决该问题：
单击 Data Source 页签下已添加的 ClickHouse 数据源，单击右侧的 Advanced 页签，将 ssl 参数设为为 true。
Image

参考

要了解有关 DataGrip 的更多信息，请访问 DataGrip官方文档。