Debug TiDB Cloud Documentation: Connect to TiDB Serverless via Public Endpoint

[qiancai]

This issue is a sub-issue of Debug TiDB Cloud Documentation: Summary Issue · Issue #15480 · pingcap/docs. The purpose of this sub-issue is to verify and debug the Connect to TiDB Serverless via Public Endpoint document.

You can follow the instructions provided in #15480 to verify and debug the instructions in this document.

1. After finishing your verification, please add your verification result to this sub-issue as a comment. The result can be the issues you encounter, the mistakes you find, or any other findings. If everything looks fine, you can also add it as a comment.
2. For any issues you found during the verification, welcome to create a pull request (PR) to fix them directly. In the pull request, please indicate which issue this PR resolves in the PR description (for example, fix #15741). To learn how to create a pull request, see TiDB Documentation Contributing Guide.

Note: Currently, the TiDB Cloud documentation is in English only and it is stored in the release-7.5 branch of pingcap/docs for reusing the SQL documentation of TiDB. Hence, to create a pull request for TiDB Cloud documentation, make sure that your PR is based on the release-7.5 branch.

Your contribution to testing and verifying the documentation is highly appreciated!

[minaelee]

/assign

[minaelee]

First two sentences:

This document describes how to connect to your TiDB Serverless cluster via public endpoint. With the public endpoint, you can connect to your TiDB Serverless cluster via a SQL client from your laptop.

Redundant phrasing & assumes the user will be on a laptop. Use instead:

This document describes how to connect to your TiDB Serverless cluster via a public endpoint, using a SQL client from your computer.

[minaelee]

This document ends rather abruptly. This is the final sentence:

Connect to your cluster with the connection string.

This could use more information and/or links at the bottom for further details on how to connect.

I see that in the UI (that is, in the Connect dialog for a cluster), there are accompanying links below where the code snippet/connection string for each Connect With type is generated. Many of these link to a tutorial page on how to connect for each type, e.g. Connect to TiDB with node/mysql2.

I would normally say that the way to resolve the 'could use more information' issue would be to provide the user with a list of these tutorials. However, from what I can tell, many of the linked documents are outdated.

This is how: They say that the user should choose to Connect With the option of General, and they do not use the code/connection strings provided by the Connect dialog.

Example. Choose Nodejs(mysql2) in the Connection With in the Connect dialog for a cluster. See that a connection string is generated that looks similar to this:

mysql://4TkAZe59LRrDmGD.root:<PASSWORD>@gateway01.us-west-2.prod.aws.tidbcloud.com:4000/test?ssl={"rejectUnauthorized":true}

Below it, you should see a link to a tutorial, Connect to TiDB with node/mysql2. Follow it and notice two things:

1. The instructions tell you to select General for Connection Type even though you got to this page by selecting Nodejs(mysql2).
2. The connection string that was generated is not used in the instructions given on this page.

It seems like at some point, the Connect With option got an upgrade to show vendor-specific connection strings for many of the SQL clients listed, but their tutorials were not updated.

Someone might want to double check me on this, but I went through the Connect With options and the above issue exists for:

• Connect to TiDB with node/mysql2
• Connect to TiDB with SQLAlchemy
• Connect to TiDB with JDBC
• Connect to TiDB with mysqlclient
• Connect to TiDB with pymysql
• Connect to TiDB with MySQL Connector/Python
• Connect to TiDB with Django
• Connect to TiDB with Go-MySQL-Driver

[ran-huang]

@minaelee Thank you, Minae! I appreciate the time you took to provide such comprehensive feedback on our documentation. You have keen eyes for details! 👍 The inconsistencies between our UI and tutorials is true -- the tutorials were written before the console UI offered multiple ways of connection.

In response, we're kicking off an immediate review and update process for all our connection tutorials, with a special focus on those you've highlighted. The update will take longer than expected because, in addition to updating the documentation, we may also update some sample code. Your contributions are making a real difference in helping us enhance our documentation, and we're truly grateful! ❤️ 🚀

[minaelee]

I'm glad to hear my feedback has been helpful, @ran-huang! Best of luck with the tutorial updates.