TiUP Overview

Starting with TiDB 4.0, TiUP, as the package manager, makes it far easier to manage different cluster components in the TiDB ecosystem. Now you can run any component with only a single line of TiUP commands.

Install TiUP

You can install TiUP with a single command in both Darwin and Linux operating systems:

  1. curl --proto '=https' --tlsv1.2 -sSf https://tiup-mirrors.pingcap.com/install.sh | sh

This command installs TiUP in the $HOME/.tiup folder. The installed components and the data generated by their operation are also placed in this folder. This command also automatically adds $HOME/.tiup/bin to the PATH environment variable in the Shell .profile file, so you can use TiUP directly.

After installation, you can check the version of TiUP:

  1. tiup --version
  1. 1.14.0 tiup
  2. Go Version: go1.21.4
  3. Git Ref: v1.14.0
  4. GitHash: c3e9fc518aea0da66a37f82ee5a516171de9c372

Overview - 图1

Note

For TiUP versions starting from v1.11.3, the telemetry is disabled by default in newly deployed TiUP, and usage information is not collected and shared with PingCAP. For details about what is shared and how to disable the sharing, see Telemetry.

TiUP ecosystem introduction

TiUP is not only a package manager in the TiDB ecosystem. Its ultimate mission is to enable everyone to use TiDB ecosystem tools easier than ever before by building its own ecosystem. This requires introducing additional packages to enrich the TiUP ecosystem.

This series of TiUP documents introduce what these packages do and how you can use them.

In the TiUP ecosystem, you can get help information by adding --help to any command, such as the following command to get help information for TiUP itself:

  1. tiup --help
  1. TiUP is a command-line component management tool that can help to download and install
  2. TiDB platform components to the local system. You can run a specific version of a component via
  3. "tiup <component>[:version]". If no version number is specified, the latest version installed
  4. locally will be used. If the specified component does not have any version installed locally,
  5. the latest stable version will be downloaded from the repository.
  7. Usage:
  8.   tiup [flags] <command> [args...]
  9.   tiup [flags] <component> [args...]
  10.   tiup [command]
  12. Examples:
  13.   $ tiup playground                    # Quick start
  14.   $ tiup playground nightly            # Start a playground with the latest nightly version
  15.   $ tiup install <component>[:version] # Install a component of specific version
  16.   $ tiup update --all                  # Update all installed components to the latest version
  17.   $ tiup update --nightly              # Update all installed components to the nightly version
  18.   $ tiup update --self                 # Update the "tiup" to the latest version
  19.   $ tiup list                          # Fetch the latest supported components list
  20.   $ tiup status                        # Display all running/terminated instances
  21.   $ tiup clean <name>                  # Clean the data of running/terminated instance (Kill process if it's running)
  22.   $ tiup clean --all                   # Clean the data of all running/terminated instances
  24. Available Commands:
  25.   install     Install a specific version of a component
  26.   list        List the available TiDB components or versions
  27.   uninstall   Uninstall components or versions of a component
  28.   update      Update tiup components to the latest version
  29.   status      List the status of instantiated components
  30.   clean       Clean the data of instantiated components
  31.   mirror      Manage a repository mirror for TiUP components
  32.   telemetry   Controls things about telemetry
  33.   env         Show the list of system environment variable that related to TiUP
  34.   history     Display the historical execution record of TiUP, displays 100 lines by default
  35.   link        Link component binary to $TIUP_HOME/bin/
  36.   unlink      Unlink component binary to $TIUP_HOME/bin/
  37.   help        Help about any command
  38.   completion  Generate the autocompletion script for the specified shell
  40. Flags:
  41.       --binary <component>[:version]   Print binary path of a specific version of a component <component>[:version]
  42.                                        and the latest version installed will be selected if no version specified
  43.       --binpath string                 Specify the binary path of component instance
  44.   -h, --help                           help for tiup
  45.   -T, --tag string                     [Deprecated] Specify a tag for component instance
  46.   -v, --version                        Print the version of tiup
  48. Use "tiup [command] --help" for more information about a command.

The output is long but you can focus on only two parts:

  • Available commands
    • install: used to install a specific version of a component
    • list: used to view the list of available TiDB components or available versions of a component
    • uninstall: used to uninstall components or versions of a component
    • update: used to update the component version
    • status: used to view the running history of components
    • clean: used to clear the running log of components
    • mirror: used to clone a private mirror from the official mirror
    • telemetry: used to control the telemetry feature
    • env: used to show the list of system environment variables that related to TiUP
    • history: used to display the historical execution record of TiUP (100 lines by default)
    • link: used to link component binary to $TIUP_HOME/bin/
    • unlink: used to unlink component binary to $TIUP_HOME/bin/
    • help: used to print out help information
    • completion: used to generate the command line autocompletion script for the specified shell (including bash, zsh, fish, and powershell)
  • Available components
    • playground: used to start a TiDB cluster locally
    • client: client used to connect to TiUP Playground
    • cluster: used to deploy a TiDB cluster for production environments
    • bench: used to stress test the database

Overview - 图2

Note

  • The number of available components will continue to grow. To check the latest supported components, execute the tiup list command.
  • The list of available versions of components will also continue to grow. To check the latest supported component versions, execute the tiup list <component> command.

TiUP commands are implemented in TiUP’s internal code and used for package management operations, while TiUP components are independent component packages installed by TiUP commands.

For example, if you run the tiup list command, TiUP directly runs its own internal code; if you run the tiup playground command, TiUP first checks whether there is a local package named “playground”, and if not, TiUP downloads the package from the mirror, and then run it.