- About TiDB
- Quick Start
- Deploy
- Software and Hardware Requirements
- Environment Configuration Checklist
- Plan Cluster Topology
- Install and Start
- Verify Cluster Status
- Test Cluster Performance
- Migrate
- Overview
- Migrate from MySQL
- Migrate from CSV Files
- Migrate from SQL Files
- Replicate Incremental Data between TiDB Clusters in Real Time
- Maintain
- Upgrade
- Scale
- Backup and Restore
- Use BR Tool (Recommended)
- Configure Time Zone
- Daily Checklist
- Maintain TiFlash
- Maintain TiDB Using TiUP
- Modify Configuration Online
- Online Unsafe Recovery
- Monitor and Alert
- Troubleshoot
- TiDB Troubleshooting Map
- Identify Slow Queries
- Analyze Slow Queries
- SQL Diagnostics
- Identify Expensive Queries
- Statement Summary Tables
- Troubleshoot Hotspot Issues
- Troubleshoot Increased Read and Write Latency
- Save and Restore the On-Site Information of a Cluster
- Troubleshoot Cluster Setup
- Troubleshoot High Disk I/O Usage
- Troubleshoot Lock Conflicts
- Troubleshoot TiFlash
- Troubleshoot Write Conflicts in Optimistic Transactions
- Performance Tuning
- System Tuning
- Software Tuning
- SQL Tuning
- Overview
- Understanding the Query Execution Plan
- SQL Optimization Process
- Overview
- Logic Optimization
- Physical Optimization
- Prepare Execution Plan Cache
- Control Execution Plans
- Tutorials
- Multiple Data Centers in One City Deployment
- Three Data Centers in Two Cities Deployment
- Two Data Centers in One City Deployment
- Read Historical Data
- Use Stale Read (Recommended)
- Use the
tidb_snapshot
System Variable
- Best Practices
- Use Placement Rules
- Use Load Base Split
- Use Store Limit
- TiDB Tools
- Overview
- Use Cases
- Download
- TiUP
- TiDB Operator
- Backup & Restore (BR)
- TiDB Binlog
- TiDB Lightning
- TiDB Data Migration
- TiCDC
- Dumpling
- sync-diff-inspector
- TiSpark
- Reference
- Cluster Architecture
- Key Monitoring Metrics
- Secure
- Privileges
- SQL
- SQL Language Structure and Syntax
- SQL Statements
ADD COLUMN
ADD INDEX
ADMIN
ADMIN CANCEL DDL
ADMIN CHECKSUM TABLE
ADMIN CHECK [TABLE|INDEX]
ADMIN SHOW DDL [JOBS|QUERIES]
ADMIN SHOW TELEMETRY
ALTER DATABASE
ALTER INDEX
ALTER INSTANCE
ALTER PLACEMENT POLICY
ALTER TABLE
ALTER USER
ANALYZE TABLE
BACKUP
BEGIN
CHANGE COLUMN
COMMIT
CHANGE DRAINER
CHANGE PUMP
CREATE [GLOBAL|SESSION] BINDING
CREATE DATABASE
CREATE INDEX
CREATE PLACEMENT POLICY
CREATE ROLE
CREATE SEQUENCE
CREATE TABLE LIKE
CREATE TABLE
CREATE USER
CREATE VIEW
DEALLOCATE
DELETE
DESC
DESCRIBE
DO
DROP [GLOBAL|SESSION] BINDING
DROP COLUMN
DROP DATABASE
DROP INDEX
DROP PLACEMENT POLICY
DROP ROLE
DROP SEQUENCE
DROP STATS
DROP TABLE
DROP USER
DROP VIEW
EXECUTE
EXPLAIN ANALYZE
EXPLAIN
FLASHBACK TABLE
FLUSH PRIVILEGES
FLUSH STATUS
FLUSH TABLES
GRANT <privileges>
GRANT <role>
INSERT
KILL [TIDB]
LOAD DATA
LOAD STATS
MODIFY COLUMN
PREPARE
RECOVER TABLE
RENAME INDEX
RENAME TABLE
REPLACE
RESTORE
REVOKE <privileges>
REVOKE <role>
ROLLBACK
SELECT
SET DEFAULT ROLE
SET [NAMES|CHARACTER SET]
SET PASSWORD
SET ROLE
SET TRANSACTION
SET [GLOBAL|SESSION] <variable>
SHOW ANALYZE STATUS
SHOW [BACKUPS|RESTORES]
SHOW [GLOBAL|SESSION] BINDINGS
SHOW BUILTINS
SHOW CHARACTER SET
SHOW COLLATION
SHOW [FULL] COLUMNS FROM
SHOW CONFIG
SHOW CREATE PLACEMENT POLICY
SHOW CREATE SEQUENCE
SHOW CREATE TABLE
SHOW CREATE USER
SHOW DATABASES
SHOW DRAINER STATUS
SHOW ENGINES
SHOW ERRORS
SHOW [FULL] FIELDS FROM
SHOW GRANTS
SHOW INDEX [FROM|IN]
SHOW INDEXES [FROM|IN]
SHOW KEYS [FROM|IN]
SHOW MASTER STATUS
SHOW PLACEMENT
SHOW PLACEMENT FOR
SHOW PLACEMENT LABELS
SHOW PLUGINS
SHOW PRIVILEGES
SHOW [FULL] PROCESSSLIST
SHOW PROFILES
SHOW PUMP STATUS
SHOW SCHEMAS
SHOW STATS_HEALTHY
SHOW STATS_HISTOGRAMS
SHOW STATS_META
SHOW STATUS
SHOW TABLE NEXT_ROW_ID
SHOW TABLE REGIONS
SHOW TABLE STATUS
SHOW [FULL] TABLES
SHOW [GLOBAL|SESSION] VARIABLES
SHOW WARNINGS
SHUTDOWN
SPLIT REGION
START TRANSACTION
TABLE
TRACE
TRUNCATE
UPDATE
USE
WITH
- Data Types
- Functions and Operators
- Overview
- Type Conversion in Expression Evaluation
- Operators
- Control Flow Functions
- String Functions
- Numeric Functions and Operators
- Date and Time Functions
- Bit Functions and Operators
- Cast Functions and Operators
- Encryption and Compression Functions
- Information Functions
- JSON Functions
- Aggregate (GROUP BY) Functions
- Window Functions
- Miscellaneous Functions
- Precision Math
- Set Operations
- List of Expressions for Pushdown
- TiDB Specific Functions
- Clustered Indexes
- Constraints
- Generated Columns
- SQL Mode
- Table Attributes
- Transactions
- Garbage Collection (GC)
- Views
- Partitioning
- Temporary Tables
- Character Set and Collation
- Placement Rules in SQL
- System Tables
mysql
- INFORMATION_SCHEMA
- Overview
ANALYZE_STATUS
CLIENT_ERRORS_SUMMARY_BY_HOST
CLIENT_ERRORS_SUMMARY_BY_USER
CLIENT_ERRORS_SUMMARY_GLOBAL
CHARACTER_SETS
CLUSTER_CONFIG
CLUSTER_HARDWARE
CLUSTER_INFO
CLUSTER_LOAD
CLUSTER_LOG
CLUSTER_SYSTEMINFO
COLLATIONS
COLLATION_CHARACTER_SET_APPLICABILITY
COLUMNS
DATA_LOCK_WAITS
DDL_JOBS
DEADLOCKS
ENGINES
INSPECTION_RESULT
INSPECTION_RULES
INSPECTION_SUMMARY
KEY_COLUMN_USAGE
METRICS_SUMMARY
METRICS_TABLES
PARTITIONS
PLACEMENT_RULES
PROCESSLIST
REFERENTIAL_CONSTRAINTS
SCHEMATA
SEQUENCES
SESSION_VARIABLES
SLOW_QUERY
STATISTICS
TABLES
TABLE_CONSTRAINTS
TABLE_STORAGE_STATS
TIDB_HOT_REGIONS
TIDB_INDEXES
TIDB_SERVERS_INFO
TIDB_TRX
TIFLASH_REPLICA
TIKV_REGION_PEERS
TIKV_REGION_STATUS
TIKV_STORE_STATUS
USER_PRIVILEGES
VIEWS
METRICS_SCHEMA
- UI
- TiDB Dashboard
- Overview
- Maintain
- Access
- Overview Page
- Cluster Info Page
- Key Visualizer Page
- Metrics Relation Graph
- SQL Statements Analysis
- Slow Queries Page
- Cluster Diagnostics
- Search Logs Page
- Instance Profiling
- Session Management and Configuration
- FAQ
- CLI
- Command Line Flags
- Configuration File Parameters
- System Variables
- Storage Engines
- Telemetry
- Errors Codes
- Table Filter
- Schedule Replicas by Topology Labels
- FAQs
- Release Notes
- All Releases
- Release Timeline
- v5.3
- v5.2
- v5.1
- v5.0
- v4.0
- v3.1
- v3.0
- v2.1
- v2.0
- v1.0
- Glossary
Quick Start Guide for the TiDB Database Platform
This guide walks you through the quickest way to get started with TiDB. For non-production environments, you can deploy your TiDB database by either of the following methods:
- Deploy a local test cluster (for Mac and Linux)
- Simulate production deployment on a single machine (for Linux only)
TiDB, TiUP and TiDB Dashboard share usage details with PingCAP to help understand how to improve the product. For details about what is shared and how to disable the sharing, see Telemetry.
The deployment method provided in this guide is ONLY FOR quick start, NOT FOR production.
- To deploy an on-premises production cluster, see production installation guide.
- To deploy TiDB in Kubernetes, see Get Started with TiDB in Kubernetes.
- To manage TiDB in the cloud, see TiDB Cloud Quick Start.
Deploy a local test cluster
- Scenario: Quickly deploy a local TiDB cluster for testing using a single Mac or Linux server. By deploying such a cluster, you can learn the basic architecture of TiDB and the operation of its components, such as TiDB, TiKV, PD, and the monitoring components.
As a distributed system, a basic TiDB test cluster usually consists of 2 TiDB instances, 3 TiKV instances, 3 PD instances, and optional TiFlash instances. With TiUP Playground, you can quickly build the test cluster by taking the following steps:
Download and install TiUP:
curl --proto '=https' --tlsv1.2 -sSf https://tiup-mirrors.pingcap.com/install.sh | sh
Declare the global environment variable:
NoteAfter the installation, TiUP displays the absolute path of the corresponding
profile
file. You need to modify the followingsource
command according to the path.source .bash_profile
Start the cluster in the current session:
If you want 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:
tiup playground
If you want to specify the TiDB version and the number of the instances of each component, run a command like this:
tiup playground v5.3.1 --db 2 --pd 3 --kv 3
The command downloads a version cluster to the local machine and starts it, such as v5.3.1. To view the latest version, run
tiup list tidb
.This command returns the access methods of the cluster:
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 Prometheus: http://127.0.0.1:9090 To view Grafana: http://127.0.0.1:3000
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 TiUP Reference Guide.
- Since v5.2.0, TiDB supports running
Start a new session to access TiDB:
Use the TiUP client to connect to TiDB.
tiup client
You can also use the MySQL client to connect to TiDB.
mysql --host 127.0.0.1 --port 4000 -u root
Access the Prometheus dashboard of TiDB at http://127.0.0.1:9090.
Access the TiDB Dashboard at http://127.0.0.1:2379/dashboard. The default username is
root
, with an empty password.(Optional) Load data to TiFlash for analysis.
Clean up the cluster after the test deployment:
Stop the process by pressing
ctrl-c
.Run the following command:
tiup clean --all
TiUP Playground listens on 127.0.0.1
by default, and the service is only locally accessible. If you want the service to be externally accessible, specify the listening address using the --host
parameter to bind the network interface card (NIC) to an externally accessible IP address.
As a distributed system, a basic TiDB test cluster usually consists of 2 TiDB instances, 3 TiKV instances, 3 PD instances, and optional TiFlash instances. With TiUP Playground, you can quickly build the test cluster by taking the following steps:
Download and install TiUP:
curl --proto '=https' --tlsv1.2 -sSf https://tiup-mirrors.pingcap.com/install.sh | sh
Declare the global environment variable:
NoteAfter the installation, TiUP displays the absolute path of the corresponding
profile
file. You need to modify the followingsource
command according to the path.source .bash_profile
Start the cluster in the current session:
If you want 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:
tiup playground
If you want to specify the TiDB version and the number of the instances of each component, run a command like this:
tiup playground v5.3.1 --db 2 --pd 3 --kv 3
The command downloads a version cluster to the local machine and starts it, such as v5.3.1. To view the latest version, run
tiup list tidb
.This command returns the access methods of the cluster:
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
NoteFor 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 TiUP Reference Guide.
Start a new session to access TiDB:
Use the TiUP client to connect to TiDB.
tiup client
You can also use the MySQL client to connect to TiDB.
mysql --host 127.0.0.1 --port 4000 -u root
Access the Prometheus dashboard of TiDB at http://127.0.0.1:9090.
Access the TiDB Dashboard at http://127.0.0.1:2379/dashboard. The default username is
root
, with an empty password.Access the Grafana dashboard of TiDB through http://127.0.0.1:3000. Both the default username and password are
admin
.(Optional) Load data to TiFlash for analysis.
Clean up the cluster after the test deployment:
Stop the process by pressing
ctrl-c
.Run the following command:
tiup clean --all
TiUP Playground listens on 127.0.0.1
by default, and the service is only locally accessible. If you want the service to be externally accessible, specify the listening address using the --host
parameter to bind the network interface card (NIC) to an externally accessible IP address.
Simulate production deployment on a single machine
- Scenario: Experience the smallest TiDB cluster with the complete topology and simulate the production deployment steps on a single Linux server.
This section describes how to deploy a TiDB cluster using a YAML file of the smallest topology in TiUP.
Prepare
Prepare a target machine that meets the following requirements:
- CentOS 7.3 or a later version is installed
- The Linux OS has access to the Internet, which is required to download TiDB and related software installation packages
The smallest TiDB cluster topology is as follows:
The IP address of the following instances only serves as an example IP. In your actual deployment, you need to replace the IP with your actual IP.
Instance | Count | IP | Configuration |
---|---|---|---|
TiKV | 3 | 10.0.1.1 10.0.1.1 10.0.1.1 | Avoid conflict between the port and the directory |
TiDB | 1 | 10.0.1.1 | The default port Global directory configuration |
PD | 1 | 10.0.1.1 | The default port Global directory configuration |
TiFlash | 1 | 10.0.1.1 | The default port Global directory configuration |
Monitor | 1 | 10.0.1.1 | The default port Global directory configuration |
Other requirements for the target machine:
The
root
user and its password is requiredStop the firewall service of the target machine, or open the port needed by the TiDB cluster nodes
Currently, TiUP supports deploying TiDB on the x86_64 (AMD64 and ARM) architectures:
- It is recommended to use CentOS 7.3 or later versions on AMD64
- It is recommended to use CentOS 7.6 1810 on ARM
Deploy
You can log in to the target machine as a regular user or the root
user. The following steps use the root
user as an example.
Download and install TiUP:
curl --proto '=https' --tlsv1.2 -sSf https://tiup-mirrors.pingcap.com/install.sh | sh
Declare the global environment variable.
NoteAfter the installation, TiUP displays the absolute path of the corresponding
profile
file. You need to modify the followingsource
command according to the path.source .bash_profile
Install the cluster component of TiUP:
tiup cluster
If the TiUP cluster is already installed on the machine, update the software version:
tiup update --self && tiup update cluster
Use the
root
user privilege to increase the connection limit of thesshd
service. This is because TiUP needs to simulate deployment on multiple machines.Modify
/etc/ssh/sshd_config
, and setMaxSessions
to20
.Restart the
sshd
service:service sshd restart
Create and start the cluster:
Edit the configuration file according to the following template, and name it as
topo.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: log.slow-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
user: "tidb"
: Use thetidb
system user (automatically created during deployment) to perform the internal management of the cluster. By default, use port 22 to log in to the target machine via SSH.replication.enable-placement-rules
: This PD parameter is set to ensure that TiFlash runs normally.host
: The IP of the target machine.
Execute the cluster deployment command:
tiup cluster deploy <cluster-name> <tidb-version> ./topo.yaml --user root -p
<cluster-name>
: Set the cluster name<tidb-version>
: Set the TiDB cluster version. You can see all the supported TiDB versions by running thetiup list tidb
command
Enter "y" and the
root
user's password to complete the deployment:Do you want to continue? [y/N]: y Input SSH password:
Start the cluster:
tiup cluster start <cluster-name>
Access the cluster:
Install the MySQL client. If it is already installed, skip this step.
yum -y install mysql
Access TiDB. The password is empty:
mysql -h 10.0.1.1 -P 4000 -u root
Access the Grafana monitoring dashboard at http://{grafana-ip}:3000. The default username and password are both
admin
.Access the TiDB Dashboard at http://{pd-ip}:2379/dashboard. The default username is
root
, and the password is empty.To view the currently deployed cluster list:
tiup cluster list
To view the cluster topology and status:
tiup cluster display <cluster-name>
What's next
If you have just deployed a TiDB cluster for the local test environment:
If you are ready to deploy a TiDB cluster for the production environment:
If you're looking for analytics solution with TiFlash: