334 lines
13 KiB
Plaintext
334 lines
13 KiB
Plaintext
---
|
||
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 RequestId from "./_request_id.mdx";
|
||
|
||
`@tdengine/websocket` 是 TDengine 的官方 Node.js 语言连接器。Node.js 开发人员可以通过它开发存取 TDengine 数据库的的应用软件。
|
||
|
||
Node.js 连接器源码托管在 [GitHub](https://github.com/taosdata/taos-connector-node/tree/main)。
|
||
|
||
## 连接方式
|
||
|
||
Node.js 连接器目前仅支持 Websocket 连接器， 其通过 taosAdapter 提供的 Websocket 接口连接 TDengine 实例。
|
||
|
||
连接方式的详细介绍请参考：[连接器建立连接的方式](../../develop/connect/#连接器建立连接的方式)
|
||
|
||
## 支持的平台
|
||
|
||
支持 Node.js 14及以上版本。
|
||
|
||
## 版本历史
|
||
|
||
| Node.js 连接器 版本 | 主要变化 | TDengine 版本 |
|
||
| :------------------: | :----------------------: | :----------------: |
|
||
| 3.1.0 | 新版本发布，支持 WebSocket 连接 | 3.2.0.0 及更高版本 |
|
||
|
||
## 支持的功能特性
|
||
|
||
- 连接管理
|
||
- SQL写入
|
||
- SQL查询
|
||
- 参数绑定
|
||
- 数据订阅
|
||
- 无模式写入
|
||
|
||
## 处理异常
|
||
|
||
在调用连接器 api 报错后，通过 try catch 可以获取到错误的信息和错误码。
|
||
|
||
错误说明：Node.js 连接器错误码在 100 到 110 之间，之外的错误为 TDengine 其他功能模块的报错。
|
||
|
||
具体的连接器错误码请参考：
|
||
|
||
| Error Code | Description | Suggested Actions |
|
||
| ---------- | -------------------------------------------------------------| ----------------------------------------------------------------------------------------- |
|
||
| 100 | invalid variables | 参数不合法，请检查相应接口规范，调整参数类型及大小。 |
|
||
| 101 | invalid url | url 错误，请检查 url 是否填写正确。 |
|
||
| 102 | received server data but did not find a callback for processing | 接收到服务端数据但没有找到上层回调 |
|
||
| 103 | invalid message type | 接收到的消息类型无法识别，请检查服务端是否正常。 |
|
||
| 104 | connection creation failed | 连接创建失败，请检查网络是否正常。 |
|
||
| 105 | websocket request timeout | 请求超时 |
|
||
| 106 | authentication fail | 认证失败，请检查用户名，密码是否正确。 |
|
||
| 107 | unknown sql type in tdengine | 请检查 TDengine 支持的 Data Type 类型。 |
|
||
| 108 | connection has been closed | 连接已经关闭，请检查 Connection 是否关闭后再次使用，或是连接是否正常。 |
|
||
| 109 | fetch block data parse fail | 获取到的查询数据，解析失败 |
|
||
| 110 | websocket connection has reached its maximum limit | Websocket 连接达到上限 |
|
||
|
||
## 类型映射
|
||
|
||
下表为 TDengine DataType 和 Node.js DataType 之间的映射关系
|
||
|
||
| TDengine DataType | Node.js DataType|
|
||
|-------------------|-------------|
|
||
| TIMESTAMP | bigint |
|
||
| TINYINT | number |
|
||
| SMALLINT | number |
|
||
| INT | number |
|
||
| BIGINT | bigint |
|
||
| TINYINT UNSIGNED | number |
|
||
| SMALLINT UNSIGNED | number |
|
||
| INT UNSIGNED | number |
|
||
| BIGINT UNSIGNED | bigint |
|
||
| FLOAT | number |
|
||
| DOUBLE | number |
|
||
| BOOL | boolean |
|
||
| BINARY | string |
|
||
| NCHAR | string |
|
||
| JSON | string |
|
||
| VARBINARY | ArrayBuffer |
|
||
| GEOMETRY | ArrayBuffer |
|
||
|
||
**注意**：JSON 类型仅在 tag 中支持。
|
||
|
||
## 安装步骤
|
||
|
||
### 安装前准备
|
||
|
||
- 安装 Node.js 开发环境, 使用14以上版本。下载链接： https://nodejs.org/en/download/
|
||
|
||
### 使用 npm 安装 Node.js 连接器
|
||
|
||
```bash
|
||
npm install @tdengine/websocket
|
||
```
|
||
|
||
### 安装验证
|
||
|
||
验证方法：
|
||
|
||
- 新建安装验证目录，例如：`~/tdengine-test`，下载 GitHub 上 [nodejsChecker.js 源代码](https://github.com/taosdata/TDengine/tree/main/docs/examples/node/websocketexample/nodejsChecker.js)到本地。
|
||
|
||
- 在命令行中执行以下命令。
|
||
|
||
```bash
|
||
npm init -y
|
||
npm install @tdengine/websocket
|
||
node nodejsChecker.js
|
||
```
|
||
|
||
- 执行以上步骤后，在命令行会输出 nodeChecker.js 连接 TDengine 实例，并执行简单插入和查询的结果。
|
||
|
||
## 建立连接
|
||
|
||
安装并引用 `@tdengine/websocket` 包。
|
||
|
||
**注意**：
|
||
- 链接器使用结束后，需要调用 taos.destroy() 释放连接器资源
|
||
```javascript
|
||
const taos = require("@tdengine/websocket");
|
||
|
||
//数据库操作......
|
||
|
||
taos.destroy();
|
||
```
|
||
|
||
```javascript
|
||
WSConfig配置Websocket参数如下:
|
||
getToken(): string | undefined | null;
|
||
setToken(token: string): void;
|
||
getUser(): string | undefined | null;
|
||
setUser(user: string): void;
|
||
getPwd(): string | undefined | null;
|
||
setPwd(pws: string): void;
|
||
getDb(): string | undefined | null;
|
||
setDb(db: string): void;
|
||
getUrl(): string;
|
||
setUrl(url: string): void;
|
||
setTimeOut(ms: number): void;
|
||
getTimeOut(): number | undefined | null;
|
||
```
|
||
|
||
```javascript
|
||
{{#include docs/examples/node/websocketexample/sql_example.js:createConnect}}
|
||
```
|
||
|
||
## 使用示例
|
||
|
||
### 创建数据库和表
|
||
|
||
```javascript
|
||
{{#include docs/examples/node/websocketexample/sql_example.js:create_db_and_table}}
|
||
```
|
||
> **注意**：如果不使用 `USE power` 指定数据库，则后续对表的操作都需要增加数据库名称作为前缀，如 power.meters。
|
||
|
||
### 插入数据
|
||
|
||
```javascript
|
||
{{#include docs/examples/node/websocketexample/sql_example.js:insertData}}
|
||
```
|
||
|
||
> NOW 为系统内部函数，默认为客户端所在计算机当前时间。
|
||
> `NOW + 1s` 代表客户端当前时间往后加 1 秒，数字后面代表时间单位：a(毫秒)，s(秒)，m(分)，h(小时)，d(天)，w(周)，n(月)，y(年)。
|
||
|
||
### 查询数据
|
||
|
||
```javascript
|
||
{{#include docs/examples/node/websocketexample/sql_example.js:queryData}}
|
||
```
|
||
|
||
> 查询到的数据
|
||
|
||
```javascript
|
||
wsRow:meta:=> [
|
||
{ name: 'ts', type: 'TIMESTAMP', length: 8 },
|
||
{ name: 'current', type: 'FLOAT', length: 4 },
|
||
{ name: 'voltage', type: 'INT', length: 4 },
|
||
{ name: 'phase', type: 'FLOAT', length: 4 },
|
||
{ name: 'location', type: 'VARCHAR', length: 64},
|
||
{ name: 'groupid', type: 'INT', length: 4 }
|
||
]
|
||
wsRow:data:=> [
|
||
[ 1714013737536n, 12.3, 221, 0.31, 'California.SanFrancisco', 3 ]
|
||
]
|
||
```
|
||
|
||
### 执行带有 reqId 的 SQL
|
||
|
||
<RequestId />
|
||
|
||
```javascript
|
||
{{#include docs/examples/node/websocketexample/sql_example.js:sqlWithReqid}}
|
||
```
|
||
|
||
### 通过参数绑定写入数据
|
||
|
||
TDengine 的 NodeJs 连接器支持参数绑定风格的 Prepare API 方式写入数据，和大多数数据库类似，目前仅支持用 ? 来代表待绑定的参数。采用这种方式写入数据时，能避免 SQL 语法解析的资源消耗，从而在很多情况下显著提升写入性能。
|
||
|
||
**注意**：
|
||
- 预处理语句中指定数据库与子表名称不要使用 `db.?`，应直接使用 `?`，然后在 setTableName 中指定数据库，如：`stmt.setTableName("db.t1")`。
|
||
|
||
示例代码：
|
||
```javascript
|
||
{{#include docs/examples/node/websocketexample/stmt_example.js}}
|
||
```
|
||
|
||
用于设定 TAG/VALUES 数据列的取值的方法总共有：
|
||
|
||
```javascript
|
||
setBoolean(params: any[]): void;
|
||
setTinyInt(params: any[]): void;
|
||
setUTinyInt(params: any[]): void;
|
||
setSmallInt(params: any[]): void;
|
||
setUSmallInt(params: any[]): void;
|
||
setInt(params: any[]): void;
|
||
setUInt(params: any[]): void;
|
||
setBigint(params: any[]): void;
|
||
setUBigint(params: any[]): void;
|
||
setFloat(params: any[]): void;
|
||
setDouble(params: any[]): void;
|
||
setVarchar(params: any[]): void;
|
||
setBinary(params: any[]): void;
|
||
setNchar(params: any[]): void;
|
||
setJson(params: any[]): void;
|
||
setVarBinary(params: any[]): void;
|
||
setGeometry(params: any[]): void;
|
||
setTimestamp(params: any[]): void;
|
||
```
|
||
|
||
**注意**：JSON 类型仅在 tag 中支持。
|
||
|
||
### 无模式写入
|
||
|
||
TDengine 支持无模式写入功能。无模式写入兼容 InfluxDB 的 行协议（Line Protocol）、OpenTSDB 的 telnet 行协议和 OpenTSDB 的 JSON 格式协议。详情请参见[无模式写入](../../reference/schemaless/)。
|
||
|
||
```javascript
|
||
{{#include docs/examples/node/websocketexample/line_example.js}}
|
||
```
|
||
|
||
### 执行带有 reqId 的无模式写入
|
||
|
||
此 reqId 可用于请求链路追踪。
|
||
|
||
```javascript
|
||
await wsSchemaless.schemalessInsert([influxdbData], SchemalessProto.InfluxDBLineProtocol, Precision.NANO_SECONDS, ttl, reqId);
|
||
await wsSchemaless.schemalessInsert([telnetData], SchemalessProto.OpenTSDBTelnetLineProtocol, Precision.NANO_SECONDS, ttl, reqId);
|
||
await wsSchemaless.schemalessInsert([jsonData], SchemalessProto.OpenTSDBJsonFormatProtocol, Precision.NANO_SECONDS, ttl, reqId);
|
||
```
|
||
|
||
### 数据订阅
|
||
|
||
TDengine NodeJs 连接器支持订阅功能，应用 API 如下：
|
||
|
||
#### 创建 Topic
|
||
```javascript
|
||
{{#include docs/examples/node/websocketexample/tmq_example.js:create_topic}}
|
||
```
|
||
|
||
#### 创建 Consumer
|
||
|
||
```javascript
|
||
{{#include docs/examples/node/websocketexample/tmq_example.js:create_consumer}}
|
||
```
|
||
> 参数说明
|
||
- taos.TMQConstants.CONNECT_USER: 用户名。
|
||
- taos.TMQConstants.CONNECT_PASS: 密码。
|
||
- taos.TMQConstants.GROUP_ID: 所在的 group。
|
||
- taos.TMQConstants.CLIENT_ID: client id。
|
||
- taos.TMQConstants.WS_URL: taosAdapter 的url地址。
|
||
- taos.TMQConstants.AUTO_OFFSET_RESET: 来确定消费位置为最新数据（latest）还是包含旧数据（earliest）。
|
||
- taos.TMQConstants.ENABLE_AUTO_COMMIT: 是否允许自动提交。
|
||
- taos.TMQConstants.AUTO_COMMIT_INTERVAL_MS: 自动提交间隔。
|
||
- taos.TMQConstants.CONNECT_MESSAGE_TIMEOUT: 数据传输超时参数，单位 ms，默认为 10000 ms。
|
||
|
||
其他参数请参考：[Consumer 参数列表](../../develop/tmq/#数据订阅相关参数)， 注意 TDengine 服务端自3.2.0.0版本开始消息订阅中的 auto.offset.reset 默认值发生变化。
|
||
|
||
#### 订阅消费数据
|
||
```javascript
|
||
{{#include docs/examples/node/websocketexample/tmq_example.js:subscribe}}
|
||
```
|
||
|
||
#### 指定订阅 Offset
|
||
|
||
```javascript
|
||
{{#include docs/examples/node/websocketexample/tmq_example.js:assignment}}
|
||
```
|
||
|
||
#### 关闭订阅
|
||
```javascript
|
||
// 取消订阅
|
||
consumer.unsubscribe();
|
||
// 关闭消费
|
||
consumer.close()
|
||
// 释放连接器资源
|
||
taos.destroy();
|
||
```
|
||
|
||
详情请参考：[数据订阅](../../develop/tmq)
|
||
|
||
#### 完整示例
|
||
|
||
```javascript
|
||
{{#include docs/examples/node/websocketexample/tmq_example.js}}
|
||
```
|
||
|
||
## 更多示例程序
|
||
|
||
| 示例程序 | 示例程序描述 |
|
||
| ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------- |
|
||
| [sql_example](https://github.com/taosdata/TDengine/tree/main/docs/examples/node/websocketexample/sql_example.js) | 基本的使用如如建立连接，执行 SQL 等操作。 |
|
||
| [stmt_example](https://github.com/taosdata/TDengine/tree/main/docs/examples/node/websocketexample/stmt_example.js) | 绑定参数插入的示例。 | |
|
||
| [line_example](https://github.com/taosdata/TDengine/tree/main/docs/examples/node/websocketexample/line_example.js) | 行协议写入示例。 |
|
||
| [telnet_line_example](https://github.com/taosdata/TDengine/tree/main/docs/examples/node/websocketexample/telnet_line_example.js) | OpenTSDB Telnet 行协议写入示例。 |
|
||
| [json_line_example](https://github.com/taosdata/TDengine/tree/main/docs/examples/node/websocketexample/json_line_example.js) | OpenTSDB JSON 行协议写入示例。 |
|
||
| [tmq_example](https://github.com/taosdata/TDengine/tree/main/docs/examples/node/websocketexample/tmq_example.js) | 订阅的使用示例。 |
|
||
|
||
## 使用限制
|
||
|
||
- Node.js 连接器（`@tdengine/websocket`）支持 Node.js 14 以上版本，低于 14 的版本可能存在包兼容性的问题。
|
||
- 目前只支持 WebSocket 连接，需要提前启动 taosAdapter
|
||
- 使用连接器结束后，需要调用 taos.connectorDestroy(); 释放连接器资源。
|
||
|
||
|
||
## 常见问题
|
||
|
||
1. "Unable to establish connection" 或 "Unable to resolve FQDN"
|
||
|
||
**原因**：一般都是因为配置 FQDN 不正确。 可以参考[如何彻底搞懂 TDengine 的 FQDN](https://www.taosdata.com/blog/2021/07/29/2741.html) 。
|
||
|
||
|