TablePlus is a cross-platform database management tool designed to simplify database connection, querying, editing, and management processes. It supports managing MySQL, PostgreSQL, SQLite, SQL Server, Oracle, and other databases. This article explains how to connect to and use the MySQL and ClickHouse databases created in ByteHouse within TablePlus.

• You have installed TablePlus. For details, see the TablePlus official website.
• The database user feature is currently in Beta. To connect to TablePlus using a database user, please submit a support ticket or contact the ByteHouse team to get whitelist access.

ByteHouse supports connections via IAM users or database users. Configure your user account information before using this tool. For the difference between IAM users and database users, please refer toOverview.

Step 1 Configure network domain #

After logging into the ByteHouse console, go to the Tenant Management section and then the Basic Information page. Check the network group configuration to confirm that the VPC is bound and that a public domain is linked.

• If the VPC and public domain are not bound, refer to the Network information settingsdocumentation to complete the binding configuration.
• After binding, click to copy the public domain name for later parameter configuration.

step2 set the default compute group #

go to the Tenant Management > Parameter Settings page at the top, check the set default compute group, and ensure this compute group is running and not stopped. all subsequent operations, such as data queries after connecting to ByteHouse, will use the default compute group configured here.

step 3 obtain user and password information for the connection string #

connect using an IAM user #

IAM users use an API Key as the connection password. You can create a new API key in the API Key module on the Tenant Management > Connection Information page at the top and save the API key locally for later configuration.

connect using a database user #

the database user's account consists of the ByteHouse account, database username, account, and optionally the environment ID, formatted as {accountID_or_accountName}::{username}[::{envID}]. the password is the database user's password.

obtain account information

After logging in and entering the ByteHouse console, click the profile icon in the top right to view and copy your account ID or name.

Configure database user and password

After logging in and entering the ByteHouse console, go to the Permission Management section at the top, then to the User page. View the user list, filter users by Database type, then view and copy the database username. If no database user has been created, contact the administrator for Manage Database Accountscreation guidance.
The database user password is set by the administrator. Contact the administrator to obtain the password. If the password is lost or forgotten, contact the administrator to reset it. For details, please refer to Reset Passwordthe documentation.

(Optional) Obtain environment information

If using the default environment, no configuration is needed. To use another environment, specify the environment name. You can log in and enter the ByteHouse console, then go to the Tenant Management section at the top, and open the Basic Information page to view the current environment name.

You can create MySQL or ClickHouse data sources using TablePlus and connect them to ByteHouse.

Connect MySQL database driver #

1. Launch TablePlus, right-click in the blank area on the right side of the interface, then click New > Connection.

2. Search for and select MySQL in the popup window, then click Create.

   

3. In the MySQL Connection popup, fill in the configuration information according to the connection details obtained from ByteHouse 侧配置here:

   

   Parameter	Connect using IAM user	Connect using database user
   Name	Custom connection name.
   Host/IP	Set as ByteHouse network domain name in the format: tenant-{TENANT_ID}-{REGION}-public.bytehouse.volces.com. You can find this in ByteHouse Console under Tenant Management>Basic Information>Network Information. For details, see Step 2: Set network information.
   Port	Database port number, set to the fixed value: 3306.
   User & Password	You can obtain the API Key in the ByteHouse Console>Tenant Management>Connection Information. See Obtain API keyfor details. User is the first half of the API Key. For example, if the API Key is xxxx.yyyy, User should enter xxxx. The password is the second half of the API Key. For example, if the API Key is xxxx.yyyy, the password should be yyyy.	User Name is configured as {accountID_or_accountName}::{username}[::{envID}]. See Step 3: Obtain ByteHouse connection string informationfor details: accountID_or_accountName: refers to the Volcano Engine user account ID or name. You can log in to the ByteHouse Console, click the top right personal center, and view and copy the account ID or name. username: the ByteHouse database account username. You can find this in the ByteHouse Console>Permission Management>Users>View Database Usernames. envID: optional configuration representing 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. You can log in to the ByteHouse console and find it under Tenant Management>Basic Information>Current Environment. password: The database user's password is 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 it. For details, please refer to Reset Password.
   Database	Enter your database name or leave blank.
   SSL	Select REQUIRED.

4. Click Test to check if the connection is successful. When the input box background turns green, it indicates a successful connection.
   The example of a successful connection is shown below:

   

5. After successfully testing the connection, click Connect to create the connection.

6. (Optional) Configure the compute group information. Click Bootsrap commands to add the set virtual_warehouse='virtual_warehouse_id' bootstrap command.
   'virtual_warehouse_id' should be set to the ByteHouse compute group ID you use. You can find the required compute group ID by logging into the ByteHouse console and clicking the compute groups tab at the top.
   
   Before using the SQL editor each time, run set virtual_warehouse='virtual_warehouse_id'.
   

Connect to ClickHouse database driver #

1. Launch TablePlus, right-click on the blank area on the right side of the interface, then click New > Connection.

2. Search for and select ClickHouse in the pop-up window, then click Create.

   

3. In the ClickHouse Connection pop-up, fill in the configuration according to the connection information obtained from ByteHouse 侧配置here:

   

   Parameters	Connect using IAM user	Connect using database user
   Name	Custom connection name.
   Host	Set as the ByteHouse network domain name in this format: tenant-{TENANT_ID}-{REGION}-public.bytehouse.volces.com. You can find it in ByteHouse console under Tenant Management > Basic Information > Network Information. For details, see Step 2: Set network information.
   Port	The database port, set to the fixed value: 19000.
   User & Password	The username and password for logging into the ByteHouse database. User Name defaults to bytehouse. Password is <API_Key>, which can be obtained from the ByteHouse Console>Tenant Management>Connection Information API Key. See Obtain API keydetails for more information.	User Name is configured as {accountID_or_accountName}::{username}[::{envID}]. See Step 3: Obtain ByteHouse connection string informationdetails: accountID_or_accountName refers to the BytePlus user account ID or name. You can log in to the ByteHouse Console, click the upper right Profile to view and copy the account ID or name. username is the username of the ByteHouse database account. You can find it in ByteHouse Console>ad_auth_management>View Database Username. envID is an optional configuration for the environment name where the database is located. If using the Default environment, no configuration is needed; specify the environment name for other environments. You can log in to the ByteHouse Console, and obtain it in Tenant Management>basic information>currentenvironment. password is the database account password 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, reference Reset Password for details.
   Database	Enter your database name or leave empty.
   SSL	Select USE SSL(SKIP VALIDATE).

4. Click Test to verify the connection. When the input box background turns green, the connection is successful.
   An example of a successful connection is shown below:

   

5. After the connection test succeeds, click Connect to create the connection.

6. (Optional) Configure compute group information. Click Bootstrap commands to add the bootstrap command set virtual_warehouse='virtual_warehouse_id'.
   'virtual_warehouse_id' is set to the ByteHouse compute group ID you use. You can find the required compute group ID by logging into the ByteHouse console and clicking the compute group tab at the top.
   
   Before each use of the SQL editor, run set virtual_warehouse='virtual_warehouse_id'.