Connect to TiDB with MySQL Workbench

TiDB is a MySQL-compatible database, and MySQL Workbench is a GUI tool set for MySQL database users.

In this tutorial, you can learn how to connect to your TiDB cluster using MySQL Workbench.

Prerequisites

To complete this tutorial, you need:

If you don't have a TiDB cluster, you can create one as follows:

Connect to TiDB

Connect to your TiDB cluster depending on the TiDB deployment option you have selected.

  • TiDB Cloud Serverless
  • TiDB Cloud Dedicated
  • TiDB Self-Managed
  1. Navigate to the Clusters page, and then click the name of your target cluster to go to its overview page.

  2. Click Connect in the upper-right corner. A connection dialog is displayed.

  3. Ensure the configurations in the connection dialog match your operating environment.

    • Connection Type is set to Public.
    • Branch is set to main.
    • Connect With is set to MySQL Workbench.
    • Operating System matches your environment.
  4. Click Generate Password to create a random password.

  5. Launch MySQL Workbench and click + near the MySQL Connections title.

    MySQL Workbench: add new connection

  6. In the Setup New Connection dialog, configure the following connection parameters:

    • Connection Name: give this connection a meaningful name.

    • Hostname: enter the HOST parameter from the TiDB Cloud connection dialog.

    • Port: enter the PORT parameter from the TiDB Cloud connection dialog.

    • Username: enter the USERNAME parameter from the TiDB Cloud connection dialog.

    • Password: click Store in Keychain ... or Store in Vault, enter the password of the TiDB Cloud Serverless cluster, and then click OK to store the password.

      MySQL Workbench: store the password of TiDB Cloud Serverless in keychain

    The following figure shows an example of the connection parameters:

    MySQL Workbench: configure connection settings for TiDB Cloud Serverless

  7. Click Test Connection to validate the connection to the TiDB Cloud Serverless cluster.

  8. If the connection test is successful, you can see the Successfully made the MySQL connection message. Click OK to save the connection configuration.

  1. Navigate to the Clusters page, and then click the name of your target cluster to go to its overview page.

  2. Click Connect in the upper-right corner. A connection dialog is displayed.

  3. In the connection dialog, select Public from the Connection Type drop-down list, and then click CA cert to download the CA certificate.

    If you have not configured the IP access list, click Configure IP Access List or follow the steps in Configure an IP Access List to configure it before your first connection.

    In addition to the Public connection type, TiDB Dedicated supports Private Endpoint and VPC Peering connection types. For more information, see Connect to Your TiDB Dedicated Cluster.

  4. Launch MySQL Workbench and click + near the MySQL Connections title.

    MySQL Workbench: add new connection

  5. In the Setup New Connection dialog, configure the following connection parameters:

    • Connection Name: give this connection a meaningful name.

    • Hostname: enter the HOST parameter from the TiDB Cloud connection dialog.

    • Port: enter the PORT parameter from the TiDB Cloud connection dialog.

    • Username: enter the USERNAME parameter from the TiDB Cloud connection dialog.

    • Password: click Store in Keychain ..., enter the password of the TiDB Cloud Dedicated cluster, and then click OK to store the password.

      MySQL Workbench: store the password of TiDB Cloud Dedicated in keychain

    The following figure shows an example of the connection parameters:

    MySQL Workbench: configure connection settings for TiDB Cloud Dedicated

  6. Click Test Connection to validate the connection to the TiDB Cloud Dedicated cluster.

  7. If the connection test is successful, you can see the Successfully made the MySQL connection message. Click OK to save the connection configuration.

  1. Launch MySQL Workbench and click + near the MySQL Connections title.

    MySQL Workbench: add new connection

  2. In the Setup New Connection dialog, configure the following connection parameters:

    • Connection Name: give this connection a meaningful name.

    • Hostname: enter the IP address or domain name of your TiDB Self-Managed cluster.

    • Port: enter the port number of your TiDB Self-Managed cluster.

    • Username: enter the username to use to connect to your TiDB.

    • Password: click Store in Keychain ..., enter the password to use to connect to your TiDB cluster, and then click OK to store the password.

      MySQL Workbench: store the password of TiDB Self-Managed in keychain

    The following figure shows an example of the connection parameters:

    MySQL Workbench: configure connection settings for TiDB Self-Managed

  3. Click Test Connection to validate the connection to the TiDB Self-Managed cluster.

  4. If the connection test is successful, you can see the Successfully made the MySQL connection message. Click OK to save the connection configuration.

FAQs

How to handle the connection timeout error "Error Code: 2013. Lost connection to MySQL server during query"?

This error indicates that the query execution time exceeds the timeout limit. To resolve this issue, you can adjust the timeout settings by the following steps:

  1. Launch MySQL Workbench and navigate to the Workbench Preferences page.

  2. In the SQL Editor > MySQL Session section, configure the DBMS connection read timeout interval (in seconds) option. This sets the maximum amount of time (in seconds) that a query can take before MySQL Workbench disconnects from the server.

    MySQL Workbench: adjust timeout option in SQL Editor settings

For more information, see MySQL Workbench frequently asked questions.

Next steps

Need help?

Ask questions on TiDB Community, or create a support ticket.

Was this page helpful?