---
toc_max_heading_level: 4
sidebar_label: Node.js
title: TDengine Node.js Connector
---

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

import Preparation from "./_preparation.mdx";
import NodeInsert from "../07-develop/03-insert-data/_js_sql.mdx";
import NodeInfluxLine from "../07-develop/03-insert-data/_js_line.mdx";
import NodeOpenTSDBTelnet from "../07-develop/03-insert-data/_js_opts_telnet.mdx";
import NodeOpenTSDBJson from "../07-develop/03-insert-data/_js_opts_json.mdx";
import NodeQuery from "../07-develop/04-query-data/_js.mdx";

`@tdengine/client` 和 `@tdengine/rest` 是 TDengine 的官方 Node.js 语言连接器。 Node.js 开发人员可以通过它开发可以存取 TDengine 集群数据的应用软件。注意：从 TDengine 3.0 开始 Node.js 原生连接器的包名由 `td2.0-connector` 改名为 `@tdengine/client` 而 rest 连接器的包名由 `td2.0-rest-connector` 改为 `@tdengine/rest`。并且不与 TDengine 2.x 兼容。

`@tdengine/client` 是**原生连接器**，它通过 TDengine 客户端驱动程序（taosc）连接 TDengine 运行实例，支持数据写入、查询、订阅、schemaless 接口和参数绑定接口等功能。`@tdengine/rest` 是 **REST 连接器**，它通过 taosAdapter 提供的 REST 接口连接 TDengine 的运行实例。REST 连接器可以在任何平台运行，但性能略为下降，接口实现的功能特性集合和原生接口有少量不同。

Node.js 连接器源码托管在 [GitHub](https://github.com/taosdata/taos-connector-node/tree/3.0)。

## 支持的平台

原生连接器支持的平台和 TDengine 客户端驱动支持的平台一致。
REST 连接器支持所有能运行 Node.js 的平台。

## 版本支持

请参考[版本支持列表](../#版本支持)

## 支持的功能特性

<Tabs defaultValue="native">
<TabItem value="native" label="原生连接器">

1. 连接管理
2. 普通查询
3. 连续查询
4. 参数绑定
5. 订阅功能
6. Schemaless

</TabItem>
<TabItem value="rest" label="REST 连接器">

1. 连接管理
2. 普通查询
3. 连续查询

</TabItem>
</Tabs>


## 安装步骤

### 安装前准备

- 安装 Node.js 开发环境
- 如果使用 REST 连接器，跳过此步。但如果使用原生连接器，请安装 TDengine 客户端驱动，具体步骤请参考[安装客户端驱动](../#安装客户端驱动)。我们使用 [node-gyp](https://github.com/nodejs/node-gyp) 和 TDengine 实例进行交互，还需要根据具体操作系统来安装下文提到的一些依赖工具。

<Tabs defaultValue="Linux">
<TabItem value="Linux" label="Linux 系统安装依赖工具">

- `python` (建议`v2.7` , `v3.x.x` 目前还不支持)
- `@tdengine/client` 3.0.0 支持 Node.js LTS v10.9.0 或更高版本, Node.js LTS v12.8.0 或更高版本；其他版本可能存在包兼容性的问题
- `make`
- C 语言编译器，[GCC](https://gcc.gnu.org) v4.8.5 或更高版本

</TabItem>

<TabItem value="macOS" label="macOS 系统安装依赖工具">

- `python` (建议`v2.7` , `v3.x.x` 目前还不支持)
- `@tdengine/client` 3.0.0 目前是只支持 Node.js v12.22.12 或 v12 的更高版本；其他版本可能存在包兼容性的问题
- `make`
- C 语言编译器，[GCC](https://gcc.gnu.org) v4.8.5 或更高版本

</TabItem>

<TabItem value="Windows" label="Windows 系统安装依赖工具">

- 安装方法 1

使用微软的[ windows-build-tools ](https://github.com/felixrieseberg/windows-build-tools)在`cmd` 命令行界面执行`npm install --global --production windows-build-tools` 即可安装所有的必备工具。

- 安装方法 2

手动安装以下工具：

- 安装 Visual Studio 相关：[Visual Studio Build 工具](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=BuildTools) 或者 [Visual Studio 2017 Community](https://visualstudio.microsoft.com/pl/thank-you-downloading-visual-studio/?sku=Community)
- 安装 [Python](https://www.python.org/downloads/) 2.7(`v3.x.x` 暂不支持) 并执行 `npm config set python python2.7`
- 进入`cmd`命令行界面，`npm config set msvs_version 2017`

参考微软的 Node.js 用户手册[ Microsoft's Node.js Guidelines for Windows](https://github.com/Microsoft/nodejs-guidelines/blob/master/windows-environment.md#compiling-native-addon-modules)。

如果在 Windows 10 ARM 上使用 ARM64 Node.js，还需添加 "Visual C++ compilers and libraries for ARM64" 和 "Visual C++ ATL for ARM64"。

</TabItem>
</Tabs>

### 使用 npm 安装

<Tabs defaultValue="install_rest">
<TabItem value="install_native" label="安装原生连接器">

```bash
npm install @tdengine/client
```

</TabItem>
<TabItem value="install_rest" label="安装 REST 连接器">

```bash
npm install @tdengine/rest
```

</TabItem>
</Tabs>

### 安装验证

<Tabs defaultValue="native">
<TabItem value="native" label="原生连接器">

在安装好 TDengine 客户端后，使用 nodejsChecker.js 程序能够验证当前环境是否支持 Node.js 方式访问 TDengine。

验证方法：

- 新建安装验证目录，例如：`~/tdengine-test`，下载 GitHub 上 [nodejsChecker.js 源代码](https://github.com/taosdata/taos-connector-node/blob/3.0/nodejs/examples/nodejsChecker.js)到本地。

- 在命令行中执行以下命令。

```bash
npm init -y
npm install @tdengine/client
node nodejsChecker.js host=localhost
```

- 执行以上步骤后，在命令行会输出 nodejsChecker.js 连接 TDengine 实例，并执行简单插入和查询的结果。

</TabItem>
<TabItem value="rest" label="REST 连接器">

在安装好 TDengine 客户端后，使用 nodejsChecker.js 程序能够验证当前环境是否支持 Node.js 方式访问 TDengine。

验证方法：

- 新建安装验证目录，例如：`~/tdengine-test`，下载 GitHub 上 [restChecker.js 源代码](https://github.com/taosdata/TDengine/tree/3.0/docs/examples/node/restexample/restChecker.js)到本地。

- 在命令行中执行以下命令。

```bash
npm init -y
npm install @tdengine/rest
node restChecker.js
```

- 执行以上步骤后，在命令行会输出 restChecker.js 连接 TDengine 实例，并执行简单插入和查询的结果。

</TabItem>
</Tabs>



## 建立连接

请选择使用一种连接器。

<Tabs defaultValue="native">
<TabItem value="native" label="原生连接">

安装并引用 `@tdengine/client` 包。

```javascript
//A cursor also needs to be initialized in order to interact with TDengine from Node.js.
const taos = require("@tdengine/client");
var conn = taos.connect({
  host: "127.0.0.1",
  user: "root",
  password: "taosdata",
  config: "/etc/taos",
  port: 0,
});
var cursor = conn.cursor(); // Initializing a new cursor

//Close a connection
conn.close();
```

</TabItem>
<TabItem value="rest" label="REST 连接">

安装并引用 `@tdengine/rest` 包。

```javascript
//A cursor also needs to be initialized in order to interact with TDengine from Node.js.
import { options, connect } from "@tdengine/rest";
options.path = "/rest/sql";
// set host
options.host = "localhost";
// set other options like user/passwd

let conn = connect(options);
let cursor = conn.cursor();
```

</TabItem>
</Tabs>

## 使用示例

### 写入数据

#### SQL 写入

<Tabs defaultValue="native">
<TabItem value="native" label="原生连接">

<NodeInsert />

</TabItem>
<TabItem value="rest" label="REST 连接">

```js
{{#include docs/examples/node/restexample/insert_example.js}}
```

</TabItem>
</Tabs>



#### InfluxDB 行协议写入

<Tabs defaultValue="native">
<TabItem value="native" label="原生连接">

<NodeInfluxLine />

</TabItem>
</Tabs>

#### OpenTSDB Telnet 行协议写入

<Tabs defaultValue="native">
<TabItem value="native" label="原生连接">

<NodeOpenTSDBTelnet />

</TabItem>
</Tabs>

#### OpenTSDB JSON 行协议写入

<Tabs defaultValue="native">
<TabItem value="native" label="原生连接">

<NodeOpenTSDBJson />

</TabItem>
</Tabs>

### 查询数据

<Tabs defaultValue="native">
<TabItem value="native" label="原生连接">

<NodeQuery />

</TabItem>

<TabItem value="rest" label="REST 连接">

```js
{{#include docs/examples/node/restexample/query_example.js}}
```

</TabItem>
</Tabs>


## 更多示例程序

| 示例程序                                                                                                                                   | 示例程序描述                           |
| ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------- |
| [basicUse](https://github.com/taosdata/taos-connector-node/blob/3.0/nodejs/examples/queryExample.js)                                  | 基本的使用如如建立连接，执行 SQL 等操作。                       |
| [stmtBindBatch](https://github.com/taosdata/taos-connector-node/blob/3.0/nodejs/examples/bindParamBatch.js)                  | 绑定多行参数插入的示例。               | |
| [stmtBindSingleParamBatch](https://github.com/taosdata/taos-connector-node/blob/3.0/nodejs/examples/bindSingleParamBatch.js) | 按列绑定参数插入的示例。               |
| [stmtQuery](https://github.com/taosdata/taos-connector-node/blob/3.0/nodejs/examples/stmtQuery.js)                       | 绑定参数查询的示例。                   |
| [schemless insert](https://github.com/taosdata/taos-connector-node/blob/3.0/nodejs/examples/schemaless.js)                   | schemless 插入的示例。                 |
| [TMQ](https://github.com/taosdata/taos-connector-node/blob/3.0/nodejs/examples/tmq.js)                                 | 订阅的使用示例。                       |
| [asyncQuery](https://github.com/taosdata/taos-connector-node/blob/3.0/nodejs/examples/asyncQueryExample.js)                                         | 异步查询的使用示例。                   |
| [REST](https://github.com/taosdata/taos-connector-node/blob/3.0/typescript-rest/example/example.ts)                                    | 使用 REST 连接的 TypeScript 使用示例。 |

## 使用限制

native 连接器（`@tdengine/client`） >= v3.0.0 目前支持 node 的版本为：支持 >=v12.8.0 <= v12.9.1 || >=v10.20.0 <= v10.9.0 ；2.0.5 及更早版本支持 v10.x 版本，其他版本可能存在包兼容性的问题。

## 其他说明

Node.js 连接器的使用参见[视频教程](https://www.taosdata.com/blog/2020/11/11/1957.html)。

## 常见问题

1. 使用 REST 连接需要启动 taosadapter。

   ```bash
   sudo systemctl start taosadapter
   ```

2. Node.js 版本

   原生连接器 `@tdengine/client` 目前兼容的 Node.js 版本为：>=v10.20.0 <= v10.9.0 || >=v12.8.0 <= v12.9.1

3. "Unable to establish connection"，"Unable to resolve FQDN"

  一般都是因为配置 FQDN 不正确。 可以参考[如何彻底搞懂 TDengine 的 FQDN](https://www.taosdata.com/blog/2021/07/29/2741.html) 。

## 重要更新记录

### 原生连接器

| package name     | version | TDengine version    | 说明                                                             |
|------------------|---------|---------------------|------------------------------------------------------------------|
| @tdengine/client | 3.0.0   | 3.0.0               | 支持TDengine 3.0 且不与2.x 兼容。                                                          |
| td2.0-connector  | 2.0.12  | 2.4.x；2.5.x；2.6.x | 修复 cursor.close() 报错的 bug。                                 |
| td2.0-connector  | 2.0.11  | 2.4.x；2.5.x；2.6.x | 支持绑定参数、json tag、schemaless 接口等功能。                  |
| td2.0-connector  | 2.0.10  | 2.4.x；2.5.x；2.6.x | 支持连接管理，普通查询、连续查询、获取系统信息、订阅功能等功能。 |
### REST 连接器

| package name         | version | TDengine version    | 说明                                                                      |
|----------------------|---------|---------------------|---------------------------------------------------------------------------|
| @tdengine/rest       | 3.0.0   | 3.0.0               | 支持 TDegnine 3.0，且不与2.x 兼容。                                               |
| td2.0-rest-connector | 1.0.7   | 2.4.x；2.5.x；2.6.x | 移除默认端口 6041。                                                       |
| td2.0-rest-connector | 1.0.6   | 2.4.x；2.5.x；2.6.x | 修复create，insert，update，alter 等SQL 执行返回的 affectRows 错误的bug。 |
| td2.0-rest-connector | 1.0.5   | 2.4.x；2.5.x；2.6.x | 支持云服务 cloud Token；                                                  |
| td2.0-rest-connector | 1.0.3   | 2.4.x；2.5.x；2.6.x | 支持连接管理、普通查询、获取系统信息、错误信息、连续查询等功能。          |

## API 参考

[API 参考](https://docs.taosdata.com/api/td2.0-connector/)