DataGrip is an integrated development environment (IDE) developed by JetBrains specifically for database developers and administrators. It supports various database management systems, provides intelligent code completion, and facilitates version control integration.
This article introduces how DataGrip connects to ByteHouse Cloud Data Warehouse Edition using the open-source ClickHouse driver.

Context #

ByteHouse supports connecting DataGrip via IAM users or database users. The differences between IAM users and database users are described as follows. You can choose according to your needs.

• IAM users are users created in BytePlus access control (IAM), whose privileges are determined by IAM privilege policy and the ByteHouse resources and data privileges you grant. IAM users can access the ByteHouse Console and can also access ByteHouse via CLI, connection drivers, ecosystem tools, API, and others.
• Database users are database-level users created in ByteHouse. You can grant environment, resources, and data privileges to them. Database users cannot access the ByteHouse Console, but can access ByteHouse via CLI, connection drivers, ecosystem tools, API, and others.

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

• Overview
• User Management
• Manage Database Accounts

Prerequisites #

1. Please install DataGrip in advance and acquire the corresponding commercial license.
2. You can set the default virtual warehouse/database for connection on the Tenant Management - Parameter Setting page.
   

Connect to ByteHouse using DataGrip #

1. Launch DataGrip, click the + icon on the Database Explorer tab, and select Data Source -> ClickHouse.

   warning

   If the interface prompts you to download the driver, click "Download" to complete the driver download.
   

2. Configure the ByteHouse Data Source fields.
   

   Parameter	Connect using IAM user	Connect using database user
   Name	Customize the connection name.
   Host	Configure as the ByteHouse network domain name, which can be obtained in ByteHouse Console under Tenant management > basic information > network information. For details, see Step 2: Set network information.
   Port	Database port number, set as the fixed value: 8123.
   User & Password	Username and password for logging in to the ByteHouse database. Username defaults to bytehouse. Password is <API_Key>, which can be obtained in ByteHouse Console > Tenant management > connection information as the API Key. For details, see Obtain API key.	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 ByteHouse Console, click Profile in the upper right corner to view and copy the account ID or name. {username}: Username for logging in to the ByteHouse database account. Available in ByteHouse Console > access control > User > View database username. {envID}: Optional configuration, the environment name where the database is located. If using the default environment, configuration is not required. To use other environments, specify the environment name. Do not add [] when configuring. You can log in to ByteHouse Console, and obtain it in Tenant management > Basic information > Current environmentto obtain. Examples are as follows: Configure environment ID: 21xxxxxxxx::demouser::demoenv Without environment ID: 21xxxxxxxx::demouser password: The password for the database account is custom configuration 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.
   URL	The field format is as follows: jdbc:clickhouse://{HOST}:{PORT}/?secure=true&user=bytehouse&password={API_KEY}	The field format is as follows: jdbc:clickhouse://{HOST}:{PORT}/?secure=true&user={accountID_or_accountName}::{username}[::{envID}]&password={password}

3. Switch to the SSH/SSL tab and check Use SSL.
   

4. Switch to the Schemas tab and select the database to connect (you can click the refresh button to refresh the list).
   

5. (Optional) Set the default virtual warehouse.

   tip

   To set the Default virtual warehouse used after connecting to ByteHouse when you have multiple virtual warehouses, refer to this Step. If you do not set it, the Default virtual warehouse set in the Console will be used after connecting to ByteHouse.

   
   On the Advanced tab, set custom_settings to virtual_warehouse=your_virtualwarehouse_id.
   Here, your_virtualwarehouse_id is the default virtual warehouse ID used after connecting to ByteHouse. You can view the corresponding virtual warehouse ID on the virtual warehouse page in the ByteHouse Console.

6. Click Test Connection. If Succeeded is displayed, the connection is successful.

FAQ processing #

[22000] Code: 0 error #

If you encounter the following error during the connection process:

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

You can resolve this issue by adjusting the driver version of the ClickHouse datasource:
Set the driver version of the ClickHouse datasource to 0.6.3. On the Drivers tab, click ClickHouse, then on the right side under Driver Files click +, click Provided Driver, select ClickHouse, and choose version 0.6.3.

LZ4 is not supported (LZ4 不支持) error #

If you encounter the following error during the connection process:

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 fix this problem by disabling the compress parameter:
Click the added ClickHouse data source under the Data Source tab, then click the Advanced tab on the right, and set the compress parameter to false.

Connection reset (连接重置) error #

If you encounter the following error during the connection process:

You can fix this problem by activating the ssl operation:
Click the added ClickHouse data source under the Data Source tab, then click the Advanced tab on the right, and set the ssl parameter to true.

Reference #

For more details about DataGrip, visit the DataGrip official documentation.