TiDB 数据库快速上手指南

本指南介绍如何快速上手体验 TiDB 数据库。对于非生产环境，你可以选择以下任意一种方式部署 TiDB 数据库：

• 部署本地测试集群（支持 macOS 和 Linux）
• 在单机上模拟部署生产环境集群（支持 Linux）

要快速了解 TiUP 的基本功能、使用 TiUP 快速搭建 TiDB 集群的方法与连接 TiDB 集群并执行 SQL 的方法，建议先观看下面的培训视频（时长 15 分钟）。注意本视频只作为学习参考，如需了解 TiUP 的具体使用方法和 TiDB 快速上手具体操作步骤，请以文档内容为准。

部署本地测试集群

• 适用场景：利用本地 macOS 或者单机 Linux 环境快速部署 TiDB 测试集群，体验 TiDB 集群的基本架构，以及 TiDB、TiKV、PD、监控等基础组件的运行。

• macOS
• Linux

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

安装完成后会提示如下信息：

```log
Successfully set mirror to https://tiup-mirrors.pingcap.com
Detected shell: zsh
Shell profile:  /Users/user/.zshrc
/Users/user/.zshrc has been modified to add tiup to PATH
open a new terminal or source /Users/user/.zshrc to use it
Installed path: /Users/user/.tiup/bin/tiup
===============================================
Have a try:     tiup playground
===============================================
```

```shell
source ${your_shell_profile}
```

    ```shell
    tiup playground
    ```

- 也可以指定 TiDB 版本以及各组件实例个数，命令类似于：


    ```shell
    tiup playground v7.4.0 --db 2 --pd 3 --kv 3
    ```

    上述命令会在本地下载并启动某个版本的集群（例如 v7.4.0）。最新版本可以通过执行 `tiup list tidb` 来查看。运行结果将显示集群的访问方式：

    ```log
    CLUSTER START SUCCESSFULLY, Enjoy it ^-^
    To connect TiDB: mysql --comments --host 127.0.0.1 --port 4001 -u root -p (no password)
    To connect TiDB: mysql --comments --host 127.0.0.1 --port 4000 -u root -p (no password)
    To view the dashboard: http://127.0.0.1:2379/dashboard
    PD client endpoints: [127.0.0.1:2379 127.0.0.1:2382 127.0.0.1:2384]
    To view the Prometheus: http://127.0.0.1:9090
    To view the Grafana: http://127.0.0.1:3000
    ```

    > **注意：**
    >
    > + 支持 v5.2.0 及以上版本的 TiDB 在 Apple M1 芯片的机器上运行 `tiup playground`。
    > + 以这种方式执行的 playground，在结束部署测试后 TiUP 会清理掉原集群数据，重新执行该命令后会得到一个全新的集群。
    > + 若希望持久化数据，可以执行 TiUP 的 `--tag` 参数：`tiup --tag <your-tag> playground ...`，详情参考 [TiUP 参考手册](/tiup/tiup-reference.md#-t---tag-string)。

    ```shell
    tiup client
    ```

+ 也可使用 MySQL 客户端连接 TiDB：


    ```shell
    mysql --host 127.0.0.1 --port 4000 -u root
    ```

    ```shell
    tiup clean --all
    ```

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

安装完成后会提示如下信息：

```log
Successfully set mirror to https://tiup-mirrors.pingcap.com
Detected shell: bash
Shell profile:  /home/user/.bashrc
/home/user/.bashrc has been modified to add tiup to PATH
open a new terminal or source /home/user/.bashrc to use it
Installed path: /home/user/.tiup/bin/tiup
===============================================
Have a try:     tiup playground
===============================================
```

```shell
source ${your_shell_profile}
```

    ```shell
    tiup playground
    ```

- 也可以指定 TiDB 版本以及各组件实例个数，命令类似于：


    ```shell
    tiup playground v7.4.0 --db 2 --pd 3 --kv 3
    ```

    上述命令会在本地下载并启动某个版本的集群（例如 v7.4.0）。最新版本可以通过执行 `tiup list tidb` 来查看。运行结果将显示集群的访问方式：

    ```log
    CLUSTER START SUCCESSFULLY, Enjoy it ^-^
    To connect TiDB: mysql --host 127.0.0.1 --port 4000 -u root -p (no password) --comments
    To view the dashboard: http://127.0.0.1:2379/dashboard
    PD client endpoints: [127.0.0.1:2379]
    To view the Prometheus: http://127.0.0.1:9090
    To view the Grafana: http://127.0.0.1:3000
    ```

    > **注意：**
    >
    > + 以这种方式执行的 playground，在结束部署测试后 TiUP 会清理掉原集群数据，重新执行该命令后会得到一个全新的集群。
    > + 若希望持久化数据，可以执行 TiUP 的 `--tag` 参数：`tiup --tag <your-tag> playground ...`，详情参考 [TiUP 参考手册](/tiup/tiup-reference.md#-t---tag-string)。

    ```shell
    tiup client
    ```

+ 也可使用 MySQL 客户端连接 TiDB：


    ```shell
    mysql --host 127.0.0.1 --port 4000 -u root
    ```

```shell
tiup clean --all
```

在单机上模拟部署生产环境集群

• 适用场景：希望用单台 Linux 服务器，体验 TiDB 最小的完整拓扑的集群，并模拟生产环境下的部署步骤。

本节介绍如何参照 TiUP 最小拓扑的一个 YAML 文件部署 TiDB 集群。

准备环境

开始部署 TiDB 集群前，准备一台部署主机，确保其软件满足需求：

• 推荐安装 CentOS 7.3 及以上版本
• 运行环境可以支持互联网访问，用于下载 TiDB 及相关软件安装包

最小规模的 TiDB 集群拓扑包含以下实例：

部署主机软件和环境要求如下：

• 部署需要使用部署主机的 root 用户及密码
• 部署主机关闭防火墙或者开放 TiDB 集群的节点间所需端口
• 目前 TiUP Cluster 支持在 x86_64（AMD64）和 ARM 架构上部署 TiDB 集群
  • 在 AMD64 架构下，建议使用 CentOS 7.3 及以上版本 Linux 操作系统
  • 在 ARM 架构下，建议使用 CentOS 7.6 1810 版本 Linux 操作系统

实施部署

1. 下载并安装 TiUP：

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

2. 声明全局环境变量：

   注意

   TiUP 安装完成后会提示对应 Shell profile 文件的绝对路径。在执行以下 source 命令前，需要将 ${your_shell_profile} 修改为 Shell profile 文件的实际位置。

```shell
source ${your_shell_profile}
```

3. 安装 TiUP 的 cluster 组件：

```shell
tiup cluster
```

4. 如果机器已经安装 TiUP cluster，需要更新软件版本：

```shell
tiup update --self && tiup update cluster
```

5. 由于模拟多机部署，需要通过 root 用户调大 sshd 服务的连接数限制：

   1. 修改 /etc/ssh/sshd_config 将 MaxSessions 调至 20。
   2. 重启 sshd 服务：

    ```shell
    service sshd restart
    ```

6. 创建并启动集群

   按下面的配置模板，编辑配置文件，命名为 topo.yaml，其中：

   • user: "tidb"：表示通过 tidb 系统用户（部署会自动创建）来做集群的内部管理，默认使用 22 端口通过 ssh 登录目标机器
   • replication.enable-placement-rules：设置这个 PD 参数来确保 TiFlash 正常运行
   • host：设置为本部署主机的 IP

   配置模板如下：

```yaml
# # Global variables are applied to all deployments and used as the default value of
# # the deployments if a specific deployment value is missing.
global:
 user: "tidb"
 ssh_port: 22
 deploy_dir: "/tidb-deploy"
 data_dir: "/tidb-data"

# # Monitored variables are applied to all the machines.
monitored:
 node_exporter_port: 9100
 blackbox_exporter_port: 9115

server_configs:
 tidb:
   instance.tidb_slow_log_threshold: 300
 tikv:
   readpool.storage.use-unified-pool: false
   readpool.coprocessor.use-unified-pool: true
 pd:
   replication.enable-placement-rules: true
   replication.location-labels: ["host"]
 tiflash:
   logger.level: "info"

pd_servers:
 - host: 10.0.1.1

tidb_servers:
 - host: 10.0.1.1

tikv_servers:
 - host: 10.0.1.1
   port: 20160
   status_port: 20180
   config:
     server.labels: { host: "logic-host-1" }

 - host: 10.0.1.1
   port: 20161
   status_port: 20181
   config:
     server.labels: { host: "logic-host-2" }

 - host: 10.0.1.1
   port: 20162
   status_port: 20182
   config:
     server.labels: { host: "logic-host-3" }

tiflash_servers:
 - host: 10.0.1.1

monitoring_servers:
 - host: 10.0.1.1

grafana_servers:
 - host: 10.0.1.1
```

7. 执行集群部署命令：

```shell
tiup cluster deploy <cluster-name> <version> ./topo.yaml --user root -p
```

- 参数 `<cluster-name>` 表示设置集群名称
- 参数 `<version>` 表示设置集群版本，例如 `v7.4.0`。可以通过 `tiup list tidb` 命令来查看当前支持部署的 TiDB 版本
- 参数 `-p` 表示在连接目标机器时使用密码登录

    > **注意：**
    >
    > 如果主机通过密钥进行 SSH 认证，请使用 `-i` 参数指定密钥文件路径，`-i` 与 `-p` 不可同时使用。

按照引导，输入”y”及 root 密码，来完成部署：

```log
Do you want to continue? [y/N]:  y
Input SSH password:
```

8. 启动集群：

```shell
tiup cluster start <cluster-name>
```

9. 访问集群：

   • 安装 MySQL 客户端。如果已安装 MySQL 客户端则可跳过这一步骤。

    ```shell
    yum -y install mysql
    ```

- 访问 TiDB 数据库，密码为空：

    ```shell
    mysql -h 10.0.1.1 -P 4000 -u root
    ```

- 访问 TiDB 的 Grafana 监控：

    通过 <http://{grafana-ip}:3000> 访问集群 Grafana 监控页面，默认用户名和密码均为 `admin`。

- 访问 TiDB 的 Dashboard：

    通过 <http://{pd-ip}:2379/dashboard> 访问集群 [TiDB Dashboard](/dashboard/dashboard-intro.md) 监控页面，默认用户名为 `root`，密码为空。

- 执行以下命令确认当前已经部署的集群列表：

    ```shell
    tiup cluster list
    ```

- 执行以下命令查看集群的拓扑结构和状态：

    ```shell
    tiup cluster display <cluster-name>
    ```

探索更多

如果你刚刚部署好一套 TiDB 本地测试集群，你可以继续：

• 学习 TiDB SQL 操作
• 迁移数据到 TiDB

如果你准备好在生产环境部署 TiDB，你可以继续：

• 使用 TiUP 部署 TiDB 集群
• 使用 TiDB Operator 在 Kubernetes 上部署 TiDB

如果你想使用 TiFlash 作为数据分析的解决方案，可参阅以下文档：

• 使用 TiFlash
• TiFlash 简介