{"id":24809,"date":"2025-01-10T08:31:43","date_gmt":"2025-01-10T16:31:43","guid":{"rendered":"https:\/\/www.pingcap.com\/?p=24809"},"modified":"2026-01-09T08:44:14","modified_gmt":"2026-01-09T16:44:14","slug":"distributed-sql-tutorial-first-steps-setting-up-tidb-locally","status":"publish","type":"post","link":"https:\/\/www.pingcap.com\/ko\/blog\/distributed-sql-tutorial-first-steps-setting-up-tidb-locally\/","title":{"rendered":"Kickstart Your Distributed SQL Journey: Setting Up TiDB Locally with TiUP Playground"},"content":{"rendered":"\n

TiDB<\/a> is a powerful, open-source distributed SQL database<\/a> built for handling both transactional and analytical workloads. With its MySQL compatibility, horizontal scalability, and real-time HTAP capabilities, it\u2019s designed for modern, cloud-native architectures. In this distributed SQL tutorial, we’ll walk you through setting up a local TiDB cluster for development and testing in just a few simple steps. <\/p>\n\n\n\n

For a fully-managed experience with a free tier, you can also explore TiDB Cloud Serverless<\/a>. <\/p>\n\n\n\n

<\/span>Set Up Your Environment<\/span><\/h2>\n\n\n\n

This tutorial demonstrates examples using macOS. They will also work on Linux with trivial adaptations.<\/p>\n\n\n\n

Install TiUP<\/h3>\n\n\n\n

TiUP<\/a> is TiDB\u2019s package manager. Install it with the following command:<\/p>\n\n\n\n

curl --proto '=https' --tlsv1.2 -sSf https:\/\/tiup-mirrors.pingcap.com\/install.sh | sh<\/code><\/pre>\n\n\n\n
You will see an output like this:<\/p>\n\n\n\n
...\nSuccessfully set mirror to https:\/\/tiup-mirrors.pingcap.com\nDetected shell: zsh\nShell profile:  ~\/.zshrc\n~\/.zshrc has been modified to add tiup to PATH\nopen a new terminal or source ~\/.zshrc to use it\nInstalled path: ~\/.tiup\/bin\/tiup\n\n===============================================\nHave a try:     tiup playground\n===============================================<\/code><\/pre>\n\n\n\n
The script automatically modifies your PATH. To apply the changes, use the source command shown in the installation output or open a new terminal. In this example, run:<\/p>\n\n\n\n
source ~\/.zshrc<\/code><\/pre>\n\n\n\n
Start Your Database Playground<\/h3>\n\n\n\n
Start your local TiUP playground<\/a> environment with:<\/p>\n\n\n\n
tiup playground<\/code><\/pre>\n\n\n\n
When playground starts, you\u2019ll see:<\/p>\n\n\n\n
...\nTiDB Playground Cluster is started, enjoy!\n\nConnect TiDB:    mysql --host 127.0.0.1 --port 4000 -u root\nTiDB Dashboard:  http:\/\/127.0.0.1:2379\/dashboard\nGrafana:         http:\/\/127.0.0.1:3000\n<\/code><\/pre>\n\n\n\n
Keep this terminal open and proceed to the next steps in a new terminal.<\/p>\n\n\n\n
Connect to TiDB and Run Your First Queries<\/h3>\n\n\n\n
Let’s connect to the database server and run your first queries using TiUP’s built-in client. While this client only works with TiUP playground environments, it’s the quickest way to get started. Notice that TiDB Playground output shows you how to connect using the standard MySQL client. We\u2019ll cover that later. <\/p>\n\n\n\n
Run the built-in client with:<\/p>\n\n\n\n
tiup client<\/code><\/pre>\n\n\n\n
When prompted to choose an endpoint, simply press Enter<\/code> to connect. Since we started tiup playground<\/code> without extra arguments, there’s only one endpoint available.<\/p>\n\n\n\n
You will see a prompt like this:<\/p>\n\n\n\n
...\nStarting component client: ~\/.tiup\/components\/client\/v1.16.1\/tiup-client\nConnected with driver mysql (8.0.11-TiDB-v8.4.0)\nType \"help\" for help.\n\nmy:root@127.0.0.1:4000=> <\/code><\/pre>\n\n\n\n
Then, try these sample SQL commands:<\/p>\n\n\n\n
CREATE DATABASE hello;\nUSE hello;\n\nCREATE TABLE hello_tidb (\n    id INT,\n    name VARCHAR(50)\n);\n\nINSERT INTO hello_tidb VALUES (1, 'Hello World');\n\nSELECT * FROM hello_tidb;<\/code><\/pre>\n\n\n\n
The SQL commands above demonstrate basic interactions with the TiDB database. First, a new database hello<\/code> and a table hello_tidb<\/code> are created. Then, a row with id = 1<\/code> and name = 'Hello World'<\/code> is inserted. The SELECT * FROM hello_tidb<\/code> command retrieves and displays all rows in the table, resulting in the following output:<\/p>\n\n\n\n
 id |    name     \n----+-------------\n  1 | Hello World \n(1 row)<\/code><\/pre>\n\n\n\n
This confirms that the data has been successfully inserted and queried from the database. To exit the TiUP client, type \\q<\/code> or exit<\/code> and press Enter<\/code>. This will close the interactive session and return you to the terminal.<\/p>\n\n\n\n
<\/span>Understanding What Just Happened<\/span><\/h2>\n\n\n\n
You just started to use a fully functional distributed database<\/a> cluster with:<\/p>\n\n\n\n