252 lines
11 KiB
Plaintext
252 lines
11 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 Preparition 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` and `@tdengine/rest` are the official Node.js connectors. Node.js developers can develop applications to access TDengine instance data. Note: The connectors for TDengine 3.0 are different than those for TDengine 2.x. The new connectors do not support TDengine 2.x.
|
||
|
||
`@tdengine/client` is **native connection**, which connects to TDengine instances natively through the TDengine client driver (taosc), supporting data writing, querying, subscriptions, schemaless writing, and bind interface. `@tdengine/rest` is the **REST connection**, which connects to TDengine instances via the REST interface provided by taosAdapter. The REST connector can run on any platform, but performance is slightly degraded, and the interface implements a somewhat different set of functional features than the native interface.
|
||
|
||
The source code for the Node.js connectors is located on [GitHub](https://github.com/taosdata/taos-connector-node/tree/3.0).
|
||
|
||
## Supported platforms
|
||
|
||
The platforms supported by the native connector are the same as those supported by the TDengine client driver.
|
||
The REST connector supports all platforms that can run Node.js.
|
||
|
||
## Version support
|
||
|
||
Please refer to [version support list](/reference/connector#version-support)
|
||
|
||
## Supported features
|
||
|
||
### Native connectors
|
||
|
||
1. Connection Management
|
||
2. General Query
|
||
3. Continuous Query
|
||
4. Parameter Binding
|
||
5. Subscription
|
||
6. Schemaless
|
||
|
||
### REST Connector
|
||
|
||
1. Connection Management
|
||
2. General Query
|
||
3. Continuous Query
|
||
|
||
## Installation Steps
|
||
|
||
### Pre-installation preparation
|
||
|
||
- Install the Node.js development environment
|
||
- If you are using the REST connector, skip this step. However, if you use the native connector, please install the TDengine client driver. Please refer to [Install Client Driver](/reference/connector#Install-Client-Driver) for more details. We use [node-gyp](https://github.com/nodejs/node-gyp) to interact with TDengine instances and also need to install some dependencies mentioned below depending on the specific OS.
|
||
|
||
<Tabs defaultValue="Linux">
|
||
<TabItem value="Linux" label="Linux system installation dependencies">
|
||
|
||
- `python` (recommended for `v2.7` , `v3.x.x` currently not supported)
|
||
- `@tdengine/client` 3.0.0 supports Node.js LTS v10.9.0 or later and Node.js LTS v12.8.0 or later. Older versions may be incompatible.
|
||
- `make`
|
||
- C compiler, [GCC](https://gcc.gnu.org) v4.8.5 or higher
|
||
|
||
</TabItem>
|
||
<TabItem value="Windows" label="Windows system installation dependencies">
|
||
|
||
- Installation method 1
|
||
|
||
Use Microsoft's [windows-build-tools](https://github.com/felixrieseberg/windows-build-tools) to execute `npm install --global --production` from the `cmd` command-line interface to install all the necessary tools.
|
||
|
||
- Installation method 2
|
||
|
||
Manually install the following tools.
|
||
|
||
- Install Visual Studio related: [Visual Studio Build Tools](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=BuildTools) or [Visual Studio 2017 Community](https://visualstudio.microsoft.com/pl/thank-you-downloading-visual-studio/?sku=Community)
|
||
- Install [Python](https://www.python.org/downloads/) 2.7 (`v3.x.x` is not supported) and execute `npm config set python python2.7`.
|
||
- Go to the `cmd` command-line interface, `npm config set msvs_version 2017`
|
||
|
||
Refer to Microsoft's Node.js User Manual [Microsoft's Node.js Guidelines for Windows](https://github.com/Microsoft/nodejs-guidelines/blob/master/windows-environment.md#compiling-native-addon-modules).
|
||
|
||
If using ARM64 Node.js on Windows 10 ARM, you must add "Visual C++ compilers and libraries for ARM64" and "Visual C++ ATL for ARM64".
|
||
|
||
</TabItem>
|
||
</Tabs>
|
||
|
||
### Install via npm
|
||
|
||
<Tabs defaultValue="install_rest">
|
||
<TabItem value="install_native" label="Install native connector">
|
||
|
||
```bash
|
||
npm install @tdengine/client
|
||
```
|
||
|
||
</TabItem>
|
||
<TabItem value="install_rest" label="Install REST connector">
|
||
|
||
```bash
|
||
npm install @tdengine/rest
|
||
```
|
||
|
||
</TabItem>
|
||
</Tabs>
|
||
|
||
### Verify
|
||
|
||
After installing the TDengine client, use the `nodejsChecker.js` program to verify that the current environment supports Node.js access to TDengine.
|
||
|
||
Verification in details:
|
||
|
||
- Create an installation test folder such as `~/tdengine-test`. Download the [nodejsChecker.js source code](https://github.com/taosdata/taos-connector-node/blob/3.0/nodejs/examples/nodejsChecker.js) to your local machine.
|
||
|
||
- Execute the following command from the command-line.
|
||
|
||
```bash
|
||
npm init -y
|
||
npm install @tdengine/client
|
||
node nodejsChecker.js host=localhost
|
||
```
|
||
|
||
- After executing the above steps, the command-line will output the result of `nodejsChecker.js` connecting to the TDengine instance and performing a simple insert and query.
|
||
|
||
## Establishing a connection
|
||
|
||
Please choose to use one of the connectors.
|
||
|
||
<Tabs defaultValue="rest">
|
||
<TabItem value="native" label="native connection">
|
||
|
||
Install and import the `@tdengine/client` package.
|
||
|
||
```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 connection">
|
||
|
||
Install and import the `@tdengine/rest` package.
|
||
|
||
```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>
|
||
|
||
## Usage examples
|
||
|
||
### Write data
|
||
|
||
#### SQL Write
|
||
|
||
<NodeInsert />
|
||
|
||
#### InfluxDB line protocol write
|
||
|
||
<NodeInfluxLine />
|
||
|
||
#### OpenTSDB Telnet line protocol write
|
||
|
||
<NodeOpenTSDBTelnet />
|
||
|
||
#### OpenTSDB JSON line protocol write
|
||
|
||
<NodeOpenTSDBJson />
|
||
|
||
### Querying data
|
||
|
||
<NodeQuery />
|
||
|
||
|
||
## More sample programs
|
||
|
||
| Sample Programs | Sample Program Description |
|
||
| --------------------------------------------------------------------------------------------------------------------------------- --------- | -------------------------------------- |
|
||
| [basicUse](https://github.com/taosdata/taos-connector-node/blob/3.0/nodejs/examples/queryExample.js) | Basic operations such as establishing connections and running SQl commands. |
|
||
| [stmtBindBatch](https://github.com/taosdata/taos-connector-node/blob/3.0/nodejs/examples/bindParamBatch.js) | Binding multi-line parameter insertion. | |
|
||
| [stmtBindSingleParamBatch](https://github.com/taosdata/taos-connector-node/blob/3.0/nodejs/examples/bindSingleParamBatch.js) | Columnar binding parameter insertion |
|
||
| [stmtQuery](https://github.com/taosdata/taos-connector-node/blob/3.0/nodejs/examples/stmtQuery.js) | Binding parameter query |
|
||
| [schemless insert](https://github.com/taosdata/taos-connector-node/blob/3.0/nodejs/examples/schemaless.js) | Schemaless insert |
|
||
| [TMQ](https://github.com/taosdata/taos-connector-node/blob/3.0/nodejs/examples/tmq.js) | Using data subscription |
|
||
| [asyncQuery](https://github.com/taosdata/taos-connector-node/blob/3.0/nodejs/examples/asyncQueryExample.js) | Using asynchronous queries |
|
||
| [REST](https://github.com/taosdata/taos-connector-node/blob/3.0/typescript-rest/example/example.ts) | Using TypeScript with the REST connector |
|
||
|
||
## Usage limitations
|
||
|
||
`@tdengine/client` 3.0.0 supports Node.js LTS v12.8.0 to 12.9.1 and 10.9.0 to 10.20.0.
|
||
|
||
|
||
|
||
|
||
|
||
## Frequently Asked Questions
|
||
|
||
1. Using REST connections requires starting taosadapter.
|
||
|
||
```bash
|
||
sudo systemctl start taosadapter
|
||
```
|
||
|
||
2. Node.js versions
|
||
|
||
`@tdengine/client` supports Node.js v10.9.0 to 10.20.0 and 12.8.0 to 12.9.1.
|
||
|
||
3. "Unable to establish connection", "Unable to resolve FQDN"
|
||
|
||
Usually, the root cause is an incorrect FQDN configuration. You can refer to this section in the [FAQ](https://docs.tdengine.com/2.4/train-faq/faq/#2-how-to-handle-unable-to-establish-connection) to troubleshoot.
|
||
|
||
## Important update records
|
||
|
||
### Native connectors
|
||
|
||
| package name | version | TDengine version | Description |
|
||
|------------------|---------|---------------------|------------------------------------------------------------------|
|
||
| @tdengine/client | 3.0.0 | 3.0.0 | Supports TDengine 3.0. Not compatible with TDengine 2.x. |
|
||
| td2.0-connector | 2.0.12 | 2.4.x；2.5.x；2.6.x | Fixed cursor.close() bug. |
|
||
| td2.0-connector | 2.0.11 | 2.4.x；2.5.x；2.6.x | Supports parameter binding, JSON tags and schemaless interface |
|
||
| td2.0-connector | 2.0.10 | 2.4.x；2.5.x；2.6.x | Supports connection management, standard queries, connection queries, system information, and data subscription |
|
||
### REST Connector
|
||
|
||
| package name | version | TDengine version | Description |
|
||
|----------------------|---------|---------------------|---------------------------------------------------------------------------|
|
||
| @tdengine/rest | 3.0.0 | 3.0.0 | Supports TDengine 3.0. Not compatible with TDengine 2.x. |
|
||
| td2.0-rest-connector | 1.0.7 | 2.4.x；2.5.x；2.6.x | Removed default port 6041。 |
|
||
| td2.0-rest-connector | 1.0.6 | 2.4.x；2.5.x；2.6.x | Fixed affectRows bug with create, insert, update, and alter. |
|
||
| td2.0-rest-connector | 1.0.5 | 2.4.x；2.5.x；2.6.x | Support cloud token |
|
||
| td2.0-rest-connector | 1.0.3 | 2.4.x；2.5.x；2.6.x | Supports connection management, standard queries, system information, error information, and continuous queries |
|
||
|
||
## API Reference
|
||
|
||
[API Reference](https://docs.taosdata.com/api/td2.0-connector/) |