From fc556d837ce8a39d6fdadd121a1570ff7d817f13 Mon Sep 17 00:00:00 2001 From: Shuduo Sang Date: Sat, 23 Apr 2022 21:33:37 +0800 Subject: [PATCH] docs: connector refine (#11780) * docs: refine connector doc [TD-14839] * docs: use TDengine CLI [TD-14839] * docs: replace JNI with navtive connection [TD-14839] * docs: make connectors doc use same preparition [TD-14839] --- .../03-connector/_preparition.mdx | 8 +++++ docs-cn/14-reference/03-connector/cpp.mdx | 2 -- docs-cn/14-reference/03-connector/csharp.mdx | 35 +++++++++---------- docs-cn/14-reference/03-connector/go.mdx | 19 ++++++---- docs-cn/14-reference/03-connector/java.mdx | 14 +++----- docs-cn/14-reference/03-connector/node.mdx | 5 +++ docs-cn/14-reference/03-connector/rust.mdx | 9 +++-- 7 files changed, 52 insertions(+), 40 deletions(-) create mode 100644 docs-cn/14-reference/03-connector/_preparition.mdx diff --git a/docs-cn/14-reference/03-connector/_preparition.mdx b/docs-cn/14-reference/03-connector/_preparition.mdx new file mode 100644 index 0000000000..fb371509c0 --- /dev/null +++ b/docs-cn/14-reference/03-connector/_preparition.mdx @@ -0,0 +1,8 @@ +2. 已安装 maven 3.6 及以上版本 +3. 已安装 TDengine-client（使用原生连接必须安装，使用REST 连接无需安装） + +**注意**：由于 TDengine 的应用驱动是使用 C 语言开发的，使用原生连接时需要依赖系统对应的本地函数库。TDengine Linux 服务端安装包也附带了 TDengine client，也可以单独安装 [Linux 客户端](/get-started/) 连接远端 TDengine 集群。在 Windows 环境开发时需要安装 TDengine 对应的 [Windows 客户端](https://www.taosdata.com/cn/all-downloads/#TDengine-Windows-Client) 连接远端 TDengine 集群。 + +- libtaos.so 在 Linux 系统中成功安装 TDengine 后，依赖的 Linux b版客户端驱动 libtaos.so 文件会被自动拷贝至 /usr/lib/libtaos.so，该目录包含在 Linux 自动扫描路径上，无需单独指定。 +- taos.dll 在 Windows 系统中安装完客户端之后，驱动包依赖的 Windows 版客户端驱动 taos.dll 文件会自动拷贝到系统默认搜索路径 C:/Windows/System32 下，同样无需要单独指定。 + diff --git a/docs-cn/14-reference/03-connector/cpp.mdx b/docs-cn/14-reference/03-connector/cpp.mdx index 3dcf2623b8..689dfc86eb 100644 --- a/docs-cn/14-reference/03-connector/cpp.mdx +++ b/docs-cn/14-reference/03-connector/cpp.mdx @@ -199,8 +199,6 @@ TDengine 的异步 API 均采用非阻塞调用模式。应用程序可以用多 说明：如果 `taos_stmt_execute` 执行成功，假如不需要改变 SQL 语句的话，那么是可以复用 `taos_stmt_prepare` 的解析结果，直接进行第 3 ～ 6 步绑定新数据的。但如果执行出错，那么并不建议继续在当前的环境上下文下继续工作，而是建议释放资源，然后从 `taos_stmt_init` 步骤重新开始。 -除 C/C++ 语言外，TDengine 的 Java 语言原生连接 Connector 也提供参数绑定接口支持，具体请另外参见：[参数绑定接口的 Java 用法](/reference/connector/java#通过参数绑定写入数据)。 - 接口相关的具体函数如下（也可以参考 [prepare.c](https://github.com/taosdata/TDengine/blob/develop/examples/c/prepare.c) 文件中使用对应函数的方式）： - `TAOS_STMT* taos_stmt_init(TAOS *taos)` diff --git a/docs-cn/14-reference/03-connector/csharp.mdx b/docs-cn/14-reference/03-connector/csharp.mdx index bcc9bcc274..a0784175cc 100644 --- a/docs-cn/14-reference/03-connector/csharp.mdx +++ b/docs-cn/14-reference/03-connector/csharp.mdx @@ -4,13 +4,15 @@ sidebar_label: C# title: C# Connector --- +import Preparition from "./_preparition.mdx" + ## 总体介绍 -TDengine.Connector 是 TDengine 提供的 C# 本地客户端驱动连接器。该连接器通过 TDengine 客户端驱动建立本地连接，进而可以访问 TDengine 数据库。目前已支持 TDengine 的绝大部分特性。例如：同步查询、异步查询、管理连接、订阅消费，schemaless 等。 +TDengine.Connector 是 TDengine 提供的 C# 本地客户端驱动连接器。C# 语言开发人员可以通过 它开发存取 TDengine 数据库的应用软件。连接器支持通过客户端驱动（taosc）建立本地连接 TDengine 服务端。进行查询、订阅、schemaless 接口、参数绑定接口等功能。 -本文介绍如何在 Windows 或 Linux 环境中安装 TDengine.Connector，并通过 TDengine.Connector 连接 TDengine 数据库、进行数据查询、数据写入等基本操作。 +TDengine.Connector 目前暂未提供使用 REST 连接d的接口，用户可以参考 [RESTful APIs](https://docs.taosdata.com//reference/restful-api/) 文档自行编写。 -TDengine.Connector 目前暂未封装 RESTful 接口，用户可以参考 [RESTful APIs](https://docs.taosdata.com//reference/restful-api/) 文档自行编写。 +本文介绍如何在 Windows 或 Linux 环境中安装 TDengine.Connector，并通过 TDengine.Connector 连接 TDengine 数据库、进行数据查询、数据写入等基本操作。 ## 支持的平台 @@ -18,38 +20,33 @@ C# 连接器支持的系统有：Linux 64 / Windows x64/ Windows x86 ## 版本支持 -| TDengine.Connector | TDengine 版本 | 说明 | -|--------------------|:-------------------------------------:|--------------------------------| -| 1.0.2 | v2.5.0.x,v2.4.0.x,v2.3.4+ | 支持连接管理、同步查询、错误信息等功能。 | -| 1.0.3 | v2.5.0.x,v2.4.0.x,v2.3.4+ | 新增参数绑定、schemaless, json tag 等功能。 | -| 1.0.4 | v2.5.0.x,v2.4.0.x,v2.3.4+ | 新增异步查询，订阅等功能，修复绑定参数 bug。 | -| 1.0.5 | v2.5.0.x,v2.4.0.x,v2.3.4+ | 修复 Windows 同步查询中文报错 bug。 | -| 1.0.6 | v2.5.0.x,v2.4.0.x,v2.3.4+ | 修复schemaless bug。| +| TDengine.Connector | TDengine 版本 | +|--------------------|:-------------------------------------:| +| 1.0.2 ~ 1.0.6 | v2.3.4+ | ## 支持的特性 -### 本地连接 +### 原生连接 + +“原生连接”指连接器通过客户端驱动 taosc 直接与 TDengine 服务端建立连接。 -“本地连接”指连接器通过本地客户端驱动程序 taosc 直接与服务端程序 taosd 建立连接。 “本地连接”支持的特新如下： 1. 连接管理 2. 同步查询 3. 异步查询 4. 参数绑定 -5. 错误信息 -6. 订阅功能 -7. Schemaless +5. 订阅功能 +6. Schemaless ## 安装步骤 ### 安装前的准备 -* 安装 [.NET SDK](https://dotnet.microsoft.com/download) - -* 安装 [TDengine 客户端](/reference/connector/#安装客户端驱动) +1. 安装 [.NET SDK](https://dotnet.microsoft.com/download) + - （可选安装）[Nuget 客户端](https://docs.microsoft.com/en-us/nuget/install-nuget-client-tools) + -* 安装 （可选） [Nuget 客户端](https://docs.microsoft.com/en-us/nuget/install-nuget-client-tools) ### 使用 dotnet CLI 安装 diff --git a/docs-cn/14-reference/03-connector/go.mdx b/docs-cn/14-reference/03-connector/go.mdx index 7299ec2818..789d503d00 100644 --- a/docs-cn/14-reference/03-connector/go.mdx +++ b/docs-cn/14-reference/03-connector/go.mdx @@ -4,9 +4,15 @@ sidebar_label: Go title: Go Connector --- +import Preparition from "./_preparition.mdx" + ## 总体介绍 -driver-go 实现 Go [database/sql](https://golang.org/pkg/database/sql/) 包的 TDengine 驱动程序，同时提供通过本地的客户端驱动程序直接与服务端程序 taosd 进行订阅、 schemaless 写入和 stmt 功能。 +driver-go 是 TDengine 的官方 Go 语言连接器。Go 语言开发人员可以通过它开发存取 TDengine 数据库的应用软件。driver-go 实现了 Go [database/sql](https://golang.org/pkg/database/sql/) 包的接口，支持通过客户端驱动程序（taosc）原生连接 TDengine 服务端，支持数据写入、查询、订阅、schemaless 接口和参数绑定接口等功能。 + +driver-go 也支持使用 REST 连接 TDengine 服务端。 + +本文介绍如何在 Windows 或 Linux 环境中安装 driver-go，并通过 driver-go 连接 TDengine 数据库、进行数据查询、数据写入等基本操作。 Go 连接器的源码托管在 github。项目名称：driver-go。欢迎 [贡献源码](https://github.com/taosdata/driver-go) 或 [报告问题](https://github.com/taosdata/driver-go/issues)。 @@ -28,12 +34,12 @@ Go 连接器的源码托管在 github。项目名称：driver-go。欢迎 [贡 ### 原生连接 -`原生连接` 指连接器通过本地的客户端驱动程序直接与服务端程序 taosd 建立连接。 +“原生连接”指连接器通过客户端驱动（taosc）直接与 TDengine 服务端建立连接。 * database/sql (cgo 模式) * 订阅 -* schemaless -* stmt +* schemaless 接口 +* 参数绑定接口 ### REST 连接 @@ -45,9 +51,8 @@ REST 连接指连接器通过 taosAdapter 组件提供的 REST API 建立与 tao ### 安装前的准备 -* taos本地的客户端 -* Go 1.14 及以上 -* GCC 4.8.5 及以上 +1. 安装 Go 开发环境（Go 1.14 及以上，GCC 4.8.5 及以上） + 配置好环境变量，检查命令： diff --git a/docs-cn/14-reference/03-connector/java.mdx b/docs-cn/14-reference/03-connector/java.mdx index 28770b6f41..dc20bdc9c1 100644 --- a/docs-cn/14-reference/03-connector/java.mdx +++ b/docs-cn/14-reference/03-connector/java.mdx @@ -5,6 +5,8 @@ title: Java Connector description: 此连接器基于标准 JDBC API 实现。 --- +import Preparition from "./_preparition.mdx" + ## 总体介绍 `taos-jdbcdriver` 的实现包括两种形式： JDBC 原生连接和 JDBC-REST（taos-jdbcdriver-2.0.18 开始支持 JDBC-RESTful）。 JDBC 原生连接通过调用客户端驱动 libtaos.so（或 taos.dll ）的本地方法实现， JDBC-RESTful 则通过封装 TDengine REST 服务接口建立连接，REST 连接实现的功能集合和原生连接有少量不同。 @@ -105,17 +107,9 @@ TDengine 目前支持时间戳、数字、字符、布尔类型，与 Java 对 使用 Java Connector 连接数据库前，需要具备以下条件： -1. Linux 或 Windows 操作系统 -2. 已安装 Java 1.8 及以上运行时环境 -3. 已安装 maven 3.6 及以上版本 -4. 已安装 TDengine-client（使用 JDBC 原生连接必须安装，使用 JDBC-RESTful 无需安装） - -**注意**：由于 TDengine 的应用驱动是使用 C 语言开发的，使用 taos-jdbcdriver 驱动包时需要依赖系统对应的本地函数库。 - -- libtaos.so 在 Linux 系统中成功安装 TDengine 后，依赖的本地客户端驱动 libtaos.so 文件会被自动拷贝至 /usr/lib/libtaos.so，该目录包含在 Linux 自动扫描路径上，无需单独指定。 -- taos.dll 在 Windows 系统中安装完客户端之后，驱动包依赖的 taos.dll 文件会自动拷贝到系统默认搜索路径 C:/Windows/System32 下，同样无需要单独指定。 +1. 已安装 Java 1.8 或以上版本运行时环境 -**注意**：在 Windows 环境开发时需要安装 TDengine 对应的 [Windows 客户端](https://www.taosdata.com/cn/all-downloads/#TDengine-Windows-Client)，TDengine Linux 服务端安装包也附带了 TDengine client，也可以单独安装 [Linux 客户端](/get-started/) 连接远端 TDengine 集群。 + ### 使用 maven 安装 diff --git a/docs-cn/14-reference/03-connector/node.mdx b/docs-cn/14-reference/03-connector/node.mdx index 96b9f0b561..b9df7b2afa 100644 --- a/docs-cn/14-reference/03-connector/node.mdx +++ b/docs-cn/14-reference/03-connector/node.mdx @@ -4,6 +4,8 @@ sidebar_label: Node.js title: Node.js Connector --- +import Preparition from "./_preparition.mdx" + ## 总体介绍 td2.0-connector 是 TDengine 的官方 Node.js 连接器。Node.js 开发人员可以通过它开发可以存取 TDengine 数据的应用软件。 @@ -60,6 +62,9 @@ Node.js 连接器支持的系统有： ### 安装前的准备 +1. 安装 Node.js 开发环境 + + - 应用驱动安装请参考[安装连接器驱动步骤](/reference/connector/#安装客户端驱动)。 我们使用[node-gyp](https://github.com/nodejs/node-gyp)和 TDengine 服务端进行交互。安装 Node.js 本地驱动连接器之前，还需要根据具体操作系统来安装下文提到的一些依赖工具。如果要安装的是 RESTful 连接器则可以跳过以下步骤，直接只用 npm 安装。 diff --git a/docs-cn/14-reference/03-connector/rust.mdx b/docs-cn/14-reference/03-connector/rust.mdx index 1d04dfdfd6..39714c548c 100644 --- a/docs-cn/14-reference/03-connector/rust.mdx +++ b/docs-cn/14-reference/03-connector/rust.mdx @@ -4,9 +4,11 @@ sidebar_label: Rust title: Rust Connector --- +import Preparition from "./_preparition.mdx" + [![Crates.io](https://img.shields.io/crates/v/libtaos)](https://crates.io/crates/libtaos) ![Crates.io](https://img.shields.io/crates/d/libtaos) [![docs.rs](https://img.shields.io/docsrs/libtaos)](https://docs.rs/libtaos) -Rust 连接器 [libtaos][libtaos] 旨在为 Rust 开发者提供连接器官方支持。[libtaos][libtaos] 使用不同的 features 提供对 TDengine 客户端驱动和 REST 接口的支持。以下是可使用的特性列表： +libtaos 是 TDengine 的官方 Rust 语言连接器。Rust 语言开发人员可以通过它开发存取 TDengine 数据库的应用软件。libtaos 使用不同的 features 提供对通过客户端驱动程序（taosc）原生连接和使用 REST 连接 TDengine 服务端的。以下是可使用的特性列表： | 启用特性 | 支持平台 | 说明 | | -------- | --------------------- | ----------------------------------------------------------------- | @@ -28,7 +30,10 @@ Rust 连接器 [libtaos][libtaos] 旨在为 Rust 开发者提供连接器官方 ## 安装 -如需使用 TDengine 客户端驱动（taosc），请参考 [该文档](/reference/connector/#安装客户端驱动) 进行安装。使用 REST 接口无需安装客户端。之后可以按照如下说明在 [Rust](https://rust-lang.org) 项目中添加 [libtaos][libtaos] 依赖： +1. 安装 Rust 开发工具链 + + +之后可以按照如下说明在 [Rust](https://rust-lang.org) 项目中添加 [libtaos][libtaos] 依赖： ### 使用客户端驱动 -- GitLab