## Module 1: Connecting to TiDB Cloud Cluster {% if TIDB_ENVIRONMENT == 'TiDB Cloud Starter' %} ### Step 1. Log into the remote Linux + Click here - [Terminal 1](ssh://monitor1-ssh#1) to open a new terminal connected to the virtual machine assigned for your hands-on lab. {% elif TIDB_ENVIRONMENT == 'TiDB Cloud Essential' %} ### Step 1. Create a new TiDB Cloud Essential cluster > [!TIP] > If you already have a TiDB Cloud Essential cluster running under project `tidblabs-project` for hands-on lab or evaluation purpose, you can skip this step. - Go to [Projects on TiDB Cloud console](https://tidbcloud.com/org-settings/projects/). - Click `Create New Project`. Name the new project as `tidblabs-project`, and click `Confirm`. Please make sure you have your credit card linked to your TiDB Cloud account or you have applied for enough TiDB Cloud Credits. Otherwise, you cannot create a new project. ![create-tidblabs-project.jpg 85%](https://lab-static.pingcap.com/images/2025/11/12/a0d8440ea67b16e4d3b4d22fa522fb1f1014abe4.jpg) - Click the project name to enter the project page. ![click-tidblabs-project.png 85%](https://lab-static.pingcap.com/images/2025/11/13/385a38090615446a95ad7aae6977fb20f804bd50.png) - In the `Clusters` page, click `Create Cluster`. This button appears either in the middle of the page or on the upper right corner. Choose `Essential`, Choose `${LAB:CLOUD_PROVIDER}` as the Cloud Provider and `${LAB:REGION_NAME} (${LAB:REGION_CODE})` as the Region. ![choose-essential-cp-region.jpg 85%](https://lab-static.pingcap.com/images/2025/11/13/7c9f14094559f38023dbde0a45e144365bb8bd72.jpg) - Name the new cluster `tidblabs`, and keep the default settings for Capacity, Dual-layer Data Encryption, and High Availability. Click `Create` on the right. The cluster will automatically scale between RCU 2K and RCU 4K depending on workload requirements. For more information about RCU, refer to the [documentation](https://www.pingcap.com/tidb-cloud-essential-pricing-details/). ![create-tidblabs-essential-cluster.png 85%](https://lab-static.pingcap.com/images/2025/11/13/62e0c238d48c9a6b5298e8d4e11636bcfcb67a65.png) - Wait a few seconds until the cluster becomes active. ![tidblabs-essential-active.jpg 85%](https://lab-static.pingcap.com/images/2025/11/13/5358b8f697ad135498f08d69d7c58d1018c552b9.jpg) - Click the `Connect` button on the upper right corner. ![click-connect-for-essential.jpg 85%](https://lab-static.pingcap.com/images/2025/11/13/d40772019b0ae45bda91931ad0259f09f551f8d3.jpg) - On the `Connect` panel, make sure the Connect Type is `Public`, choose `Debian/Ubuntu/Arch` under Operating System, and then click `Generate Password`. ![tidblabs-essential-password-connect-generate.jpg 85%](https://lab-static.pingcap.com/images/2025/11/13/999bc20961199e2a4322451d19a15d930d931050.jpg) - Click here - [Terminal 1](ssh://monitor1-ssh#1) to open a new terminal connected to the Ubuntu virtual machine assigned for your hands-on lab. - On the `Connect` panel, copy the four values (HOST, PORT, USERNAME, and PASSWORD), manually replace the corresponding placeholders (enclosed by `<` and `>`) in the commands below, and run them in [Terminal 1](ssh://monitor1-ssh#1) to set these as environment variables. ![tidblabs-essential-four-info.jpg 85%](https://lab-static.pingcap.com/images/2025/11/13/a08ea9cdbbaa9de290fe5a413da7db71c4e20ac5.jpg) ```bash export SERVERLESS_CLUSTER_HOST= export SERVERLESS_CLUSTER_PORT= export SERVERLESS_CLUSTER_USERNAME='' export SERVERLESS_CLUSTER_PASSWORD='' ``` {% endif %} ### Step 2. Check the connectivity to the TiDB Cloud cluster {% if TIDB_ENVIRONMENT == 'TiDB Cloud Starter' %} + The following operations are performed on a remote Virtual Machine. Connect to TiDB Cloud Starter with the following three patterns. (When you want to exit the MySQL client, use `EXIT`.) + A. Connection (with SSL): Connect using the following command. ```bash mysql \ --comments -u '${LAB:SERVERLESS_CLUSTER_USERNAME}' -p'${LAB:SERVERLESS_CLUSTER_PASSWORD}' \ -h ${LAB:SERVERLESS_CLUSTER_HOST} -P ${LAB:SERVERLESS_CLUSTER_PORT} \ --ssl-mode=VERIFY_IDENTITY --ssl-ca=/etc/ssl/certs/ca-certificates.crt ``` ```output mysql> ``` ```sql EXIT; ``` + B. Connection (with SSL): If you don't specify the `--ssl-mode` option, the default mode is `PREFERRED`, which means the MySQL client will first attempt to establish an SSL connection and fall back to an unencrypted connection if SSL fails. ```bash mysql \ --comments -u '${LAB:SERVERLESS_CLUSTER_USERNAME}' -p'${LAB:SERVERLESS_CLUSTER_PASSWORD}' \ -h ${LAB:SERVERLESS_CLUSTER_HOST} -P ${LAB:SERVERLESS_CLUSTER_PORT} ``` ```output mysql> ``` ```sql EXIT; ``` + C. Connection (without SSL): Change to `--ssl-mode=DISABLED`. A connection error will occur. ```bash mysql \ --comments -u '${LAB:SERVERLESS_CLUSTER_USERNAME}' -p'${LAB:SERVERLESS_CLUSTER_PASSWORD}' \ -h ${LAB:SERVERLESS_CLUSTER_HOST} -P ${LAB:SERVERLESS_CLUSTER_PORT} \ --ssl-mode=DISABLED ``` ```output mysql: [Warning] Using a password on the command line interface can be insecure. ERROR 1105 (HY000): Connections using insecure transport are prohibited. See https://docs.tidb.io/tidbcloud/secure-connections-to-serverless-tier-clusters ``` {% elif TIDB_ENVIRONMENT == 'TiDB Cloud Essential' %} + The following operations are performed on a remote Virtual Machine. Connect to TiDB Cloud Essential with the following three patterns. (When you want to exit the MySQL client, use `EXIT`.) + A. Connection (with SSL): Connect using the following command. ```bash mysql \ --comments -u ${SERVERLESS_CLUSTER_USERNAME} -p${SERVERLESS_CLUSTER_PASSWORD} \ -h ${SERVERLESS_CLUSTER_HOST} -P ${SERVERLESS_CLUSTER_PORT} \ --ssl-mode=VERIFY_IDENTITY --ssl-ca=/etc/ssl/certs/ca-certificates.crt ``` ```output mysql> ``` ```sql EXIT; ``` + B. Connection (with SSL): If you don't specify the `--ssl-mode` option, the default mode is `PREFERRED`, which means the MySQL client will first attempt to establish an SSL connection and fall back to an unencrypted connection if SSL fails. ```bash mysql \ --comments -u ${SERVERLESS_CLUSTER_USERNAME} -p${SERVERLESS_CLUSTER_PASSWORD} \ -h ${SERVERLESS_CLUSTER_HOST} -P ${SERVERLESS_CLUSTER_PORT} ``` ```output mysql> ``` ```sql EXIT; ``` + C. Connection (without SSL): Change to `--ssl-mode=DISABLED`. A connection error will occur. ```bash mysql \ --comments -u ${SERVERLESS_CLUSTER_USERNAME} -p${SERVERLESS_CLUSTER_PASSWORD} \ -h ${SERVERLESS_CLUSTER_HOST} -P ${SERVERLESS_CLUSTER_PORT} \ --ssl-mode=DISABLED ``` ```output mysql: [Warning] Using a password on the command line interface can be insecure. ERROR 1105 (HY000): Connections using insecure transport are prohibited. See https://docs.tidb.io/tidbcloud/secure-connections-to-serverless-tier-clusters ``` {% endif %} ### Step 3. Basic database operations {% if TIDB_ENVIRONMENT == 'TiDB Cloud Starter' %} + Connect to TiDB. ```bash mysql \ --comments -u '${LAB:SERVERLESS_CLUSTER_USERNAME}' -p'${LAB:SERVERLESS_CLUSTER_PASSWORD}' \ -h ${LAB:SERVERLESS_CLUSTER_HOST} -P ${LAB:SERVERLESS_CLUSTER_PORT} \ --ssl-mode=VERIFY_IDENTITY --ssl-ca=/etc/ssl/certs/ca-certificates.crt ``` ```output mysql> ``` + Create a new database. ```sql DROP DATABASE IF EXISTS ${LAB:SERVERLESS_CLUSTER_DATABASE_NAME}; CREATE DATABASE ${LAB:SERVERLESS_CLUSTER_DATABASE_NAME}; SHOW DATABASES\G ``` ```output *************************** 1. row *************************** Database: INFORMATION_SCHEMA *************************** 2. row *************************** Database: PERFORMANCE_SCHEMA *************************** 3. row *************************** Database: ${LAB:SERVERLESS_CLUSTER_DATABASE_NAME} *************************** 4. row *************************** Database: mysql *************************** 5. row *************************** Database: test 5 rows in set (0.02 sec) ``` + Create a new table. ```sql USE ${LAB:SERVERLESS_CLUSTER_DATABASE_NAME}; CREATE TABLE color (id INT AUTO_INCREMENT, name TEXT, Point INT, PRIMARY KEY (id)); INSERT INTO color (name, Point) VALUES ('red', 1); INSERT INTO color (name, Point) VALUES ('orange', 1); INSERT INTO color (name, Point) VALUES ('yellow', 2); SELECT * FROM color; ``` ```output Database changed Query OK, 0 rows affected (0.14 sec) Query OK, 1 row affected (0.04 sec) Query OK, 1 row affected (0.01 sec) Query OK, 1 row affected (0.01 sec) +----+--------+-------+ | id | name | Point | +----+--------+-------+ | 1 | red | 1 | | 2 | orange | 1 | | 3 | yellow | 2 | +----+--------+-------+ 3 rows in set (0.01 sec) ``` {% elif TIDB_ENVIRONMENT == 'TiDB Cloud Essential' %} + Connect to TiDB. ```bash mysql \ --comments -u ${SERVERLESS_CLUSTER_USERNAME} -p${SERVERLESS_CLUSTER_PASSWORD} \ -h ${SERVERLESS_CLUSTER_HOST} -P ${SERVERLESS_CLUSTER_PORT} \ --ssl-mode=VERIFY_IDENTITY --ssl-ca=/etc/ssl/certs/ca-certificates.crt ``` ```output mysql> ``` + Create a new database. ```sql DROP DATABASE IF EXISTS lab_demo_${LAB:LAB_INSTANCE_ID}; CREATE DATABASE lab_demo_${LAB:LAB_INSTANCE_ID}; SHOW DATABASES\G ``` ```output *************************** 1. row *************************** Database: INFORMATION_SCHEMA *************************** 2. row *************************** Database: PERFORMANCE_SCHEMA *************************** 3. row *************************** Database: lab_demo_${LAB:LAB_INSTANCE_ID} *************************** 4. row *************************** Database: mysql *************************** 5. row *************************** Database: test 5 rows in set (0.02 sec) ``` + Create a new table. ```sql USE lab_demo_${LAB:LAB_INSTANCE_ID}; CREATE TABLE color (id INT AUTO_INCREMENT, name TEXT, Point INT, PRIMARY KEY (id)); INSERT INTO color (name, Point) VALUES ('red', 1); INSERT INTO color (name, Point) VALUES ('orange', 1); INSERT INTO color (name, Point) VALUES ('yellow', 2); SELECT * FROM color; ``` ```output Database changed Query OK, 0 rows affected (0.14 sec) Query OK, 1 row affected (0.04 sec) Query OK, 1 row affected (0.01 sec) Query OK, 1 row affected (0.01 sec) +----+--------+-------+ | id | name | Point | +----+--------+-------+ | 1 | red | 1 | | 2 | orange | 1 | | 3 | yellow | 2 | +----+--------+-------+ 3 rows in set (0.01 sec) ``` {% endif %} ### Step 4. Check MySQL compatibility + TiDB is not 100% compatible with MySQL. Here we check the MySQL 8.x features such as Window Functions and unsupported Stored Procedures. You can check compatibility from the following URL: [https://docs.pingcap.com/tidb/stable/mysql-compatibility/](https://docs.pingcap.com/tidb/stable/mysql-compatibility/). + Check that the default character set and collation are different. ```sql SHOW CREATE TABLE color\G ``` ```output *************************** 1. row *************************** Table: color Create Table: CREATE TABLE `color` ( `id` int(11) NOT NULL AUTO_INCREMENT, `name` text DEFAULT NULL, `Point` int(11) DEFAULT NULL, PRIMARY KEY (`id`) /*T![clustered_index] CLUSTERED */ ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin AUTO_INCREMENT=30001 1 row in set (0.00 sec) ``` + Window function example. ```sql SELECT id, name, Point, RANK() OVER w as 'rank' FROM color WINDOW w AS (ORDER BY Point); ``` ```output +----+--------+-------+------+ | id | name | Point | rank | +----+--------+-------+------+ | 1 | red | 1 | 1 | | 2 | orange | 1 | 1 | | 3 | yellow | 2 | 3 | +----+--------+-------+------+ 3 rows in set (0.01 sec) ``` + Stored Procedure. This will fail as it is not supported. ```sql delimiter // CREATE PROCEDURE sample() BEGIN SELECT * FROM color; END // delimiter ; ``` ```output ERROR 8108 (HY000): Unsupported type *ast.ProcedureInfo ``` - Keep the database connection, and proceed to the next module.