TDengine Cluster Maintenance Guide

Juno Qiu

July 5, 2026 / Time-Series Database Essentials-1

Cluster maintenance keeps TDengine TSDB reliable in production. Administrators need clear routines for load balancing, fault recovery, performance tuning, data management, monitoring, and regular inspection.

Load balancing

Automatic load balancing

TDengine supports automatic vgroup balancing:

-- View vgroup distribution
SELECT * FROM INFORMATION_SCHEMA.INS_VNODES;

-- Trigger balancing
BALANCE VGROUP;

Manual adjustment

-- Migrate a vgroup to a specified node
REDISTRIBUTE VGROUP 3 TO DNODE 2;

Fault recovery

Node fault detection

-- Check node status
SHOW DNODES;

-- View detailed status
SHOW DNODE 1 STATUS;

Fault recovery Process

Detect the fault, assess the impact, trigger recovery, and verify that service has returned to normal.

Recovery operations

-- Re-add a failed node
CREATE DNODE "dnode4.tdengine.com";

-- Data syncs automatically after recovery

Performance tuning

Key parameter adjustment

-- Adjust buffer size
ALTER DATABASE demo BUFFER 256;

-- Adjust cache size
ALTER DATABASE demo CACHESIZE 256;

Vgroup optimization

-- Increase vgroup count
ALTER DATABASE demo VGROUPS 10;

Data management

Data compaction

-- Manually trigger compaction
COMPACT DATABASE demo;

-- Check compaction status
SHOW DATABASE demo COMPACT;

Data retention policy

-- Set data retention period in days
ALTER DATABASE demo KEEP 90;

-- Remove expired data
TRIM DATABASE demo;

Monitoring and alerting

Key monitoring metrics

Metric	Threshold	Recommendation
CPU usage	>80%	Scale out or tune
Memory usage	>85%	Add memory
Disk usage	>90%	Scale out or clean up
Write latency	>100ms	Check storage I/O

Alert configuration

Configure alerts for the following conditions:

Node offline
Low disk space
Write failures
Query timeouts

Inspection checklist

Daily inspection

[ ] Check status of all nodes
[ ] Review error logs
[ ] Confirm normal write operations

Weekly inspection

[ ] Analyze performance trends
[ ] Check storage space
[ ] Evaluate resource usage

Monthly inspection

[ ] Assess capacity planning
[ ] Improve configuration parameters
[ ] Verify backups

Summary

Reliable cluster maintenance depends on:

A complete monitoring system
A documented fault-response plan
Regular performance reviews
Ongoing configuration tuning
Operational logs that can support audits and incident review