Skip to content

Commit

Permalink
tiup: refine description about tiup playground --tag (#19669) (#19684)
Browse files Browse the repository at this point in the history
  • Loading branch information
@ti-chi-bot
ti-chi-bot authored Dec 13, 2024
1 parent 2c02b87 commit 63421a7
Show file tree
Hide file tree
Showing 2 changed files with 25 additions and 61 deletions.
27 changes: 19 additions & 8 deletions quick-start-with-tidb.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,15 @@ As a distributed system, a basic TiDB test cluster usually consists of 2 TiDB in

3. Start the cluster in the current session:

> **Note:**
>
> - For the playground operated in the following way, after the deployment and testing are finished, TiUP will automatically clean up the cluster data. You will get a new cluster after re-running the command.
> - If you want to persist data on storage, then add the `--tag` flag when you start the cluster. For details, see [Specify a tag when starting the TiDB cluster to store the data](/tiup/tiup-playground.md#specify-a-tag-when-starting-the-tidb-cluster-to-store-the-data).
>
> ```shell
> tiup playground --tag ${tag_name}
> ```

- To start a TiDB cluster of the latest version with 1 TiDB instance, 1 TiKV instance, 1 PD instance, and 1 TiFlash instance, run the following command:

{{< copyable "shell-regular" >}}
Expand Down Expand Up @@ -99,9 +108,7 @@ As a distributed system, a basic TiDB test cluster usually consists of 2 TiDB in

> **Note:**
>
> + Since v5.2.0, TiDB supports running `tiup playground` on the machine that uses the Apple M1 chip.
> + For the playground operated in this way, after the test deployment is finished, TiUP will clean up the original cluster data. You will get a new cluster after re-running the command.
> + If you want the data to be persisted on storage, run `tiup --tag <your-tag> playground ...`. For details, refer to the [TiUP Reference](/tiup/tiup-reference.md#-t---tag) guide.
> Starting from v5.2.0, TiDB supports running `tiup playground` on the machine that uses the Apple M1 chip.

4. Start a new session to access TiDB:

Expand Down Expand Up @@ -188,6 +195,15 @@ As a distributed system, a basic TiDB test cluster usually consists of 2 TiDB in

3. Start the cluster in the current session:

> **Note:**
>
> - For the playground operated in the following way, after the deployment and testing are finished, TiUP will automatically clean up the cluster data. You will get a new cluster after re-running the command.
> - If you want to persist data on storage, then add the `--tag` flag when you start the cluster. For details, see [Specify a tag when starting the TiDB cluster to store the data](/tiup/tiup-playground.md#specify-a-tag-when-starting-the-tidb-cluster-to-store-the-data).
>
> ```shell
> tiup playground --tag ${tag_name}
> ```

- To start a TiDB cluster of the latest version with 1 TiDB instance, 1 TiKV instance, 1 PD instance, and 1 TiFlash instance, run the following command:

{{< copyable "shell-regular" >}}
Expand Down Expand Up @@ -217,11 +233,6 @@ As a distributed system, a basic TiDB test cluster usually consists of 2 TiDB in
To view the Grafana: http://127.0.0.1:3000
```

> **Note:**
>
> For the playground operated in this way, after the test deployment is finished, TiUP will clean up the original cluster data. You will get a new cluster after re-running the command.
> If you want the data to be persisted on storage, run `tiup --tag <your-tag> playground ...`. For details, refer to the [TiUP Reference](/tiup/tiup-reference.md#-t---tag) guide.

4. Start a new session to access TiDB:

+ Use the TiUP client to connect to TiDB.
Expand Down
59 changes: 6 additions & 53 deletions tiup/tiup-playground.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,57 +25,10 @@ This command actually performs the following operations:
- Because this command does not specify the number of each component, TiUP playground, by default, starts a smallest cluster that consists of one TiDB instance, one TiKV instance, one PD instance, and one TiFlash instance.
- After starting each TiDB component, TiUP playground reminds you that the cluster is successfully started and provides you some useful information, such as how to connect to the TiDB cluster through the MySQL client and how to access the [TiDB Dashboard](/dashboard/dashboard-intro.md).

The command-line flags of the playground component are described as follows:
You can use the following command to view the command-line flags of the playground component:

```bash
Flags:
--db int Specify the number of TiDB instances (default: 1)
--db.host host Specify the listening address of TiDB
--db.port int Specify the port of TiDB
--db.binpath string Specify the TiDB instance binary path (optional, for debugging)
--db.config string Specify the TiDB instance configuration file (optional, for debugging)
--db.timeout int Specify TiDB maximum wait time in seconds for starting. 0 means no limit
--drainer int Specify Drainer data of the cluster
--drainer.binpath string Specify the location of the Drainer binary files (optional, for debugging)
--drainer.config string Specify the Drainer configuration file
-h, --help Display help information for TiUP
--host string Specify the listening address of each component (default: `127.0.0.1`). Set it to `0.0.0.0` if provided for access of other machines
--kv int Specify the number of TiKV instances (default: 1)
--kv.binpath string Specify the TiKV instance binary path (optional, for debugging)
--kv.config string Specify the TiKV instance configuration file (optional, for debugging)
--mode string Specify the playground mode: 'tidb' (default) and 'tikv-slim'
--pd int Specify the number of PD instances (default: 1)
--pd.host host Specify the listening address of PD
--pd.binpath string Specify the PD instance binary path (optional, for debugging)
--pd.config string Specify the PD instance configuration file (optional, for debugging)
--pd.mode string Specify the PD working mode. The optional value is 'ms'. Specifying this flag means enabling PD microservice mode.
--pump int Specify the number of Pump instances. If the value is not `0`, TiDB Binlog is enabled.
--pump.binpath string Specify the location of the Pump binary files (optional, for debugging)
--pump.config string Specify the Pump configuration file (optional, for debugging)
--scheduling int Specify the number of Scheduling instances (default: 1)，which can be set only when `pd.mode` is 'ms'
--scheduling.host host Specify the listening address of the Scheduling instance
--scheduling.binpath string Specify the Scheduling instance binary path (optional, for debugging)
--scheduling.config string Specify the Scheduling instance configuration file (optional, for debugging)
-T, --tag string Specify a tag for playground
--ticdc int Specify the number of TiCDC instances (default: 0)
--ticdc.binpath string Specify the TiCDC instance binary path (optional, for debugging)
--ticdc.config string Specify the TiCDC instance configuration file (optional, for debugging)
--tiflash int Specify the number of TiFlash instances (default: 1)
--tiflash.binpath string Specify the TiFlash instance binary path (optional, for debugging)
--tiflash.config string Specify the TiFlash instance configuration file (optional, for debugging)
--tiflash.timeout int Specify TiFlash maximum wait time in seconds for starting. 0 means no limit
--tiproxy int TiProxy instance number
--tso int Specify the number of TSO instances (default: 1)，which can be set only when `pd.mode` is 'ms'
--tso.host host Specify the listening address of the TSO instance
--tso.binpath string Specify the TSO instance binary path (optional, for debugging)
--tso.config string Specify the TSO instance configuration file (optional, for debugging)
--tiproxy.binpath string TiProxy instance binary path
--tiproxy.config string TiProxy instance configuration file
--tiproxy.host host Playground TiProxy host. If not provided, TiProxy will still use host flag as its host
--tiproxy.port int Playground TiProxy port. If not provided, TiProxy will use 6000 as its port
--tiproxy.timeout int TiProxy max wait time in seconds for starting. 0 means no limit (default 60)
-v, --version Specify the version of playground
--without-monitor Disable the monitoring function of Prometheus and Grafana. If you do not add this flag, the monitoring function is enabled by default.
```shell
tiup playground --help
```

## Examples
Expand Down Expand Up @@ -126,12 +79,12 @@ By default, only one instance is started for each TiDB, TiKV, and PD component.
tiup playground --db 3 --pd 3 --kv 3
```

### Specify a tag when starting the TiDB cluster
### Specify a tag when starting the TiDB cluster to store the data

After you stop a TiDB cluster started using TiUP playground, all cluster data is cleaned up as well. To start a TiDB cluster using TiUP playground and ensure that the cluster data is not cleaned up automatically, you can specify a tag when starting the cluster. After specifying the tag, you can find the cluster data in the `~/.tiup/data` directory. Run the following command to specify a tag:

```shell
tiup playground --tag <tagname>
tiup playground --tag ${tag_name}
```

For a cluster started in this way, the data files are retained after the cluster is stopped. You can use this tag to start the cluster next time so that you can use the data kept since the cluster was stopped.
Expand Down Expand Up @@ -192,4 +145,4 @@ tiup playground v8.3.0 --pd.mode ms --pd 3 --tso 2 --scheduling 2
- `--pd.mode`: setting it to `ms` means enabling the microservice mode for PD.
- `--pd <num>`: specifies the number of APIs for PD microservices. It must be at least `1`.
- `--tso <num>`: specifies the number of instances to be deployed for the `tso` microservice.
- `--scheduling <num>`: specifies the number of instances to be deployed for the `scheduling` microservice.
- `--scheduling <num>`: specifies the number of instances to be deployed for the `scheduling` microservice.

0 comments on commit 63421a7

Please sign in to comment.