TiDB 数据库快速上手指南

    注意

    本指南中的 TiDB 部署方式仅适用于快速上手体验，不适用于生产环境。

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

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

    • macOS

    • Linux

    TiDB 是一个分布式系统。最基础的 TiDB 测试集群通常由 2 个 TiDB 实例、3 个 TiKV 实例、3 个 PD 实例和可选的 TiFlash 实例构成。通过 TiUP Playground，可以快速搭建出上述的一套基础测试集群，步骤如下：

    1. 下载并安装 TiUP。

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

      2. Detected shell: zsh
      3. Shell profile:  /Users/user/.zshrc
      4. /Users/user/.zshrc has been modified to add tiup to PATH
      5. open a new terminal or source /Users/user/.zshrc to use it
      6. Installed path: /Users/user/.tiup/bin/tiup
      7. ===============================================
      8. Have a try:     tiup playground
      9. ===============================================

    2. 声明全局环境变量。

      快速上手 TiDB - 图2

      注意

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

      1. source ${your_shell_profile}

    3. 在当前 session 执行以下命令启动集群。

      • 直接执行 tiup playground 命令会运行最新版本的 TiDB 集群，其中 TiDB、TiKV、PD 和 TiFlash 实例各 1 个：

        1. tiup playground

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

        1. tiup playground v6.5.2 --db 2 --pd 3 --kv 3

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

        1. CLUSTER START SUCCESSFULLY, Enjoy it ^-^
        2. To connect TiDB: mysql --comments --host 127.0.0.1 --port 4001 -u root -p (no password)
        3. To connect TiDB: mysql --comments --host 127.0.0.1 --port 4000 -u root -p (no password)
        4. To view the dashboard: http://127.0.0.1:2379/dashboard
        5. PD client endpoints: [127.0.0.1:2379 127.0.0.1:2382 127.0.0.1:2384]
        6. To view the Prometheus: http://127.0.0.1:9090
        7. 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 参考手册。

    4. 新开启一个 session 以访问 TiDB 数据库。

      • 使用 TiUP client 连接 TiDB：

        1. tiup client

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

        1. mysql --host 127.0.0.1 --port 4000 -u root

    5. 通过 访问 TiDB 的 Prometheus 管理界面。

    6. 通过 http://127.0.0.1:2379/dashboard 访问 页面，默认用户名为 root，密码为空。

    7. 通过 http://127.0.0.1:3000 访问 TiDB 的 Grafana 界面，默认用户名和密码都为 admin。

    8. （可选） 进行分析。

    9. 测试完成之后，可以通过执行以下步骤来清理集群：

      1. 按下 Control+C 键停掉上述启用的 TiDB 服务。

      2. 等待服务退出操作完成后，执行以下命令：

        1. tiup clean --all

    快速上手 TiDB - 图4

    注意

    TiUP Playground 默认监听 127.0.0.1，服务仅本地可访问；若需要使服务可被外部访问，可使用 --host 参数指定监听网卡绑定外部可访问的 IP。

    TiDB 是一个分布式系统。最基础的 TiDB 测试集群通常由 2 个 TiDB 实例、3 个 TiKV 实例、3 个 PD 实例和可选的 TiFlash 实例构成。通过 TiUP Playground，可以快速搭建出上述的一套基础测试集群，步骤如下：

    1. 下载并安装 TiUP。

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

    2. 声明全局环境变量。

      注意

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

      1. source ${your_shell_profile}

    3. 在当前 session 执行以下命令启动集群。

      • 直接运行 tiup playground 命令会运行最新版本的 TiDB 集群，其中 TiDB、TiKV、PD 和 TiFlash 实例各 1 个：

        1. tiup playground

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

        1. tiup playground v6.5.2 --db 2 --pd 3 --kv 3

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

        1. CLUSTER START SUCCESSFULLY, Enjoy it ^-^
        2. To view the dashboard: http://127.0.0.1:2379/dashboard
        3. PD client endpoints: [127.0.0.1:2379]
        4. To view the Prometheus: http://127.0.0.1:9090
        5. To view the Grafana: http://127.0.0.1:3000

        快速上手 TiDB - 图6

        注意

        • 以这种方式执行的 playground，在结束部署测试后 TiUP 会清理掉原集群数据，重新执行该命令后会得到一个全新的集群。
        • 若希望持久化数据，可以执行 TiUP 的 参数：tiup --tag <your-tag> playground ...，详情参考 TiUP 参考手册。

    4. 新开启一个 session 以访问 TiDB 数据库。

      • 使用 TiUP client 连接 TiDB：

        1. tiup client

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

        1. mysql --host 127.0.0.1 --port 4000 -u root

    5. 通过 访问 TiDB 的 Prometheus 管理界面。

    6. 通过 http://127.0.0.1:2379/dashboard 访问 页面，默认用户名为 root，密码为空。

    7. 通过 http://127.0.0.1:3000 访问 TiDB 的 Grafana 界面，默认用户名和密码都为 admin。

    8. （可选） 进行分析。

    9. 测试完成之后，可以通过执行以下步骤来清理集群：

      1. 按下 Control+C 键停掉上述启用的 TiDB 服务。

      2. 等待服务退出操作完成后，执行以下命令：

      1. tiup clean --all

    注意

    TiUP Playground 默认监听 127.0.0.1，服务仅本地可访问。若需要使服务可被外部访问，可使用 --host 参数指定监听网卡绑定外部可访问的 IP。

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

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

    准备一台部署主机，确保其软件满足需求：

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

    最小规模的 TiDB 集群拓扑：

    快速上手 TiDB - 图8

    注意

    下表中拓扑实例的 IP 为示例 IP。在实际部署时，请替换为实际的 IP。

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

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

    实施部署

    注意

    你可以使用 Linux 系统的任一普通用户或 root 用户登录主机，以下步骤以 root 用户为例。

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

    2. 声明全局环境变量：

      快速上手 TiDB - 图10

      注意

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

      1. source ${your_shell_profile}

    3. 安装 TiUP 的 cluster 组件：

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

      1. tiup update --self && tiup update cluster

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

      1. 修改 /etc/ssh/sshd_config 将 MaxSessions 调至 20。

      2. 重启 sshd 服务：

        1. service sshd restart

    6. 创建并启动集群

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

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

      配置模板如下：

      1. # # Global variables are applied to all deployments and used as the default value of
      2. # # the deployments if a specific deployment value is missing.
      3. global:
      4.  user: "tidb"
      5.  ssh_port: 22
      6.  deploy_dir: "/tidb-deploy"
      7.  data_dir: "/tidb-data"
      9. # # Monitored variables are applied to all the machines.
      10. monitored:
      11.  node_exporter_port: 9100
      12.  blackbox_exporter_port: 9115
      14. server_configs:
      15.  tidb:
      16.    log.slow-threshold: 300
      17.  tikv:
      18.    readpool.storage.use-unified-pool: false
      19.    readpool.coprocessor.use-unified-pool: true
      20.  pd:
      21.    replication.enable-placement-rules: true
      22.  tiflash:
      23.    logger.level: "info"
      26.  - host: 10.0.1.1
      28. tidb_servers:
      29.  - host: 10.0.1.1
      31. tikv_servers:
      32.  - host: 10.0.1.1
      33.    port: 20160
      34.    status_port: 20180
      35.    config:
      36.      server.labels: { host: "logic-host-1" }
      38.  - host: 10.0.1.1
      39.    port: 20161
      40.    status_port: 20181
      41.    config:
      42.      server.labels: { host: "logic-host-2" }
      44.  - host: 10.0.1.1
      45.    port: 20162
      46.    status_port: 20182
      47.    config:
      48.      server.labels: { host: "logic-host-3" }
      50. tiflash_servers:
      51.  - host: 10.0.1.1
      53. monitoring_servers:
      54.  - host: 10.0.1.1
      56. grafana_servers:
      57.  - host: 10.0.1.1

    7. 执行集群部署命令：

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

      • 参数 <cluster-name> 表示设置集群名称

      • 参数 <version> 表示设置集群版本，例如 v6.5.2。可以通过 tiup list tidb 命令来查看当前支持部署的 TiDB 版本

      • 参数 -p 表示在连接目标机器时使用密码登录

        注意

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

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

      1. Do you want to continue? [y/N]:  y
      2. Input SSH password:

    8. 启动集群：

      1. tiup cluster start <cluster-name>

    9. 访问集群：

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

        1. yum -y install mysql

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

        1. mysql -h 10.0.1.1 -P 4000 -u root

      • 访问 TiDB 的 Grafana 监控：

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

      • 访问 TiDB 的 Dashboard：

        通过 访问集群 TiDB Dashboard 监控页面，默认用户名为 ，密码为空。

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

        1. tiup cluster list

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