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 describes how DataGrip connects to ByteHouse Cloud Data Warehouse Edition via JDBC driver using TCP.

Background information #

ByteHouse supports connecting DataGrip using IAM users or database users. The differences between IAM users and database users are explained below. You can choose as needed.

• IAM users are users created in Volcano Engine Identity and Access Management (IAM). Their permissions are determined by IAM permission policies and the ByteHouse resource and data permissions you grant. IAM users can access the ByteHouse console, and can also access ByteHouse via CLI, connection drivers, ecosystem tools, API, and more.
• Database users are database-level users created in ByteHouse. You can grant them environment, resource, and data permissions. Database users cannot access the ByteHouse console, but can access ByteHouse via CLI, connection drivers, ecosystem tools, API, and more.

For more information about IAM users and database users, see the following documentation:

• Overview
• User Management
• Manage Database Accounts

Prerequisites #

• Please install DataGrip in advance and obtain the appropriate commercial license.
• Click here to download the latest version of the ByteHouse JDBC Driver jar file.
• You can set the default compute group/database for connection on the Tenant Management - Parameter Settings page.
  

Usage restrictions #

When connecting using the ByteHouse JDBC TCP driver, the setting max_result_rows may not take effect. Therefore, the pagination feature is not well supported. The expected number of returned rows may differ from the actual number of returned rows.

This issue can be resolved by configuring DataGrip as follows:

1. Go to the DataGrip - Settings - Database - Data Editor and Viewer tab.
2. Clear the checkbox for the first item under Limit, "Limit page size to".
3. Click the OK button to save the settings.
   

Connect to ByteHouse using DataGrip #

1. Launch DataGrip, click the + icon on the Database Explorer tab, and select Driver.
   

2. Customize the driver name, such as "ByteHouse JDBC Driver". Click the + sign in Driver Files, select Custom JAR in the pop-up window, and choose the locally downloaded JDBC driver jar file.
   

3. In Class, select com.bytedance.bytehouse.jdbc.ByteHouseDriver, and click Apply to save.
   

4. On the Database Explorer tab, click the + icon, select Data Source -> ByteHouse JDBC Driver.
   

5. Configure the data source connection information. You can connect using an IAM user or a database user. See the table below for parameter descriptions.
   

   Parameters	Connect using IAM user	Connect using database user
   Name	Custom connection name.
   Username & Password	Username and password for logging in to the ByteHouse database. The default username is bytehouse. The password is <API_Key>, which can be obtained from 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 Volcano Engine user account ID or name. You can log in to the ByteHouse Console, click the user center in the upper right corner to view and copy the account ID or name. {username}: Username for logging in to the ByteHouse database account. You can find it in ByteHouse Console > Permission Management > User > View Database Username. {envID}: Optional configuration, the name of the environment where the database is located. If using the default environment, this can be omitted. To use another environment, specify the environment name. Do not add [] when configuring. You can log in to the ByteHouse Console and obtain it from Tenant management> Basic information> Current environment . Usage examples are as follows: With environment ID configured: 21xxxxxxxx::demouser::demoenv Without environment ID configured: 21xxxxxxxx::demouser Password: The password for the database account is custom set 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, see Reset Password.
   URL	The field format is as follows: jdbc:bytehouse://{HOST}:{PORT}/?secure=true&user=bytehouse&password={API_KEY} {HOST}: Configure as the network domain name of ByteHouse. You can view the corresponding information in the ByteHouse console under Tenant Management > Basic Information > Network Information. For details, see Step 2: Set network information. {PORT}: Configure as 19000.	The field format is as follows: jdbc:bytehouse://{HOST}:{PORT}/?secure=true&user={accountID_or_accountName}::{username}[::{envID}]&password={password} {HOST}: Configure as the network domain name of ByteHouse. You can view the corresponding information in the ByteHouse console under Tenant Management > Basic Information > Network Information. For details, see Step 2: Set network information. {PORT}: Configure as 19000.

6. Click Test Connection. If "Success" is displayed, the connection is established successfully.

   tip

   Due to differences in how third-party software recognizes special characters in the Password field within the URL, if you are unable to connect correctly after setting up as described above, try manually entering the password in the Password field and testing the connection again.

Reference #

To learn more about DataGrip, visit the official DataGrip documentation.