diff --git a/TOC-tidb-cloud.md b/TOC-tidb-cloud.md index 7efacd2bd1fbc..17c96b8622416 100644 --- a/TOC-tidb-cloud.md +++ b/TOC-tidb-cloud.md @@ -19,7 +19,9 @@ - [Build a TiDB Serverless Cluster in TiDB Cloud](/develop/dev-guide-build-cluster-in-cloud.md) - [CRUD SQL in TiDB](/develop/dev-guide-tidb-crud-sql.md) - Connect to TiDB Cloud - - [JetBrains DataGrip](/develop/dev-guide-gui-datagrip.md) + - GUI Database Tools + - [JetBrains DataGrip](/develop/dev-guide-gui-datagrip.md) + - [DBeaver](/develop/dev-guide-gui-dbeaver.md) - [Choose Driver or ORM](/develop/dev-guide-choose-driver-or-orm.md) - Java - [JDBC](/develop/dev-guide-sample-application-java-jdbc.md) diff --git a/TOC.md b/TOC.md index 00f5382d0ade5..7ce397aa7df2a 100644 --- a/TOC.md +++ b/TOC.md @@ -49,7 +49,9 @@ - [mysql2](/develop/dev-guide-sample-application-ruby-mysql2.md) - [Rails](/develop/dev-guide-sample-application-ruby-rails.md) - Connect to TiDB - - [JetBrains DataGrip](/develop/dev-guide-gui-datagrip.md) + - GUI Database Tools + - [JetBrains DataGrip](/develop/dev-guide-gui-datagrip.md) + - [DBeaver](/develop/dev-guide-gui-dbeaver.md) - [Choose Driver or ORM](/develop/dev-guide-choose-driver-or-orm.md) - [Connect to TiDB](/develop/dev-guide-connect-to-tidb.md) - [Connection Pools and Connection Parameters](/develop/dev-guide-connection-parameters.md) diff --git a/develop/dev-guide-gui-dbeaver.md b/develop/dev-guide-gui-dbeaver.md new file mode 100644 index 0000000000000..026e2fc0fb5c9 --- /dev/null +++ b/develop/dev-guide-gui-dbeaver.md @@ -0,0 +1,166 @@ +--- +title: Connect to TiDB with DBeaver +summary: Learn how to connect to TiDB using DBeaver Community. +--- + +# Connect to TiDB with DBeaver + +TiDB is a MySQL-compatible database, and [DBeaver Community](https://dbeaver.io/download/) is a free cross-platform database tool for developers, database administrators, analysts, and everyone working with data. + +In this tutorial, you can learn how to connect to your TiDB cluster using DBeaver Community. + +> **Note:** +> +> This tutorial is compatible with TiDB Serverless, TiDB Dedicated, and TiDB Self-Hosted. + +## Prerequisites + +To complete this tutorial, you need: + +- [DBeaver Community **23.0.3** or higher](https://dbeaver.io/download/). +- A TiDB cluster. + + + +**If you don't have a TiDB cluster, you can create one as follows:** + +- (Recommended) Follow [Creating a TiDB Serverless cluster](/develop/dev-guide-build-cluster-in-cloud.md) to create your own TiDB Cloud cluster. +- Follow [Deploy a local test TiDB cluster](/quick-start-with-tidb.md#deploy-a-local-test-cluster) or [Deploy a production TiDB cluster](/production-deployment-using-tiup.md) 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](/develop/dev-guide-build-cluster-in-cloud.md) to create your own TiDB Cloud cluster. +- Follow [Deploy a local test TiDB cluster](https://docs.pingcap.com/tidb/stable/quick-start-with-tidb#deploy-a-local-test-cluster) or [Deploy a production TiDB cluster](https://docs.pingcap.com/tidb/stable/production-deployment-using-tiup) to create a local cluster. + + + +## Connect to TiDB + +Connect to your TiDB cluster depending on the TiDB deployment option you've selected. + + +
+ +1. Navigate to the [**Clusters**](https://tidbcloud.com/console/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` + - **Connect With** is set to `JDBC` + - **Operating System** matches your environment. + +4. Click **Create 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 DBeaver and click **New Database Connection** in the upper-left corner. In the **Connect to a database** dialog, select **TiDB** from the list, and then click **Next**. + + ![Select TiDB as the database in DBeaver](/media/develop/dbeaver-select-database.jpg) + +6. Copy the JDBC string from the TiDB Cloud connection dialog. In DBeaver, select **URL** for **Connect by** and paste the JDBC string into the **URL** field. You don't need to replace the `` placeholder in the string with your actual password, because DBeaver reads username and password from the **Authentication (Database Native)** section. + +7. In the **Authentication (Database Native)** section, enter your **Username** and **Password**. An example is as follows: + + ![Configure connection settings for TiDB Serverless](/media/develop/dbeaver-connection-settings-serverless.jpg) + +8. Click **Test Connection** to validate the connection to the TiDB Serverless cluster. + + If the **Download driver files** dialog is displayed, click **Download** to get the driver files. + + ![Download driver files](/media/develop/dbeaver-download-driver.jpg) + + If the connection test is successful, the **Connection test** dialog is displayed as follows. Click **OK** to close it. + + ![Connection test result](/media/develop/dbeaver-connection-test.jpg) + +9. Click **Finish** to save the connection configuration. + +
+
+ +1. Navigate to the [**Clusters**](https://tidbcloud.com/console/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. Click **Allow Access from Anywhere**, and then click **Download TiDB cluster CA** to download the CA certificate. + + For more details about how to obtain the connection string, refer to [TiDB Dedicated standard connection](https://docs.pingcap.com/tidbcloud/connect-via-standard-connection). + +4. Launch DBeaver and click **New Database Connection** in the upper-left corner. In the **Connect to a database** dialog, select **TiDB** from the list, and then click **Next**. + + ![Select TiDB as the database in DBeaver](/media/develop/dbeaver-select-database.jpg) + +5. Copy and paste the appropriate connection string into the DBeaver connection panel. The mappings between DBeaver fields and TiDB Dedicated connection string are as follows: + + | DBeaver field | TiDB Dedicated connection string | + |---------------| ------------------------------- | + | Server Host | `{host}` | + | Port | `{port}` | + | Username | `{user}` | + | Password | `{password}` | + + An example is as follows: + + ![Configure connection settings for TiDB Dedicated](/media/develop/dbeaver-connection-settings-dedicated.jpg) + +6. Click **Test Connection** to validate the connection to the TiDB Dedicated cluster. + + If the **Download driver files** dialog is displayed, click **Download** to get the driver files. + + ![Download driver files](/media/develop/dbeaver-download-driver.jpg) + + If the connection test is successful, the **Connection test** dialog is displayed as follows. Click **OK** to close it. + + ![Connection test result](/media/develop/dbeaver-connection-test.jpg) + +7. Click **Finish** to save the connection configuration. + +
+
+ +1. Launch DBeaver and click **New Database Connection** in the upper-left corner. In the **Connect to a database** dialog, select **TiDB** from the list, and then click **Next**. + + ![Select TiDB as the database in DBeaver](/media/develop/dbeaver-select-database.jpg) + +2. Configure the following connection parameters: + + - **Server Host**: The IP address or domain name of your TiDB Self-Hosted cluster. + - **Port**: The port number of your TiDB Self-Hosted cluster. + - **Username**: The username to use to connect to your TiDB Self-Hosted cluster. + - **Password**: The password of the username. + + An example is as follows: + + ![Configure connection settings for TiDB Self-Hosted](/media/develop/dbeaver-connection-settings-self-hosted.jpg) + +3. Click **Test Connection** to validate the connection to the TiDB Self-Hosted cluster. + + If the **Download driver files** dialog is displayed, click **Download** to get the driver files. + + ![Download driver files](/media/develop/dbeaver-download-driver.jpg) + + If the connection test is successful, the **Connection test** dialog is displayed as follows. Click **OK** to close it. + + ![Connection test result](/media/develop/dbeaver-connection-test.jpg) + +4. Click **Finish** to save the connection configuration. + +
+
+ +## Next steps + +- Learn more usage of DBeaver from [the documentation of DBeaver](https://github.com/dbeaver/dbeaver/wiki). +- Learn the best practices for TiDB application development with the chapters in the [Developer guide](/develop/dev-guide-overview.md), such as [Insert data](/develop/dev-guide-insert-data.md), [Update data](/develop/dev-guide-update-data.md), [Delete data](/develop/dev-guide-delete-data.md), [Single table reading](/develop/dev-guide-get-data-from-single-table.md), [Transactions](/develop/dev-guide-transaction-overview.md), and [SQL performance optimization](/develop/dev-guide-optimize-sql-overview.md). +- Learn through the professional [TiDB developer courses](https://www.pingcap.com/education/) and earn [TiDB certifications](https://www.pingcap.com/education/certification/) after passing the exam. + +## Need help? + +Ask questions on the [Discord](https://discord.gg/vYU9h56kAX), or [create a support ticket](https://support.pingcap.com/). diff --git a/develop/dev-guide-third-party-support.md b/develop/dev-guide-third-party-support.md index 149b6dbd19be4..263b6212a788e 100644 --- a/develop/dev-guide-third-party-support.md +++ b/develop/dev-guide-third-party-support.md @@ -179,4 +179,4 @@ If you encounter problems when connecting to TiDB using the tools listed in this | GUI | Latest tested version | Support level | Tutorial | | - | - | - | - | -| [DBeaver](https://dbeaver.io/) | 23.0.1 | Full | N/A | +| [DBeaver](https://dbeaver.io/) | 23.0.3 | Full | [Connect to TiDB with DBeaver](/develop/dev-guide-gui-dbeaver.md) | diff --git a/media/develop/dbeaver-connection-settings-dedicated.jpg b/media/develop/dbeaver-connection-settings-dedicated.jpg new file mode 100644 index 0000000000000..ee5eb32b9520a Binary files /dev/null and b/media/develop/dbeaver-connection-settings-dedicated.jpg differ diff --git a/media/develop/dbeaver-connection-settings-self-hosted.jpg b/media/develop/dbeaver-connection-settings-self-hosted.jpg new file mode 100644 index 0000000000000..cd929abd44399 Binary files /dev/null and b/media/develop/dbeaver-connection-settings-self-hosted.jpg differ diff --git a/media/develop/dbeaver-connection-settings-serverless.jpg b/media/develop/dbeaver-connection-settings-serverless.jpg new file mode 100644 index 0000000000000..7c544149d4df6 Binary files /dev/null and b/media/develop/dbeaver-connection-settings-serverless.jpg differ diff --git a/media/develop/dbeaver-connection-test.jpg b/media/develop/dbeaver-connection-test.jpg new file mode 100644 index 0000000000000..824a8a1fd438e Binary files /dev/null and b/media/develop/dbeaver-connection-test.jpg differ diff --git a/media/develop/dbeaver-download-driver.jpg b/media/develop/dbeaver-download-driver.jpg new file mode 100644 index 0000000000000..29762560b62c2 Binary files /dev/null and b/media/develop/dbeaver-download-driver.jpg differ diff --git a/media/develop/dbeaver-select-database.jpg b/media/develop/dbeaver-select-database.jpg new file mode 100644 index 0000000000000..1bff9fe7091d7 Binary files /dev/null and b/media/develop/dbeaver-select-database.jpg differ