Connect to TiDB with MySQL Workbench

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

Warning

• Although you can use MySQL Workbench to connect to TiDB due to its MySQL compatibility, MySQL Workbench does not fully support TiDB. You might encounter some issues during usage as it treats TiDB as MySQL.
• It is recommended to use other GUI tools that officially support TiDB, such as DataGrip, DBeaver, and VS Code SQLTools. For a complete list of GUI tools that fully supported by TiDB, see Third-party tools supported by TiDB.

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

Note

This tutorial is compatible with TiDB Serverless, TiDB Dedicated, and TiDB Self-Hosted.

Prerequisites

To complete this tutorial, you need:

• MySQL Workbench 8.0.31 or later versions.
• A TiDB cluster.

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

• (Recommended) Follow Creating a TiDB Serverless cluster to create your own TiDB Cloud cluster.
• Follow Deploy a local test TiDB cluster or Deploy a production TiDB cluster to create a local cluster.

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

• (Recommended) Follow Creating a TiDB Serverless cluster to create your own TiDB Cloud cluster.
• Follow Deploy a local test TiDB cluster or Deploy a production TiDB cluster to create a local cluster.

Connect to TiDB

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

• TiDB Serverless
• TiDB Dedicated
• TiDB Self-Hosted

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.

   • Endpoint 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.

   

   Tip

   If you have created a password before, you can either use the original password or click Reset Password to generate a new one.

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

   

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 Serverless cluster, and then click OK to store the password.

     

   The following figure shows an example of the connection parameters:

   

7. Click Test Connection to validate the connection to the TiDB 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.

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

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

11. Click Allow Access from Anywhere.

    For more details about how to obtain the connection string, refer to TiDB Dedicated standard connection.

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

    

13. 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 Dedicated cluster, and then click OK to store the password.

      

    The following figure shows an example of the connection parameters:

    

14. Click Test Connection to validate the connection to the TiDB Dedicated cluster.

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

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

    

17. 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-Hosted cluster.

    • Port: enter the port number of your TiDB Self-Hosted 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.

      

    The following figure shows an example of the connection parameters:

    

18. Click Test Connection to validate the connection to the TiDB Self-Hosted cluster.

19. 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.

   

For more information, see MySQL Workbench frequently asked questions.

Next steps

• Learn more usage of MySQL Workbench from the documentation of MySQL Workbench.
• Learn the best practices for TiDB application development with the chapters in the Developer guide, such as Insert data, Update data, Delete data, Single table reading, Transactions, and SQL performance optimization.
• Learn through the professional TiDB developer courses and earn TiDB certifications after passing the exam.

Need help?

Ask questions on the Discord, or create a support ticket.

Ask questions on the Discord, or create a support ticket.