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

DBeaver 社区版是一个免费的跨平台数据库工具，适用于开发人员、数据库管理员和数据分析师。DBeaver 支持所有流行的 SQL 数据库，如 MySQL、MariaDB、PostgreSQL、SQLite 系列等。

背景信息

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

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

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

准备工作

  • 请通过 官方网站 提前下载并安装好 DBeaver 。

    注意

    推荐使用 24.2.2 及以上版本的 DBeaver，以获得更好的兼容性。

  • 您可以在 租户管理-参数设置 页面设置默认连接的计算组/数据库。
    Image

连接到 ByteHouse

  1. 点击 数据库 - 新建数据库连接，并在页面中选择 “ClickHouse”，单击 下一步。
    Image

  2. 配置连接设置信息。
    Image

    参数

    使用 IAM 用户连接

    使用数据库用户连接

    主机

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

    端口

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

    用户名 & 密码

    • 用户名默认为 bytehouse。
    • 密码为 <API_Key>，可以在 ByteHouse 控制台 > 租户管理 > 连接信息中获取的 API Key。详情请参见获取 API Key。
    • 用户名配置为 {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
    • 密码：数据库账号的密码由管理员创建数据库账号时自定义配置，您可联系管理员获取密码。如果密码丢失或遗忘，可通联系管理员重置密码，详情请参考重置密码。

  3. 切换到 SSL 页面，启用SSL功能。
    Image
    如果您使用的版本与以上界面不同，可在驱动属性页面下，将 ssl 参数设置为 true。
    Image

  4. （可选）在驱动属性页签下配置默认计算组。

    说明

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

    Image

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

  5. 单击左下角“测试连接”，若显示 已连接 则设置成功。
    Image

  6. 单击 完成 ，即可在 DBeaver 程序主页中操作 ByteHouse 数据库。
    Image

常见问题处理

传输层报错 transport error: 500

如果您使用的 DBeaver 版本较新，可能会遇到以下报错：
Image
您可通过配置 DBeaver 驱动管理器解决该问题，操作如下：

  1. 下载 JDBC Driver v0.4.6 文件。
  2. 在 DBeaver 中，通过数据库 > 驱动管理器路径，进入驱动管理器界面，单击 ClickHouse，单击编辑。
    Image
  3. 在编辑驱动界面，单击库页签。
    Image
  4. 单击添加文件，上传步骤 1 中下载的 JDBC Driver v0.4.6 文件。
  5. 选中 com.clickhouse:clickhouse-jdbc:RELEASE [0.x.x] ，单击删除。
  6. 单击确定。

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 配置为 false。
Image

Connection reset（连接重置）报错

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

Connection reset

您可在配置连接设置信息时通过配置驱动属性解决该问题，将 ssl 配置为 true。
Image

版本不兼容报错：only works with ClickHouse servers 20.7 and above

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

We apologize, but this driver only works with ClickHouse servers 20.7 and above. Please consider to upgrade your server to a more recent version.

您可按照下图，在配置驱动属性中设置 server_time_zone 和 server_version 参数值解决该问题。

  • server_time_zone：设置为 Asia/Shanghai。如果您处于其他时区，可根据实际情况设置为对应的时区。
  • server_version：设置为 21.8.7.1。

Image