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 用户和数据库用户的介绍请参见以下文档：

• ByteHouse权限管控概述
• 管理 IAM 用户
• 管理数据库用户

准备工作 #

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

  注意

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

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

连接到 ByteHouse #

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

2. 配置连接设置信息。
   

   参数	使用 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功能。
   
   如果您使用的版本与以上界面不同，可在驱动属性页面下，将 ssl 参数设置为 true。
   

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

   说明

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

   

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

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

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

常见问题处理 #

传输层报错 transport error: 500 #

如果您使用的 DBeaver 版本较新，可能会遇到以下报错：

您可通过配置 DBeaver 驱动管理器解决该问题，操作如下：

1. 下载 JDBC Driver v0.4.6 文件。
2. 在 DBeaver 中，通过数据库 > 驱动管理器路径，进入驱动管理器界面，单击 ClickHouse，单击编辑。
   
3. 在编辑驱动界面，单击库页签。
   
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。

Connection reset（连接重置）报错 #

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

Connection reset

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

版本不兼容报错：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。