DBeaver Community Edition is a free cross-platform database tool for developers, database administrators, and data analysts. DBeaver supports all popular SQL databases such as MySQL, MariaDB, PostgreSQL, and SQLite series.

Prerequisites #

• Download and install DBeaver in advance through the official website.

  warning

  Recommended to use DBeaver version 24.2.2 or above for better compatibility.

• You can set the default connection's compute group/database on the Tenant Management - Parameter setting page.
  

Connect to ByteHouse #

1. Click Database - New Database Connection, select “ClickHouse” on the page, and click Next.
   

2. Configure connection settings.
   

   Parameter	Connect using IAM user	Connect using database user
   Host	Configure the network domain name for ByteHouse, which you can find in ByteHouse Console under Tenant Management>basic information>Network Information. See details Step 2: Set network information.
   Port	Database port number, configured with a fixed value: 8123.
   Username & password	The default username is bytehouse. The password is <API_Key>, which can be obtained from ByteHouse Console>Tenant Management>Connection Information API Key. See details Obtain API key.	The username is configured as {accountID_or_accountName}::{username}[::{envID}]. See details Step 3: Obtain ByteHouse connection string information: accountID_or_accountName: refers to the BytePlus user account ID or name. You can log in to ByteHouse Console, click the top right Profile to view and copy the account ID or name. username: the username for logging into the ByteHouse database account. Can be viewed in ByteHouse Console>ad_auth_management>User>View Database Username. envID: Optional configuration, the name of the environment where the database is located. If using the default environment, no configuration is needed; to use other environments, specify the environment name. You can log in to the ByteHouse Console and get it under Tenant Management>basic information>current environment. Password: The database account password is customized by the Administrator when creating the database account; you can contact the Administrator to obtain the password. If the password is lost or forgotten, contact the Administrator to reset it; see Reset Password for details.

3. Switch to the SSL page and enable the SSL feature.
   
   If your version differs from the above interface, set the ssl parameter to true on the driver properties page.
   

4. (Optional) Configure the default calculation group under the driver properties tab.

   tip

   If you have multiple compute groups, you can set the default compute group used after connecting to ByteHouse in this step; if not set, the default compute group configured in the console will be used after connecting.

   

   • Set custom_settings to virtual_warehouse=your_virtualwarehouse_id.
   • Here, your_virtualwarehouse_id is the default calculation group ID used after connecting to ByteHouse. You can find the corresponding calculation group ID on the Calculation Group page in the ByteHouse Console.

5. Click “Test Connection” at the bottom left. If it shows Connected, the setup is successful.
   

6. Click Complete to work with the ByteHouse database on the DBeaver main interface.

FAQ #

Connection error #

If you are using a newer version of DBeaver, you may encounter the following error:

You can resolve this issue by configuring the DBeaver driver manager as follows:

1. Download the JDBC Driver v0.4.6 file.
2. In DBeaver, go to Database>Driver Manager, enter the driver manager interface, click ClickHouse, then click Edit.
   
3. In the edit driver interface, click the Libraries tab.
   
4. Click Add File and upload the JDBC Driver v0.4.6 file downloaded in step 1.
5. Select com.clickhouse:clickhouse-jdbc:RELEASE [0.x.x] and click Delete.
6. Click Confirm.

LZ4 is not supported error #

If you encounter the following error during connection:

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.

You can resolve this issue by configuring the driver property in the connection settings and setting compress to false.

Connection reset error #

If you encounter the following error during connection:

Connection reset

You can resolve this issue by configuring the driver property in the connection settings and setting ssl to true.