diff --git a/TOC-develop.md b/TOC-develop.md index 77dab88ec51e5..6b46fb9363843 100644 --- a/TOC-develop.md +++ b/TOC-develop.md @@ -20,6 +20,7 @@ - [VS Code](/develop/dev-guide-gui-vscode-sqltools.md) - [MySQL Workbench](/develop/dev-guide-gui-mysql-workbench.md) - [Navicat](/develop/dev-guide-gui-navicat.md) + - [LibreDB Studio](/develop/dev-guide-gui-libredb-studio.md) - Drivers & ORMs - [Choose a Driver or ORM](/develop/dev-guide-choose-driver-or-orm.md) - Java diff --git a/develop/dev-guide-gui-libredb-studio.md b/develop/dev-guide-gui-libredb-studio.md new file mode 100644 index 0000000000000..7f7bfbedd086c --- /dev/null +++ b/develop/dev-guide-gui-libredb-studio.md @@ -0,0 +1,84 @@ +--- +title: Connect to TiDB with LibreDB Studio +summary: Learn how to connect to TiDB using LibreDB Studio. +aliases: ['/tidb/stable/dev-guide-gui-libredb-studio/','/tidb/dev/dev-guide-gui-libredb-studio/','/tidbcloud/dev-guide-gui-libredb-studio/'] +--- + +# Connect to TiDB with LibreDB Studio + +TiDB is a MySQL-compatible database, and [LibreDB Studio](https://libredb.org) is an open-source, web-based SQL IDE that connects to PostgreSQL, MySQL-compatible databases, and a number of other engines from a single workspace. It ships as a Docker image and as an `npx` package, so it runs next to the database instead of requiring a desktop install. + +In this tutorial, you can learn how to connect to TiDB using LibreDB Studio. + +> **Note:** +> +> This tutorial covers TiDB Self-Managed only. It was not tested against TiDB Cloud, so it does not include TiDB Cloud connection steps. +> +> It was also tested against a cluster that does not enforce TLS. The connection dialog has an **SSL / TLS** section with `SSL Mode` options (including CA certificate and client certificate/key fields) for clusters that enforce `require_secure_transport`, `REQUIRE SSL`, or `REQUIRE X509`, but that path was not tested here, so this tutorial leaves `SSL Mode` at its default. + +## Prerequisites + +To complete this tutorial, you need: + +- LibreDB Studio, started with `npx @libredb/studio@0.13.4` (requires Node.js 24 or later) or the Docker image (see the [Quick Start](https://github.com/libredb/libredb-studio#quick-start) instructions). +- A TiDB Self-Managed cluster, and a TiDB user with `CREATE`, `INSERT`, and `SELECT` privileges on the database used in this tutorial. + +**If you don't have a TiDB cluster, you can deploy one as follows:** + +- [Deploy a local test TiDB Self-Managed cluster](/quick-start-with-tidb.md#deploy-a-local-test-cluster) or [Deploy a production TiDB Self-Managed cluster](/production-deployment-using-tiup.md). + +## Connect to TiDB + +1. Open LibreDB Studio in your browser and sign in. + +2. Click the **+** button next to the LibreDB Studio logo in the top-left corner. This opens the **New Connection** dialog. + + ![LibreDB Studio: the New Connection dialog](/media/develop/libredb-studio-new-connection.png) + +3. Select **MySQL** as the database type. TiDB does not have its own entry in this list because LibreDB Studio talks to it over the same driver it uses for MySQL; once MySQL is selected, a note under the type grid lists the wire-compatible engines that driver has been verified against, including the exact TiDB build LibreDB Studio was tested with. + + ![LibreDB Studio: the MySQL driver's compatibility note lists TiDB](/media/develop/libredb-studio-mysql-compatibility-note.png) + +4. Configure the following connection parameters: + + - **Connection Name**: give this connection a meaningful name, such as `TiDB`. + - **Host & Instance**: enter the host and port of your TiDB cluster. The default TiDB port is `4000`. + - **Username**: enter the username to connect to your TiDB cluster. + - **Password**: enter the password for that username, if one is set. + - **Database Name**: enter the name of an existing database on the cluster, such as `test`. + + The following figure shows an example of the connection parameters: + + ![LibreDB Studio: connection settings for a TiDB Self-Managed cluster](/media/develop/libredb-studio-connection-settings.png) + +5. Click **Test Connection** to validate the connection to your TiDB cluster. + +6. Click **Establish Connection** to save the connection and open it. + +7. In the query editor, run a statement to confirm the connection works end to end, for example: + + ```sql + CREATE TABLE demo_users (id INT PRIMARY KEY, name VARCHAR(50)); + INSERT INTO demo_users VALUES (1, 'Ada'), (2, 'Grace'); + SELECT * FROM demo_users; + ``` + + Click **RUN** (or press **Ctrl+Enter**) to execute it. + + ![LibreDB Studio: connected to TiDB and running a query](/media/develop/libredb-studio-connected-query.png) + +> **Note:** +> +> Right after you create a table and insert rows, the row count and size shown next to the table in the sidebar can briefly read `0` until TiDB's background statistics collection catches up. This is TiDB's own behavior, not something LibreDB Studio gets wrong, and the numbers correct themselves shortly afterward with no action needed. + +## Next steps + +- Learn more usage of LibreDB Studio from its [documentation](https://github.com/libredb/libredb-studio/tree/main/docs). +- Learn the best practices for TiDB application development with the chapters in the [Developer guide](https://docs.pingcap.com/developer/), 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 the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs). +- [Submit a support ticket for TiDB Cloud](https://tidb.support.pingcap.com/servicedesk/customer/portals) +- [Submit a support ticket for TiDB Self-Managed](/support.md) diff --git a/develop/dev-guide-third-party-support.md b/develop/dev-guide-third-party-support.md index 9278fe02374ec..a4d0810e675cf 100644 --- a/develop/dev-guide-third-party-support.md +++ b/develop/dev-guide-third-party-support.md @@ -60,6 +60,7 @@ If you encounter problems when connecting to TiDB using the tools listed in this | [DBeaver](https://dbeaver.io/) | 23.0.3 | Full | [Connect to TiDB with DBeaver](/develop/dev-guide-gui-dbeaver.md) | | [Visual Studio Code](https://code.visualstudio.com/) | 1.72.0 | Full | [Connect to TiDB with Visual Studio Code](/develop/dev-guide-gui-vscode-sqltools.md) | | [Navicat](https://www.navicat.com) | 17.1.6 | Full | [Connect to TiDB with Navicat](/develop/dev-guide-gui-navicat.md) | +| [LibreDB Studio](https://libredb.org) | 0.13.4 | Full | [Connect to TiDB with LibreDB Studio](/develop/dev-guide-gui-libredb-studio.md) | ## Need help? diff --git a/media/develop/libredb-studio-connected-query.png b/media/develop/libredb-studio-connected-query.png new file mode 100644 index 0000000000000..5037b82e70c2d Binary files /dev/null and b/media/develop/libredb-studio-connected-query.png differ diff --git a/media/develop/libredb-studio-connection-settings.png b/media/develop/libredb-studio-connection-settings.png new file mode 100644 index 0000000000000..289a62199eb3d Binary files /dev/null and b/media/develop/libredb-studio-connection-settings.png differ diff --git a/media/develop/libredb-studio-mysql-compatibility-note.png b/media/develop/libredb-studio-mysql-compatibility-note.png new file mode 100644 index 0000000000000..166de5ddc8f87 Binary files /dev/null and b/media/develop/libredb-studio-mysql-compatibility-note.png differ diff --git a/media/develop/libredb-studio-new-connection.png b/media/develop/libredb-studio-new-connection.png new file mode 100644 index 0000000000000..4affe3eb4c6cd Binary files /dev/null and b/media/develop/libredb-studio-new-connection.png differ