Build a TiDB Serverless Cluster

This document walks you through the quickest way to get started with TiDB. You will create a TiDB Serverless cluster, connect to it, and run a sample application on it.

If you need to run TiDB on your local machine, see Starting TiDB Locally.

Step 1. Create a TiDB Serverless cluster

If you do not have a TiDB Cloud account, click here to sign up for an account.
Log in to your TiDB Cloud account.
The Clusters list page is displayed by default.
For new sign-up users, TiDB Cloud creates a default TiDB Serverless cluster Cluster0 for you automatically. You can either use this default cluster for the subsequent steps or create a new TiDB Serverless cluster on your own.
To create a new TiDB Serverless cluster on your own, take the following operations:
1. Click Create Cluster.
2. On the Create Cluster page, Serverless is selected by default. Select a target region of your cluster, update the default cluster name if necessary, and then click Create. Your TiDB Serverless cluster will be created in approximately 30 seconds.
On the cluster overview page, click Connect in the upper-right corner. A connection dialog box is displayed.
In the dialog, select your preferred connection method and operating system to get the corresponding connection string. This document uses MySQL client as an example.
Click Create password to generate a random password. The generated password will not show again, so save your password in a secure location. If you do not set a root password, you cannot connect to the cluster.

Note

For TiDB Serverless clusters, when you connect to your cluster, you must include the prefix for your cluster in the user name and wrap the name with quotation marks. For more information, see User name prefix.

Step 2. Connect to a cluster

If the MySQL client is not installed, select your operating system and follow the steps below to install it.

macOS
Linux

For macOS, install Homebrew if you do not have it, and then run the following command to install the MySQL client:

brew install mysql-client

The output is as follows:

mysql-client is keg-only, which means it was not symlinked into /opt/homebrew,
because it conflicts with mysql (which contains client libraries).

If you need to have mysql-client first in your PATH, run:
  echo 'export PATH="/opt/homebrew/opt/mysql-client/bin:$PATH"' >> ~/.zshrc

For compilers to find mysql-client you may need to set:
  export LDFLAGS="-L/opt/homebrew/opt/mysql-client/lib"
  export CPPFLAGS="-I/opt/homebrew/opt/mysql-client/include"

To add the MySQL client to your PATH, locate the following command in the above output (if your output is inconsistent with the above output in the document, use the corresponding command in your output instead) and run it:

echo 'export PATH="/opt/homebrew/opt/mysql-client/bin:$PATH"' >> ~/.zshrc

Then, declare the global environment variable by the source command and verify that the MySQL client is installed successfully:

source ~/.zshrc
mysql --version

An example of the expected output:

mysql  Ver 8.0.28 for macos12.0 on arm64 (Homebrew)

For Linux, the following takes CentOS 7 as an example:

yum install mysql

Then, verify that the MySQL client is installed successfully:

mysql --version

An example of the expected output:

mysql  Ver 15.1 Distrib 5.5.68-MariaDB, for Linux (x86_64) using readline 5.1

Run the connection string obtained in Step 1.

mysql --connect-timeout 15 -u '<prefix>.root' -h <host> -P 4000 -D test --ssl-mode=VERIFY_IDENTITY --ssl-ca=/etc/ssl/cert.pem -p

Note

When you connect to a TiDB Serverless cluster, you must use the TLS connection.
If you encounter problems when connecting to a TiDB Serverless cluster, you can read Secure Connections to TiDB Serverless Clusters for more information.

Fill in the password to sign in.

Step 3. Execute a SQL statement

Let's try to execute your first SQL statement on TiDB Cloud.

SELECT 'Hello TiDB Cloud!';

Expected output:

+-------------------+
| Hello TiDB Cloud! |
+-------------------+
| Hello TiDB Cloud! |
+-------------------+

If your actual output is similar to the expected output, congratulations, you have successfully execute a SQL statement on TiDB Cloud.

Need help?

Ask questions on TiDB Community, or create a support ticket.