TiDB 8.5.7 on AWS User Guide

Overview

This guide covers launching and using the TiDB 8.5.7 on Ubuntu 24.04 AMI from cloudimg on Amazon EC2. It is one version of the cloudimg distributed and embedded SQL database listing on AWS Marketplace; you pick it as the software version when you subscribe and launch.

TiDB is an open source distributed SQL database from PingCAP, licensed Apache-2.0. It speaks the MySQL wire protocol, so existing MySQL clients, drivers and tools connect to it unchanged, and it separates compute from storage across three components:

• TiDB, the stateless SQL layer that parses, plans and runs queries.
• TiKV, the transactional key-value store that holds the rows, organised into Raft groups.
• PD (Placement Driver), the cluster's metadata store and scheduler. PD also serves TiDB Dashboard.

What the cloudimg image adds:

• No default login. Upstream TiDB creates root with an empty password. This image ships no bootstrapped cluster at all: on first boot your instance bootstraps its own cluster with a root password generated on the instance, written to /root/tidb-credentials.txt (root only). The SQL layer is held on the loopback address until first boot has proved that the empty password is refused and the new one works, and only then listens on the network. If first boot cannot finish, the SQL layer stays stopped.
• TLS on the MySQL port from the first boot. Each instance generates its own TLS key and certificate for port 4000. No key ships in the image.
• Internal ports on localhost only. PD (2379, 2380), TiKV (20160, 20180), the TiDB status port (10080), Prometheus (9090), ng-monitoring (12020) and TiDB Dashboard listen on 127.0.0.1. Only SSH and the SQL port 4000 listen on the network, and the security group opens SSH only.
• No metadata access for the database. Every TiDB service and the first-boot service are blocked from the instance metadata service, and the AMI requires IMDSv2.
• Telemetry off in the TiDB configuration, the tidb_enable_telemetry setting and TiDB Dashboard.
• Your own cluster identity. PD's cluster ID and TiKV's store ID are created on your instance, never copied from the build.
• A dedicated data volume. PD, TiKV, Prometheus and ng-monitoring keep their data on a 64 GiB gp3 EBS volume mounted at /var/lib/tidb, separate from the root volume.
• Fully patched Ubuntu 24.04 LTS at build time, with unattended security upgrades switched on.

What is on the image: TiDB, TiKV and PD 8.5.7 (Community edition, the v8.5 LTS line) with TiDB Dashboard, Prometheus and ng-monitoring from PingCAP's official release archives, each checked against the SHA-256 digest in PingCAP's signed release manifest; the MariaDB mysql client; cloud-init and the AWS Systems Manager agent.

Default user: ubuntu · Architecture: x86_64 · Recommended instance type: m5.large

What a single node does and does not give you

This is the smallest arrangement that is still a real TiDB cluster rather than a mock-storage stub, so it is a faithful environment for development, evaluation, CI and staging, and for single-box workloads that are backed up.

It is also one PD member and one TiKV store, so every Raft group holds a single replica:

• There is exactly one copy of your data.
• There is no automatic failover and no high availability.
• Losing the instance or its data volume means losing the database.

TiDB's production resilience comes from three or more PD members and three or more TiKV stores across Availability Zones. This image does not provide that. Treat backups as mandatory.

Prerequisites

• An AWS account subscribed to the listing, an EC2 key pair and a VPC subnet.
• A security group that allows TCP 22 (SSH) from your admin network. Open TCP 4000 only if applications on other hosts must connect, and only from their CIDRs. Never open 2379, 2380, 20160, 20180, 10080, 9090 or 12020: they listen on the loopback address only.

Step 1: Launch the instance

In the AWS Marketplace listing choose Continue to Subscribe, then Continue to Configuration, pick TiDB 8.5.7 on Ubuntu 24.04 as the software version and your Region, then Launch through EC2. Choose m5.large or larger (see Sizing), your key pair and a security group as above. The AMI includes the 64 GiB data volume; you can make it larger at launch.

With the AWS CLI (replace the values in angle brackets):

aws ec2 run-instances --region <region> --image-id <ami-id-from-the-listing> \
  --instance-type m5.large --key-name <your-key-pair> \
  --security-group-ids <your-security-group> --subnet-id <your-subnet> \
  --metadata-options HttpTokens=required,HttpEndpoint=enabled \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=tidb}]'

First boot takes one to two minutes after the instance is running: TiDB creates its whole system catalogue on the first bootstrap.

Step 2: Connect to your instance

Version	SSH user
TiDB 8.5.7 on Ubuntu 24.04	ubuntu

ssh -i <your-key.pem> ubuntu@<public-ip>

A welcome banner prints the most useful commands.

Step 3: Check the cluster

Six units make up the deployment: PD, ng-monitoring, Prometheus, TiKV, the TiDB SQL layer and the first-boot service. All six report active:

systemctl is-active tidb-pd tidb-ngm tidb-prometheus tidb-tikv tidb tidb-firstboot

active
active
active
active
active
active

Ask PD whether the storage layer is really serving. A TiKV store must be Up; this is the check that matters, because the SQL layer accepts connections even when storage is unavailable:

curl -s http://127.0.0.1:2379/pd/api/v1/stores | jq -r '.stores[] | "store \(.store.id)  \(.store.address)  \(.store.state_name)"'

store 1  127.0.0.1:20160  Up

Check what is listening. Only SSH (22) and the SQL port (4000) listen on the network; everything else is on the loopback address. PD's embedded TiDB Dashboard also opens two internal proxy ports on 127.0.0.1 with random numbers.

sudo ss -Htlnp | awk '{print $4, $6}' | sed 's/,pid=[0-9]*,fd=[0-9]*//g' | sort -u

*:4000 users:(("tidb-server"))
0.0.0.0:22 users:(("sshd"),("systemd"))
127.0.0.1:10080 users:(("tidb-server"))
127.0.0.1:12020 users:(("ng-monitoring-s"))
127.0.0.1:20180 users:(("tikv-server"))
127.0.0.1:2379 users:(("pd-server"))
127.0.0.1:2380 users:(("pd-server"))
127.0.0.1:38901 users:(("pd-server"))
127.0.0.1:39597 users:(("pd-server"))
127.0.0.1:9090 users:(("prometheus"))
127.0.0.53%lo:53 users:(("systemd-resolve"))
127.0.0.54:53 users:(("systemd-resolve"))
[::]:22 users:(("sshd"),("systemd"))
[::ffff:127.0.0.1]:20160 users:(("tikv-server"))

Step 4: Get your root password

The credentials file is readable only by root. List the setting names it holds:

sudo ls -l /root/tidb-credentials.txt
sudo grep -oE '^[a-z_.]+=' /root/tidb-credentials.txt

-rw------- 1 root root 1010 Oct 19 19:56 /root/tidb-credentials.txt
tidb.host=
tidb.private_ip=
tidb.port=
tidb.root.user=
tidb.root.password=
tidb.tls.ca_cert=

Read the whole file with sudo cat /root/tidb-credentials.txt and store the password in your password manager. It is unique to this instance.

To avoid typing the password on the command line (where it would land in your shell history and the process list), put it in a MySQL client option file that only you can read. The mysql and mysqldump clients read ~/.my.cnf automatically:

( umask 077; printf '[client]\nuser=root\nhost=127.0.0.1\nport=4000\npassword=%s\n' "$(sudo sed -n 's/^tidb.root.password=//p' /root/tidb-credentials.txt)" > ~/.my.cnf )
ls -l ~/.my.cnf

-rw------- 1 ubuntu ubuntu 82 Oct 19 19:59 /home/ubuntu/.my.cnf

Step 5: Connect over the MySQL protocol

mysql -t -e 'SELECT VERSION() AS server_version'

+--------------------+
| server_version     |
+--------------------+
| 8.0.11-TiDB-v8.5.7 |
+--------------------+

Without the option file, mysql -h 127.0.0.1 -P 4000 -u root -p prompts for the password.

The SQL port serves TLS with this instance's own certificate. Ask for TLS with --ssl and confirm the session is encrypted:

mysql -t --ssl -e "SHOW SESSION STATUS LIKE 'Ssl_cipher'"
openssl x509 -in /etc/cloudimg/tidb-tls/server.crt -noout -ext subjectAltName

+---------------+------------------------+
| Variable_name | Value                  |
+---------------+------------------------+
| Ssl_cipher    | TLS_AES_128_GCM_SHA256 |
+---------------+------------------------+
X509v3 Subject Alternative Name:
    IP Address:172.31.91.129, IP Address:127.0.0.1, DNS:localhost, IP Address:52.207.93.54, DNS:ec2-52-207-93-54.compute-1.amazonaws.com, DNS:ip-172-31-91-129.ec2.internal

The certificate names the instance's private and public addresses as they were at first boot. Copy /etc/cloudimg/tidb-tls/server.crt to a client to verify the server with --ssl-ca=server.crt --ssl-verify-server-cert.

Step 6: Run SQL

Create a database and a table, insert rows and read them back. Every write travels through the SQL layer into TiKV:

mysql -t -e "
CREATE DATABASE IF NOT EXISTS quickstart;
DROP TABLE IF EXISTS quickstart.orders;
CREATE TABLE quickstart.orders (
  id INT PRIMARY KEY AUTO_INCREMENT,
  region VARCHAR(24),
  amount DECIMAL(10,2)
);
INSERT INTO quickstart.orders (region, amount) VALUES
  ('emea', 120.50), ('apac', 340.00), ('amer', 75.25), ('emea', 210.75);
SELECT * FROM quickstart.orders;
SELECT region, COUNT(*) AS orders, ROUND(SUM(amount),2) AS revenue
  FROM quickstart.orders GROUP BY region ORDER BY revenue DESC;"

+----+--------+--------+
| id | region | amount |
+----+--------+--------+
|  1 | emea   | 120.50 |
|  2 | apac   | 340.00 |
|  3 | amer   |  75.25 |
|  4 | emea   | 210.75 |
+----+--------+--------+
+--------+--------+---------+
| region | orders | revenue |
+--------+--------+---------+
| apac   |      1 |  340.00 |
| emea   |      2 |  331.25 |
| amer   |      1 |   75.25 |
+--------+--------+---------+

Prove the rows are on disk rather than in memory by restarting the storage and SQL layers and reading them back:

sudo systemctl restart tidb-tikv tidb
for i in $(seq 1 60); do mysql -N -e 'SELECT 1' >/dev/null 2>&1 && break; sleep 2; done
mysql -t -e 'SELECT COUNT(*) AS rows_after_restart FROM quickstart.orders'

+--------------------+
| rows_after_restart |
+--------------------+
|                  4 |
+--------------------+

Step 7: Open TiDB Dashboard over an SSH tunnel

TiDB Dashboard is a web console for the cluster: instance topology, SQL statement analysis, slow queries, Top SQL and a key-space visualiser. PD serves it on the loopback address only, because the PD client port also carries unauthenticated cluster administration APIs. Reach it through an SSH tunnel from your workstation:

ssh -i <your-key.pem> -L 2379:127.0.0.1:2379 ubuntu@<public-ip>

With the tunnel open, browse to http://127.0.0.1:2379/dashboard and sign in as root with the password from Step 4. The Dashboard signs in with the TiDB SQL account, so there is no separate Dashboard password to manage.

The Overview page shows queries per second, latency and CPU, drawn from the bundled Prometheus:

Cluster Info lists the PD, TiDB and TiKV instances and their versions:

SQL Statements groups the statements the cluster has run, with latency and execution counts:

Grafana and Alertmanager are not included, so the Monitor & Alert panel on the Overview page reports metrics and alerts as unavailable; the Overview charts, Monitoring and Cluster Diagnostics pages use the bundled Prometheus.

Step 8: Connect from other hosts

The security group opens SSH only, so port 4000 is closed until you open it. Two options:

SSH tunnel (no security group change):

ssh -i <your-key.pem> -L 4000:127.0.0.1:4000 ubuntu@<public-ip>
mysql -h 127.0.0.1 -P 4000 -u root -p

Open the port to your own networks and connect with TLS. Allow TCP 4000 from your application subnets only (never 0.0.0.0/0):

aws ec2 authorize-security-group-ingress --group-id <your-security-group> \
  --protocol tcp --port 4000 --cidr <your-app-cidr>
mysql -h <private-ip> -P 4000 -u root -p --ssl --ssl-ca=server.crt --ssl-verify-server-cert

For applications, create a dedicated SQL user with only the privileges it needs rather than sharing root:

CREATE USER 'app'@'10.0.%' IDENTIFIED BY '<a-strong-password>';
GRANT SELECT, INSERT, UPDATE, DELETE ON quickstart.* TO 'app'@'10.0.%';

Security details

Every TiDB unit carries an IPAddressDeny rule for the instance metadata addresses, so a statement or a Dashboard feature that fetches a URL cannot reach instance credentials:

systemctl show -p IPAddressDeny tidb tidb-pd tidb-tikv | sort -u

IPAddressDeny=169.254.169.254/32 fd00:ec2::254/128 168.63.129.16/32

Telemetry is off in the SQL layer:

mysql -N -e 'SELECT @@global.tidb_enable_telemetry'

0

Sizing

TiDB's components each size their memory as a share of the instance's RAM by default (TiKV's block cache alone takes 45%, the SQL layer's limit 80% of the same RAM). This image sets every one of those limits explicitly and recomputes them from the instance's RAM each time a service starts, so the same AMI behaves correctly on any instance size, including after you resize.

m5.large (2 vCPU, 8 GiB) runs the single-node cluster comfortably for development and evaluation. Use m5.xlarge (4 vCPU, 16 GiB) or larger for heavier workloads. Prefer a fixed-performance type such as m5 over a burstable T-series for anything long running: TiKV compacts its storage continuously in the background, which is a sustained CPU load that drains a burstable instance's CPU credits and then shows up as write stalls. PingCAP's own production guidance is well above a single box (TiDB 8 cores and 16 GiB, TiKV 8 cores and 32 GiB, PD 4 cores and 8 GiB, each on separate hosts), so scale out to a multi-node cluster for production.

Maintenance

The services start automatically after a reboot. Data lives on the data volume:

df -h /var/lib/tidb | tail -1

/dev/nvme1n1     63G  915M   59G   2% /var/lib/tidb

Take backups. With one replica there is no redundancy inside the cluster, so an EBS snapshot of the data volume or a logical dump is all that stands between you and data loss:

mysqldump --databases quickstart > ~/quickstart-backup.sql && ls -l ~/quickstart-backup.sql && rm -f ~/quickstart-backup.sql

-rw-rw-r-- 1 ubuntu ubuntu 2004 Oct 19 20:10 /home/ubuntu/quickstart-backup.sql

To grow the data volume, modify the EBS volume in the EC2 console, then run sudo resize2fs on its device (findmnt -no SOURCE /var/lib/tidb). Ubuntu security updates install automatically through unattended-upgrades; TiDB itself is upgraded by moving to a newer cloudimg version of this listing or with PingCAP's upgrade documentation.

Support

This image is published and maintained by cloudimg with 24/7 support by email and live chat at support@cloudimg.co.uk. For TiDB itself, see the PingCAP documentation. The distributed and embedded SQL listing guide lists the other versions in this listing.