<\/span>A quick overview of TiDB<\/span><\/h2>\nTiDB is a relational database that is compatible with the MySQL protocol and syntax and can easily scale beyond a single machine by dividing the data over multiple machines. This also makes it resilient to machine failures.<\/p>\n
If you have seen pictures of the TiDB architecture<\/a>, you know that it consists of many components, including the TiDB server, TiKV, a transaction, key-value database, and the Placement Driver (PD), which manages metadata. For a production setup you’ll need multiple instances of each component.<\/p>\n![\"tidb-distributed-architecture\"](\"https:\/\/static.pingcap.com\/files\/2021\/09\/04065541\/tidb-distributed-architecture.jpg\")
\nTiDB architecture<\/div>\nA scalable, highly available distributed system like TiDB runs multiple components on multiple hosts. For production setups this is not a problem as there are good tools to manage this: TiDB Operator for Kubernetes and TiUP Cluster<\/a>.<\/p>\nWhen you develop and test your work, you may have a cluster that has a similar setup as production. However, if you want to test against new versions of TiDB or if your development interferes with what other developers are doing, this may not work. Also, if you are traveling you may not have an internet connection or have an unreliable connection.<\/p>\n
Setting up a local copy of a distributed system can be a complex task because there are multiple components and there also might be OS settings to manage. Also, running multiple instances of a component can easily result in conflicts on TCP ports or filesystem paths.<\/p>\n
Another good use of a local cluster is to test certain operations before doing them in production. This includes learning basic tasks like upgrading your application and backing and restoring the database.<\/p>\n
So let’s look into some of the options for local development. Some of these can also be used for CI jobs where you need a database.<\/p>\n
<\/span>Install TiUP and start a TiDB Playground<\/span><\/h2>\nTiUP is the tool to use to manage TiDB installations, both in production and for local development. One of the things TiUP can do is to set up a playground, with this TiUP will download the components that you need and configure and start them so that you get a local environment. This works on macOS, Linux and on Windows with WSL.<\/p>\n
The playground gives you a TiDB installation to work with including the TiDB Dashboard and a set of Grafana dashboards.<\/p>\n
To install TiUP run:<\/p>\n
curl --proto '=https' --tlsv1.2 -sSf https:\/\/tiup-mirrors.pingcap.com\/install.sh | sh\n<\/code><\/pre>\nOnce TiUP is installed you can start a playground:<\/p>\n
tiup playground\n<\/code><\/pre>\nThese steps are available on https:\/\/tiup.io<\/a>.<\/p>\n![\"TiUP](\"https:\/\/www.pingcap.com\/core\/uploads\/2021\/09\/tiup-playground.jpg\")
\nTiUP Playground<\/div>\nIn the output of the tiup playground<\/code> command as shown above you can see the information about how to connect to the playground with a MySQL client and also the URLs for the TiDB Dashboard and Grafana.<\/p>\nAdditional tips for working with playgrounds:<\/p>\n
\n- You can specify the version you want to run with
tiup playground v4.0.14<\/code> for example.<\/li>\n- With
tiup -T myapp playground<\/code> you can put a nametag on the playground. This is useful when you use multiple playgrounds. This also allows you to more easily find the data directory of the playground to inspect the logs etc. For example with the “myapp” tag you can find the datadir on ~\/.tiup\/data\/myapp<\/code> with subdirectories for the various components. Setting a tag also lets you keep the data after stopping the playground.<\/li>\n- The
tiup playground<\/code> command has options to set the number of instances per component. This can be used to set the number of TiFlash instances to 0 in case you for example don’t intend to use the HTAP functionality.<\/li>\n- You can add
--monitor=false<\/code> if you don’t want to use monitoring tools like Grafana and Prometheus. This is useful if you want to save resources on your local machine.<\/li>\n<\/ul>\n<\/span>TiDE: a Visual Studio Code extension for TiDB<\/span><\/h2>\nIf you use Visual Studio Code, our TiDE<\/a> extension lets you work with TiUP Playground, TiUP clusters, and Kubernetes clusters right from your IDE.<\/p>\n![\"TiDE](\"https:\/\/www.pingcap.com\/core\/uploads\/2021\/09\/tide-showing-mysql-prompt-and-logging.jpg\")
\nTiDE showing a MySQL prompt and logging<\/div>\nThis extension gives you a Ti icon on the sidebar of VS Code. If you click this icon you get presented with options for starting a playground and an overview of any running playgrounds. TiDE also supports clusters deployed with TiUP, vagrant, and TiDB Operator for Kubernetes. Besides starting and stopping playgrounds you can also use this to inspect the logs, change the configuration of components and open a MySQL client session right in the terminal pane of VS Code.<\/p>\n
<\/span>Set up your containers with Docker Compose<\/span><\/h2>\nUse TiDB Docker Compose<\/a> to set up your containers. This is a useful tool if you already use Docker Compose to manage the containers of the application you are developing.<\/p>\nTo setup a set of containers with this tool run the following:<\/p>\n
git clone https:\/\/github.com\/pingcap\/tidb-docker-compose.git\ncd tidb-docker-compose && docker-compose pull \ndocker-compose up -d\n<\/code><\/pre>\nNow you can connect with a MySQL client:<\/p>\n
mysql -h 127.0.0.1 -P 4000 -u root --comments\n<\/code><\/pre>\n<\/span>Use TiDB Operator with minikube or kind<\/span><\/h2>\nIf you run TiDB on Kubernetes in production, a good option is to use minikube or kind for local development. This approach teaches you how to work with TiDB Operator. For detailed information on setting up TiDB Operator, see Getting Started with TiDB Operator on Kubernetes<\/a>.<\/p>\n<\/span>A simple option: run a single TiDB instance<\/span><\/h2>\n
\nA scalable, highly available distributed system like TiDB runs multiple components on multiple hosts. For production setups this is not a problem as there are good tools to manage this: TiDB Operator for Kubernetes and TiUP Cluster<\/a>.<\/p>\n When you develop and test your work, you may have a cluster that has a similar setup as production. However, if you want to test against new versions of TiDB or if your development interferes with what other developers are doing, this may not work. Also, if you are traveling you may not have an internet connection or have an unreliable connection.<\/p>\n Setting up a local copy of a distributed system can be a complex task because there are multiple components and there also might be OS settings to manage. Also, running multiple instances of a component can easily result in conflicts on TCP ports or filesystem paths.<\/p>\n Another good use of a local cluster is to test certain operations before doing them in production. This includes learning basic tasks like upgrading your application and backing and restoring the database.<\/p>\n So let’s look into some of the options for local development. Some of these can also be used for CI jobs where you need a database.<\/p>\n TiUP is the tool to use to manage TiDB installations, both in production and for local development. One of the things TiUP can do is to set up a playground, with this TiUP will download the components that you need and configure and start them so that you get a local environment. This works on macOS, Linux and on Windows with WSL.<\/p>\n The playground gives you a TiDB installation to work with including the TiDB Dashboard and a set of Grafana dashboards.<\/p>\n To install TiUP run:<\/p>\n Once TiUP is installed you can start a playground:<\/p>\n These steps are available on https:\/\/tiup.io<\/a>.<\/p>\n In the output of the Additional tips for working with playgrounds:<\/p>\n If you use Visual Studio Code, our TiDE<\/a> extension lets you work with TiUP Playground, TiUP clusters, and Kubernetes clusters right from your IDE.<\/p>\n This extension gives you a Ti icon on the sidebar of VS Code. If you click this icon you get presented with options for starting a playground and an overview of any running playgrounds. TiDE also supports clusters deployed with TiUP, vagrant, and TiDB Operator for Kubernetes. Besides starting and stopping playgrounds you can also use this to inspect the logs, change the configuration of components and open a MySQL client session right in the terminal pane of VS Code.<\/p>\n Use TiDB Docker Compose<\/a> to set up your containers. This is a useful tool if you already use Docker Compose to manage the containers of the application you are developing.<\/p>\n To setup a set of containers with this tool run the following:<\/p>\n Now you can connect with a MySQL client:<\/p>\n If you run TiDB on Kubernetes in production, a good option is to use minikube or kind for local development. This approach teaches you how to work with TiDB Operator. For detailed information on setting up TiDB Operator, see Getting Started with TiDB Operator on Kubernetes<\/a>.<\/p>\n<\/span>Install TiUP and start a TiDB Playground<\/span><\/h2>\n
curl --proto '=https' --tlsv1.2 -sSf https:\/\/tiup-mirrors.pingcap.com\/install.sh | sh\n<\/code><\/pre>\ntiup playground\n<\/code><\/pre>\n\ntiup playground<\/code> command as shown above you can see the information about how to connect to the playground with a MySQL client and also the URLs for the TiDB Dashboard and Grafana.<\/p>\n\n
tiup playground v4.0.14<\/code> for example.<\/li>\ntiup -T myapp playground<\/code> you can put a nametag on the playground. This is useful when you use multiple playgrounds. This also allows you to more easily find the data directory of the playground to inspect the logs etc. For example with the “myapp” tag you can find the datadir on ~\/.tiup\/data\/myapp<\/code> with subdirectories for the various components. Setting a tag also lets you keep the data after stopping the playground.<\/li>\ntiup playground<\/code> command has options to set the number of instances per component. This can be used to set the number of TiFlash instances to 0 in case you for example don’t intend to use the HTAP functionality.<\/li>\n--monitor=false<\/code> if you don’t want to use monitoring tools like Grafana and Prometheus. This is useful if you want to save resources on your local machine.<\/li>\n<\/ul>\n<\/span>TiDE: a Visual Studio Code extension for TiDB<\/span><\/h2>\n
\n<\/span>Set up your containers with Docker Compose<\/span><\/h2>\n
git clone https:\/\/github.com\/pingcap\/tidb-docker-compose.git\ncd tidb-docker-compose && docker-compose pull \ndocker-compose up -d\n<\/code><\/pre>\nmysql -h 127.0.0.1 -P 4000 -u root --comments\n<\/code><\/pre>\n<\/span>Use TiDB Operator with minikube or kind<\/span><\/h2>\n
<\/span>A simple option: run a single TiDB instance<\/span><\/h2>\n