In IoT and Industrial IoT (IIoT) environments, the connection method a time-series database (TSDB) uses directly affects read and write performance and system stability. Choosing the right connection method is the first step in building a high-performance data ingestion system.
A TSDB offers multiple connection paths to match different development environments and deployment architectures. In real projects, developers choose based on compatibility requirements, performance targets, and deployment models. Understanding the differences among the three main connection methods is essential for using a TSDB correctly.
WebSocket connection
A WebSocket connection uses a connector to communicate with taosd through the WebSocket API provided by the taosAdapter component. The core advantage is compatibility: all connectors that support this method work with server versions 3.3.6.0 and above. As an officially recommended connection method, WebSocket connections see wide use in production environments.
WebSocket is the officially recommended connection method. Because taosAdapter acts as an intermediate layer handling protocol conversion, the client and server are decoupled from version dependencies. This simplifies long-term TSDB operations.
Native connection
A native connection uses a connector to communicate with the taosd server directly through the taosc client driver. This approach has the shortest communication path and can deliver the lowest possible latency. For a TSDB, a native connection is the most direct data path.
Native connections require the taosc client driver version to match the server version. A version mismatch can cause connection failures or data anomalies. Native connections suit scenarios that demand extreme performance and where client-to-server version consistency can be strictly controlled. In an on-premises TSDB deployment where the operations team can synchronize version upgrades, a native connection is an efficient choice.
REST API
The REST API approach bypasses connectors entirely. It uses an HTTP client to call the REST API provided by the taosAdapter component to reach taosd. This is the connection method with the lowest entry barrier for a TSDB.
The main advantage of the REST API is its minimal access barrier: any programming language or tool that supports HTTP requests can use it. Its limitation is functional completeness. It is best suited for simple data queries or quick prototyping and debugging.
Comparison
| Dimension | WebSocket connection | Native connection | REST API |
|---|---|---|---|
| Compatibility | Cross-version compatible | Version must match | Depends on taosAdapter |
| Feature coverage | Full | Full | SQL execution only |
| Parameter binding (STMT) | Supported | Supported | Not supported |
| Data subscription (TMQ) | Supported | Supported | Not supported |
| Cloud service support | Supported | Not supported | Not supported |
| Access barrier | Medium | Low | Lowest |
When to use each method
Choose WebSocket connection for production environments, connecting to cloud service instances, scenarios requiring cross-version compatibility, and teams using multiple programming languages. As the officially recommended method, WebSocket connections balance feature coverage with compatibility.
Choose native connection for on-premises deployments with strict version control and latency-sensitive local applications. Native connections eliminate the intermediate forwarding layer, giving the highest communication efficiency in locally deployed TSDB environments.
Choose REST API for quick prototyping, simple data query tasks, and projects using less common programming languages without official connector support. The REST API has limited features but offers broad versatility as a lightweight complement.
Multi-language ecosystem support
Regardless of the connection method, the TSDB provides a set of official connectors covering mainstream programming languages. The official connectors currently include C/C++, Java, Python, Go, Node.js, C#, and Rust.
For Java developers, the JDBC connector supports the standard JDBC interface and adds efficient write capabilities. It uses background threads and dedicated queues to send data in batches, improving throughput. The Python and Go connectors also provide full asynchronous write support, suitable for high-concurrency data ingestion scenarios.
Summary
Connection method selection is a foundational decision in TSDB application development. WebSocket connections, with their cross-version compatibility and complete feature support, are the recommended choice for most scenarios. Native connections suit on-premises deployments where version consistency is strictly maintained. The REST API works well for lightweight query needs. Combined with the multi-language connector ecosystem, developers can choose the approach that best fits their project requirements.
