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

Background information #

ByteHouse supports connecting to DBeaver via IAM user or database user. The differences between IAM users and database users are described as follows. You can choose as needed.

• IAM user is a user created in Volcano Engine access control (IAM), whose privileges are determined by IAM privilege policies and the ByteHouse resource and data privileges you grant. IAM users can access the ByteHouse console, and also support access to ByteHouse via CLI, connection drivers, ecosystem tools, API, and other methods.
• Database user is a database-level user created in ByteHouse, and can be granted environment, resource, and data privileges. Database users cannot access the ByteHouse console, but support access to ByteHouse via CLI, connection drivers, ecosystem tools, API, and other methods.

For more information about IAM users and database users, please refer to the following documents:

• Overview
• User Management
• Manage Database Accounts

Preparation #

1. Please download and install DBeaver in advance from the official website.

   warning

   It is recommended to use DBeaver version 24.2.2 or above for better compatibility.

2. Click here to obtain the latest version jar file of the ByteHouse JDBC Driver.
3. You can set the default compute group/database for the connection on the Tenant Management - Parameter Settings page.
   

Configure the ByteHouse driver #

1. Launch DBeaver, and under the Database tab, select Driver Manager.
   
2. Click "New".
   
3. On the Settings tab, enter the following connection information as shown:
   
   • Class name: com.bytedance.bytehouse.jdbc.ByteHouseDriver.
   • URL template: jdbc:bytehouse://{host}:{port}/?secure=true. Here, the {HOST}:{PORT} field depends on the region where the cluster is located. Please refer to Step 2: Set network informationGet relevant information.
   • Default port: 19000.
4. Switch to the "Library" tab, click Add File, and select the ByteHouse JDBC Driver file prepared earlier.
   
5. Switch to the "Advanced Parameters" tab, and uncheck the two configurations shown below.

   warning

   If this is ignored, an error may occur when querying tables with a large number of rows, such as:
   SQL Error [396]: DB::ExceptionDB::Exception: Limit for result exceeded, max rows: 200.00, current rows: 8.19 thousand SQLSTATE: 54000. Stack trace:...

   
6. Click OK to save.

Connect to ByteHouse #

1. Click Database - New Database Connection, and select "ByteHouse" on the page, then click Next.
   

2. Fill in the following connection information fields:
   

   Parameters	Connect using IAM user	Connect using database user
   Host	Configure as the network domain name of ByteHouse. You can obtain it in the ByteHouse Console under Tenant Management > Basic Information > Network Information. For details, see Step 2: Set network information.
   Port	Database port number. Configure as the fixed value: 19000.
   Username & password	The username defaults to bytehouse. The password is <API_Key>, which can be obtained in the ByteHouse Console > Tenant Management > Connection Information as the API Key. For details, see Obtain API key.	The username is configured as {accountID_or_accountName}::{username}[::{envID}]. For details, see Step 3: Obtain ByteHouse connection string information: {accountID_or_accountName}: Refers to the BytePlus user account ID or name. Log in to the ByteHouse Console, click the profile in the upper right to view and copy the account ID or name. {username}: The username of the ByteHouse database account for login. You can view the database username in ByteHouse Console > Access Control > User > View Database Username. {envID}: Optional configuration, the name of the environment where the database is located. If using the default environment, configuration is not required. To use another environment, specify the environment name. Do not add [] when configuring. You can log in to the ByteHouse Console and obtain it in Tenant management > Basic information > Current environment. Examples are as follows: Configure environment ID: 21xxxxxxxx::demouser::demoenv Without configuring environment ID: 21xxxxxxxx::demouser Password: The password for the database account 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 the password. For details, refer to Reset Password.

3. Click "Test Connection" in the lower left corner. If Connected is displayed, the setup is successful.

4. Click Finish, and you can operate the ByteHouse database from the DBeaver program homepage.