Skip to main content

Get Started with TDengine TSDB Using Docker

This page shows how to start TDengine TSDB Enterprise with Docker and complete a basic walkthrough: start the service, open the CLI, write data, and run queries. If you prefer not to use Docker, see Get Started with TDengine TSDB Using an Installation Package. If you want to contribute code or explore internals, see the TDengine GitHub repository.

note

Starting with version 3.3.7.0, TDengine TSDB image names are as follows:

  • Community Edition: tdengine/tdengine was renamed to tdengine/tsdb
  • Enterprise Edition: tdengine/tdengine-ee was renamed to tdengine/tsdb-ee

Before You Begin​

  1. Docker is installed on your machine, and your user can run the docker command.
  2. Your machine can reach Docker Hub, or you have obtained an offline image from the TDengine product download center.
  3. Ensure that the network ports required by TDengine TSDB are not currently in use. For more information, see Network Port Requirements.

Start the Service​

Pull the Image​

Pull the latest Enterprise Edition image:

docker pull tdengine/tsdb-ee:latest

You can also pull a specific version. For example:

docker pull tdengine/tsdb-ee:{{VERSION}}

If you cannot access Docker Hub directly, go to the Docker image download page in the TDengine product download center, download the offline image, load it as described on that page, and update the image name and tag.

Start the Container​

Run the following command to start the TDengine container:

docker run -d \
  -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 \
  -p 6050:6050 -p 6055:6055 \
  --name tdengine-tsdb \
  tdengine/tsdb-ee

For port usage of TDengine services, see Network Port Requirements in the operations guide.

Check Container Status​

Run the following command to check the container status:

docker ps -f name=tdengine-tsdb

Check the STATUS field in the output. If it shows Up ... (healthy), the container has started and is running normally.

Enter the Container​

Run the following command to enter the container:

docker exec -it tdengine-tsdb bash

Inside the container, you can run Linux commands and try TDengine with tools such as taos and taosBenchmark.

For more details on deploying TDengine with Docker, see Docker Deployment.

Quick Start​

Open the Command Line​

TDengine provides the taos command-line tool for checking service status, running SQL, and managing databases and tables. After you enter the shell, you can try write and query operations immediately.

On Linux or macOS, run:

taos

On Windows, run:

taos.exe

After you enter the shell, the prompt looks like:

taos>

In the shell, each SQL statement must end with a semicolon (;). The following example creates a database, inserts two rows, and queries the result:

CREATE DATABASE demo;
USE demo;
CREATE TABLE t (ts TIMESTAMP, speed INT);
INSERT INTO t VALUES ('2019-07-15 00:00:00', 10);
INSERT INTO t VALUES ('2019-07-15 01:00:00', 20);
SELECT * FROM t;

           ts            |    speed    |
========================================
 2019-07-15 00:00:00.000 |          10 |
 2019-07-15 01:00:00.000 |          20 |

Query OK, 2 row(s) in set (0.003128s)

Besides SQL, you can use the shell to check system status and manage users. The CLI and client drivers can also be installed separately on other machines. For details, see TDengine CLI.

Write Test Data​

taosBenchmark is a TDengine testing tool for generating sample data and trying write, query, and subscription features. It can simulate data from many devices and supports configuring the database, supertable, tag columns, data columns, subtable count, records per subtable, write interval, worker threads, and whether to write out-of-order data.

After confirming that the TDengine service is running, run the following command in a terminal:

taosBenchmark -y

This automatically creates a supertable named meters in the test database. The supertable contains 10,000 subtables named d0 through d9999, each with 10,000 records. Each record has four fields: ts (timestamp), current, voltage, and phase. Timestamps range from 2017-07-14 10:40:00.000 to 2017-07-14 10:40:09.999. Each table also has two tags, location and groupId, where groupId is from 1 to 10 and location includes California cities such as California.Campbell and California.Cupertino.

The command writes 100 million records. Elapsed time depends on hardware; even on a typical PC server, it usually takes only about ten seconds.

taosBenchmark provides many options for customizing table count, record count, and other test settings. Run the following command to list all parameters:

taosBenchmark --help

For detailed usage, see taosBenchmark Reference.

Query Test Data​

After writing data with taosBenchmark, run the following queries in the shell to experience query performance.

  1. Count all records under the meters supertable:
SELECT COUNT(*) FROM test.meters;

     count(*)     |
===================
        100000000 |

Query OK, 1 row(s) in set (0.075247s)
  1. Compute the average, maximum, and minimum over 100 million records:
SELECT AVG(current), MAX(voltage), MIN(phase) FROM test.meters;

   avg(current)   | max(voltage) | min(phase) |
===============================================
 10.2084751316071 |          258 |        145 |

Query OK, 1 row(s) in set (0.094037s)
  1. Count records where location = "California.SanFrancisco":
SELECT COUNT(*) FROM test.meters WHERE location = "California.SanFrancisco";

     count(*)     |
===================
         10340000 |

Query OK, 1 row(s) in set (0.050540s)
  1. Compute the average, maximum, and minimum for all records where groupId = 10:
SELECT AVG(current), MAX(voltage), MIN(phase) FROM test.meters WHERE groupId = 10;

   avg(current)   | max(voltage) | min(phase) |
===============================================
 10.2084751316071 |          258 |        145 |

Query OK, 1 row(s) in set (0.033754s)
  1. Aggregate table d1001 every 10 seconds for average, maximum, and minimum:
SELECT _wstart, AVG(current), MAX(voltage), MIN(phase)
FROM test.d1001 INTERVAL(10s);

         _wstart         |   avg(current)   | max(voltage) | min(phase) |
=========================================================================
 2017-07-14 10:40:00.000 | 10.2084751316071 |          258 |        145 |

Query OK, 1 row(s) in set (0.004716s)

In the query above, the system pseudocolumn _wstart is the start time of each window.

Go Further​

After finishing the steps above, continue with:

What to Do Next​

After this quick start, continue with later chapters to learn more about TDengine data modeling, writing, querying, data subscription, and stream processing.