README.md 14.7 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12
<p>
<p align="center">
  <a href="https://tdengine.com" target="_blank">
  <img
    src="docs/assets/tdengine.svg"
    alt="TDengine"
    width="500"
  />
  </a>
</p>
<p>

L
liuyq-617 已提交
13
[![Build Status](https://cloud.drone.io/api/badges/taosdata/TDengine/status.svg?ref=refs/heads/master)](https://cloud.drone.io/taosdata/TDengine)
14
[![Build status](https://ci.appveyor.com/api/projects/status/kf3pwh2or5afsgl9/branch/master?svg=true)](https://ci.appveyor.com/project/sangshuduo/tdengine-2n8ge/branch/master)
15
[![Coverage Status](https://coveralls.io/repos/github/taosdata/TDengine/badge.svg?branch=develop)](https://coveralls.io/github/taosdata/TDengine?branch=develop)
S
Shuduo Sang 已提交
16
[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/4201/badge)](https://bestpractices.coreinfrastructure.org/projects/4201)
sangshuduo's avatar
sangshuduo 已提交
17
<br />
sangshuduo's avatar
sangshuduo 已提交
18
[![Twitter Follow](https://img.shields.io/twitter/follow/tdenginedb?label=TDengine&style=social)](https://twitter.com/tdenginedb)
sangshuduo's avatar
sangshuduo 已提交
19 20 21 22
[![YouTube Channel](https://img.shields.io/badge/Subscribe_@tdengine--white?logo=youtube&style=social)](https://www.youtube.com/@tdengine)
[![Discord Community](https://img.shields.io/badge/Join_Discord--white?logo=discord&style=social)](https://discord.com/invite/VZdSuUg4pS)
[![LinkedIn](https://img.shields.io/badge/Follow_LinkedIn--white?logo=linkedin&style=social)](https://www.linkedin.com/company/tdengine)
[![StackOverflow](https://img.shields.io/badge/Ask_StackOverflow--white?logo=stackoverflow&style=social&logoColor=orange)](https://stackoverflow.com/questions/tagged/tdengine)
23

陶建辉(Jeff)'s avatar
陶建辉(Jeff) 已提交
24
English | [简体中文](README-CN.md) | [TDengine Cloud](https://cloud.tdengine.com) | [Learn more about TSDB](https://tdengine.com/tsdb/)
涛思数据(TDengine)'s avatar
涛思数据(TDengine) 已提交
25

H
hzcheng 已提交
26 27
# What is TDengine?

wafwerar's avatar
wafwerar 已提交
28
TDengine is an open source, high-performance, cloud native [time-series database](https://tdengine.com/tsdb/) optimized for Internet of Things (IoT), Connected Cars, and Industrial IoT. It enables efficient, real-time data ingestion, processing, and monitoring 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:
29

D
danielclow 已提交
30
- **[High Performance](https://tdengine.com/tdengine/high-performance-time-series-database/)**: 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.
31

陶建辉(Jeff)'s avatar
陶建辉(Jeff) 已提交
32
- **[Simplified Solution](https://tdengine.com/tdengine/simplified-time-series-data-solution/)**: Through built-in caching, stream processing and data subscription features, TDengine provides a simplified solution for time-series data processing. It reduces system design complexity and operation costs significantly.
33

陶建辉(Jeff)'s avatar
陶建辉(Jeff) 已提交
34
- **[Cloud Native](https://tdengine.com/tdengine/cloud-native-time-series-database/)**: 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.
H
hzcheng 已提交
35

D
danielclow 已提交
36
- **[Ease of Use](https://tdengine.com/tdengine/easy-time-series-data-platform/)**: 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. 
H
hzcheng 已提交
37

陶建辉(Jeff)'s avatar
陶建辉(Jeff) 已提交
38
- **[Easy Data Analytics](https://tdengine.com/tdengine/time-series-data-analytics-made-easy/)**: Through super tables, storage and compute separation, data partitioning by time interval, pre-computation and other means, TDengine makes it easy to explore, format, and get access to data in a highly efficient way. 
H
hzcheng 已提交
39

S
Sai Vishwak 已提交
40
- **[Open Source](https://tdengine.com/tdengine/open-source-time-series-database/)**: TDengine’s core modules, including cluster feature, are all available under open source licenses. It has gathered 19.9k stars on GitHub. There is an active developer community, and over 139k running instances worldwide.
陶建辉(Jeff)'s avatar
陶建辉(Jeff) 已提交
41

陶建辉(Jeff)'s avatar
陶建辉(Jeff) 已提交
42
For a full list of TDengine competitive advantages, please [check here](https://tdengine.com/tdengine/). The easiest way to experience TDengine is through [TDengine Cloud](https://cloud.tdengine.com). 
陶建辉(Jeff)'s avatar
陶建辉(Jeff) 已提交
43

H
hzcheng 已提交
44
# Documentation
45

W
wade zhang 已提交
46
For user manual, system design and architecture, please refer to [TDengine Documentation](https://docs.tdengine.com) ([TDengine 文档](https://docs.taosdata.com))
H
hzcheng 已提交
47 48

# Building
H
hzcheng 已提交
49

wafwerar's avatar
wafwerar 已提交
50
At the moment, TDengine server supports running on Linux/Windows/macOS systems. Any application can also choose the RESTful interface provided by taosAdapter to connect the taosd service . TDengine supports X64/ARM64 CPU, and it will support MIPS64, Alpha64, ARM32, RISC-V and other CPU architectures in the future.
51

W
wade zhang 已提交
52
You can choose to install through source code, [container](https://docs.tdengine.com/get-started/docker/), [installation package](https://docs.tdengine.com/get-started/package/) or [Kubernetes](https://docs.tdengine.com/deployment/k8s/). This quick guide only applies to installing from source.
53 54

TDengine provide a few useful tools such as taosBenchmark (was named taosdemo) and taosdump. They were part of TDengine. By default, TDengine compiling does not include taosTools. You can use `cmake .. -DBUILD_TOOLS=true` to make them be compiled with TDengine.
陶建辉(Jeff)'s avatar
陶建辉(Jeff) 已提交
55

56
To build TDengine, use [CMake](https://cmake.org/) 3.0.2 or higher versions in the project directory.
57

58
## Install build tools
59

wafwerar's avatar
wafwerar 已提交
60
### Ubuntu 18.04 and above or Debian
61 62

```bash
sangshuduo's avatar
sangshuduo 已提交
63
sudo apt-get install -y gcc cmake build-essential git libssl-dev libgflags2.2 libgflags-dev
64 65
```

66 67 68 69
#### Install build dependencies for taosTools

To build the [taosTools](https://github.com/taosdata/taos-tools) on Ubuntu/Debian, the following packages need to be installed.

70
```bash
sangshuduo's avatar
sangshuduo 已提交
71
sudo apt install build-essential libjansson-dev libsnappy-dev liblzma-dev libz-dev zlib1g pkg-config
72 73
```

wafwerar's avatar
wafwerar 已提交
74
### CentOS 7.9
75 76 77 78

```bash
sudo yum install epel-release
sudo yum update
sangshuduo's avatar
sangshuduo 已提交
79
sudo yum install -y gcc gcc-c++ make cmake3 gflags git openssl-devel
80
sudo ln -sf /usr/bin/cmake3 /usr/bin/cmake
81 82
```

sangshuduo's avatar
sangshuduo 已提交
83
### CentOS 8/Fedora/Rocky Linux
84

85
```bash
sangshuduo's avatar
sangshuduo 已提交
86
sudo dnf install -y gcc gcc-c++ make cmake epel-release gflags git openssl-devel
J
johnnyhou327 已提交
87
```
88

89 90
#### Install build dependencies for taosTools on CentOS

91 92 93
#### CentOS 7.9

```
sangshuduo's avatar
sangshuduo 已提交
94
sudo yum install -y zlib-devel zlib-static xz-devel snappy-devel jansson jansson-devel pkgconfig libatomic libatomic-static libstdc++-static openssl-devel
95 96
```

sangshuduo's avatar
sangshuduo 已提交
97
#### CentOS 8/Fedora/Rocky Linux
98 99 100 101 102

```
sudo yum install -y epel-release
sudo yum install -y dnf-plugins-core
sudo yum config-manager --set-enabled powertools
sangshuduo's avatar
sangshuduo 已提交
103
sudo yum install -y zlib-devel zlib-static xz-devel snappy-devel jansson jansson-devel pkgconfig libatomic libatomic-static libstdc++-static openssl-devel
104 105
```

106
Note: Since snappy lacks pkg-config support (refer to [link](https://github.com/google/snappy/pull/86)), it leads a cmake prompt libsnappy not found. But snappy still works well.
107

arielyangpan's avatar
arielyangpan 已提交
108 109
If the PowerTools installation fails, you can try to use:

110
```
arielyangpan's avatar
arielyangpan 已提交
111
sudo yum config-manager --set-enabled powertools
112 113
```

114 115 116 117 118 119 120 121 122 123
#### For CentOS + devtoolset

Besides above dependencies, please run following commands:

```
sudo yum install centos-release-scl
sudo yum install devtoolset-9 devtoolset-9-libatomic-devel
scl enable devtoolset-9 -- bash
```

wafwerar's avatar
wafwerar 已提交
124
### macOS
wafwerar's avatar
wafwerar 已提交
125 126

```
sangshuduo's avatar
sangshuduo 已提交
127
brew install argp-standalone gflags pkgconfig
wafwerar's avatar
wafwerar 已提交
128 129
```

130 131
### Setup golang environment

陶建辉(Jeff)'s avatar
陶建辉(Jeff) 已提交
132
TDengine includes a few components like taosAdapter developed by Go language. Please refer to golang.org official documentation for golang environment setup.
133 134 135 136 137 138 139 140

Please use version 1.14+. For the user in China, we recommend using a proxy to accelerate package downloading.

```
go env -w GO111MODULE=on
go env -w GOPROXY=https://goproxy.cn,direct
```

141 142 143 144 145 146
The default will not build taosAdapter, but you can use the following command to build taosAdapter as the service for RESTful interface.

```
cmake .. -DBUILD_HTTP=false
```

147 148
### Setup rust environment

arielyangpan's avatar
arielyangpan 已提交
149
TDengine includes a few components developed by Rust language. Please refer to rust-lang.org official documentation for rust environment setup.
150

151 152
## Get the source codes

153
First of all, you may clone the source codes from github:
154

155 156
```bash
git clone https://github.com/taosdata/TDengine.git
B
Bison "goldeagle" Fan 已提交
157
cd TDengine
L
lihui 已提交
158
```
159

160
You can modify the file ~/.gitconfig to use ssh protocol instead of https for better download speed. You will need to upload ssh public key to GitHub first. Please refer to GitHub official documentation for detail.
161 162 163 164 165 166

```
[url "git@github.com:"]
    insteadOf = https://github.com/
```

167 168 169 170
## Special Note

[JDBC Connector](https://github.com/taosdata/taos-connector-jdbc)[Go Connector](https://github.com/taosdata/driver-go)[Python Connector](https://github.com/taosdata/taos-connector-python)[Node.js Connector](https://github.com/taosdata/taos-connector-node)[C# Connector](https://github.com/taosdata/taos-connector-dotnet)[Rust Connector](https://github.com/taosdata/taos-connector-rust) and [Grafana plugin](https://github.com/taosdata/grafanaplugin) has been moved to standalone repository.

171 172
## Build TDengine

173 174
### On Linux platform

175 176
You can run the bash script `build.sh` to build both TDengine and taosTools including taosBenchmark and taosdump as below:

177
```bash
178 179 180 181 182 183 184 185 186 187 188 189
./build.sh
```

It equals to execute following commands:

```bash
mkdir debug
cd debug
cmake .. -DBUILD_TOOLS=true
make
```

sangshuduo's avatar
sangshuduo 已提交
190
You can use Jemalloc as memory allocator instead of glibc:
191

sangshuduo's avatar
sangshuduo 已提交
192 193 194 195 196
```
apt install autoconf
cmake .. -DJEMALLOC_ENABLED=true
```

wafwerar's avatar
wafwerar 已提交
197 198
TDengine build script can detect the host machine's architecture on X86-64, X86, arm64 platform.
You can also specify CPUTYPE option like aarch64 too if the detection result is not correct:
L
lihui 已提交
199

H
huili 已提交
200
aarch64:
201

202
```bash
H
huili 已提交
203
cmake .. -DCPUTYPE=aarch64 && cmake --build .
H
huili 已提交
204
```
H
huili 已提交
205

206 207
### On Windows platform

208
If you use the Visual Studio 2013, please open a command window by executing "cmd.exe".
陶建辉(Jeff)'s avatar
陶建辉(Jeff) 已提交
209
Please specify "amd64" for 64 bits Windows or specify "x86" for 32 bits Windows when you execute vcvarsall.bat.
210

211
```cmd
212
mkdir debug && cd debug
213
"C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\vcvarsall.bat" < amd64 | x86 >
214 215 216 217
cmake .. -G "NMake Makefiles"
nmake
```

218
If you use the Visual Studio 2019 or 2017:
219 220

please open a command window by executing "cmd.exe".
陶建辉(Jeff)'s avatar
陶建辉(Jeff) 已提交
221
Please specify "x64" for 64 bits Windows or specify "x86" for 32 bits Windows when you execute vcvarsall.bat.
222 223

```cmd
224 225 226 227 228 229
mkdir debug && cd debug
"c:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvarsall.bat" < x64 | x86 >
cmake .. -G "NMake Makefiles"
nmake
```

230
Or, you can simply open a command window by clicking Windows Start -> "Visual Studio < 2019 | 2017 >" folder -> "x64 Native Tools Command Prompt for VS < 2019 | 2017 >" or "x86 Native Tools Command Prompt for VS < 2019 | 2017 >" depends what architecture your Windows is, then execute commands as follows:
231

232
```cmd
233 234 235 236 237
mkdir debug && cd debug
cmake .. -G "NMake Makefiles"
nmake
```

wafwerar's avatar
wafwerar 已提交
238
### On macOS platform
239 240 241 242 243 244

Please install XCode command line tools and cmake. Verified with XCode 11.4+ on Catalina and Big Sur.

```shell
mkdir debug && cd debug
cmake .. && cmake --build .
wafwerar's avatar
wafwerar 已提交
245
```
246

H
Hongze Cheng 已提交
247
# Installing
248

249 250 251 252
## On Linux platform

After building successfully, TDengine can be installed by

253
```bash
254
sudo make install
H
Hongze Cheng 已提交
255
```
256

D
danielclow 已提交
257
Users can find more information about directories installed on the system in the [directory and files](https://docs.tdengine.com/reference/directory/) section.
258

D
danielclow 已提交
259
Installing from source code will also configure service management for TDengine.Users can also choose to [install from packages](https://docs.tdengine.com/get-started/package/) for it.
H
hzcheng 已提交
260

H
Hongze Cheng 已提交
261
To start the service after installation, in a terminal, use:
262

263 264
```bash
sudo systemctl start taosd
H
hzcheng 已提交
265 266
```

W
update  
wenzhouwww@live.cn 已提交
267
Then users can use the TDengine CLI to connect the TDengine server. In a terminal, use:
268

269
```bash
H
hzcheng 已提交
270 271 272
taos
```

W
update  
wenzhouwww@live.cn 已提交
273
If TDengine CLI connects the server successfully, welcome messages and version info are printed. Otherwise, an error message is shown.
H
hzcheng 已提交
274

275 276 277 278 279 280 281 282
## On Windows platform

After building successfully, TDengine can be installed by:

```cmd
nmake install
```

wafwerar's avatar
wafwerar 已提交
283

284 285 286 287 288 289 290
## On macOS platform

After building successfully, TDengine can be installed by:

```bash
sudo make install
```
wafwerar's avatar
wafwerar 已提交
291 292 293 294 295 296 297 298

Users can find more information about directories installed on the system in the [directory and files](https://docs.tdengine.com/reference/directory/) section.

Installing from source code will also configure service management for TDengine.Users can also choose to [install from packages](https://docs.tdengine.com/get-started/package/) for it.

To start the service after installation, double-click the /applications/TDengine to start the program, or in a terminal, use:

```bash
299
sudo launchctl start com.tdengine.taosd
wafwerar's avatar
wafwerar 已提交
300 301 302 303 304 305 306 307 308
```

Then users can use the TDengine CLI to connect the TDengine server. In a terminal, use:

```bash
taos
```

If TDengine CLI connects the server successfully, welcome messages and version info are printed. Otherwise, an error message is shown.
309

310 311
## Quick Run

312
If you don't want to run TDengine as a service, you can run it in current shell. For example, to quickly start a TDengine server after building, run the command below in terminal: (We take Linux as an example, command on Windows will be `taosd.exe`)
313

314 315 316 317
```bash
./build/bin/taosd -c test/cfg
```

W
update  
wenzhouwww@live.cn 已提交
318
In another terminal, use the TDengine CLI to connect the server:
319

320 321 322 323
```bash
./build/bin/taos -c test/cfg
```

324
option "-c test/cfg" specifies the system configuration file directory.
325

H
hzcheng 已提交
326
# Try TDengine
327

W
update  
wenzhouwww@live.cn 已提交
328
It is easy to run SQL commands from TDengine CLI which is the same as other SQL databases.
329

H
hzcheng 已提交
330
```sql
331 332 333 334 335 336 337 338 339 340 341
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   |
===================================
 19-07-15 00:00:00.000|         10|
 19-07-15 01:00:00.000|         20|
Query OK, 2 row(s) in set (0.001700s)
H
hzcheng 已提交
342 343 344
```

# Developing with TDengine
345 346

## Official Connectors
347

arielyangpan's avatar
arielyangpan 已提交
348
TDengine provides abundant developing tools for users to develop on TDengine. Follow the links below to find your desired connectors and relevant documentation.
H
hzcheng 已提交
349

W
wade zhang 已提交
350 351 352 353 354 355 356 357
- [Java](https://docs.tdengine.com/reference/connector/java/)
- [C/C++](https://docs.tdengine.com/reference/connector/cpp/)
- [Python](https://docs.tdengine.com/reference/connector/python/)
- [Go](https://docs.tdengine.com/reference/connector/go/)
- [Node.js](https://docs.tdengine.com/reference/connector/node/)
- [Rust](https://docs.tdengine.com/reference/connector/rust/)
- [C#](https://docs.tdengine.com/reference/connector/csharp/)
- [RESTful API](https://docs.tdengine.com/reference/rest-api/)
H
hzcheng 已提交
358

W
winshining 已提交
359
# Contribute to TDengine
H
hzcheng 已提交
360 361

Please follow the [contribution guidelines](CONTRIBUTING.md) to contribute to the project.
L
lihui 已提交
362

363
# Join the TDengine Community
L
lihui 已提交
364

365 366 367
For more information about TDengine, you can follow us on social media and join our Discord server:

- [Discord](https://discord.com/invite/VZdSuUg4pS)
368
- [Twitter](https://twitter.com/TDengineDB)
369
- [LinkedIn](https://www.linkedin.com/company/tdengine/)
370
- [YouTube](https://www.youtube.com/@tdengine)