tdengine/tsdb

What is TDengine TSDB ？

TDengine is an open source, high-performance, cloud native and AI powered time-series database designed for Internet of Things (IoT), Connected Cars, and Industrial IoT. It enables efficient, real-time data ingestion, processing, and analysis of TB and even PB scale data per day, generated by billions of sensors and data collectors. TDengine differentiates itself from other time-series databases with the following advantages:

• High Performance: TDengine is the only time-series database to solve the high cardinality issue to support billions of data collection points while out performing other time-series databases for data ingestion, querying and data compression.

• Simplified Solution: Through built-in caching, stream processing, data subscription and AI agent features, TDengine provides a simplified solution for time-series data processing. It reduces system design complexity and operation costs significantly.

• Cloud Native: Through native distributed design, sharding and partitioning, separation of compute and storage, RAFT, support for kubernetes deployment and full observability, TDengine is a cloud native Time-Series Database and can be deployed on public, private or hybrid clouds.

• AI Powered: Through the built in AI agent TDgpt, TDengine can connect to a variety of time series foundation model, large language model, machine learning and traditional algorithms to provide time series data forecasting, anomly detection, imputation and classification.

• Ease of Use: For administrators, TDengine significantly reduces the effort to deploy and maintain. For developers, it provides a simple interface, simplified solution and seamless integrations for third party tools. For data users, it gives easy data access.

• Easy Data Analytics: Through super tables, storage and compute separation, data partitioning by time interval, pre-computation and AI agent, TDengine makes it easy to explore, format, and get access to data in a highly efficient way.

• Open Source: TDengine’s core modules, including cluster feature and AI agent, are all available under open source licenses. It has gathered 23.7k stars on GitHub. There is an active developer community, and over 730k running instances worldwide.

For a full list of TDengine competitive advantages, please check here. The easiest way to experience TDengine is through TDengine Cloud. For the latest TDengine component TDgpt, please refer to TDgpt README for details.

How to use Docker to run TDengine TSDB

Starting with the 3.3.7.0 Docker workflow, this repository uses the following image names:

• tdengine/tsdb for TDengine TSDB OSS
• tdengine/tsdb for TDengine TSDB Enterprise

This repository is intended for 3.3.7.0 and later.

Quick Start

Run a TDengine container with persistent data and log directories:

bash
docker run -d \
  --name tdengine-tsdb \
  -v ~/data/taos/dnode/data:/var/lib/taos \
  -v ~/data/taos/dnode/log:/var/log/taos \
  -p 6030:6030 \
  -p 6041:6041 \
  -p 6043:6043 \
  -p 6060:6060 \
  -p 6044-6049:6044-6049 \
  -p 6044-6045:6044-6045/udp \
  tdengine/tsdb

After the container starts, you can verify the SQL service through the REST interface:

bash
curl -u root:taosdata -d "show databases" http://localhost:6041/rest/sql

You can also open a shell inside the container and connect with the TDengine CLI:

bash
docker exec -it tdengine-tsdb taos

Custom Passwords and Upgrades

If you use a custom root password, follow the current deployment rules:

• For 3.3.8.8 and later, provide the current root password through TAOS_ROOT_PASSWORD or TAOS_ROOT_PASSWORD_FILE.
• If the root password was changed previously, keep the deployment configuration synchronized with the actual database password before restarting the container, recreating the Pod, or upgrading the image.
• If the deployment still uses an outdated password, SQL-based checks and components that authenticate with the root account may fail.

Example with an environment variable:

bash
docker run -d \
  --name tdengine-tsdb \
  -e TAOS_ROOT_PASSWORD=my-secret-password \
  -v ~/data/taos/dnode/data:/var/lib/taos \
  -v ~/data/taos/dnode/log:/var/log/taos \
  -p 6030:6030 \
  -p 6041:6041 \
  tdengine/tsdb

Example with a password file:

bash
docker run -d \
  --name tdengine-tsdb \
  -e TAOS_ROOT_PASSWORD_FILE=/run/secrets/taos_root_password \
  -v ~/data/taos/dnode/data:/var/lib/taos \
  -v ~/data/taos/dnode/log:/var/log/taos \
  -v ~/secrets/taos_root_password:/run/secrets/taos_root_password:ro \
  -p 6030:6030 \
  -p 6041:6041 \
  tdengine/tsdb

Health Checks

taos-check startup and taos-check service are available starting from 3.4.1.0.

• taos-check startup checks whether TDengine has completed startup.
• taos-check service checks whether the SQL service is externally available.
• taos-check service uses the same password source as the container entrypoint: TAOS_ROOT_PASSWORD_FILE, TAOS_ROOT_PASSWORD, or the default password taosdata.

For 3.3.8.8, focus on keeping the password configuration correct so later health-check based deployments can upgrade cleanly.

More Deployment Options

For Docker host networking, Docker Compose, Kubernetes deployment, and the latest compatibility guidance for passwords, upgrades, and health checks, see the official documentation:

• Deploy in Docker
• TDengine Deployment Documentation
• TDengine Documentation