taos-connector-rust

taos is TDengine’s official Rust connector, published to crates.io as taos. It unifies two transport implementations, a pure-Rust WebSocket client (taos-ws) and an optional native binding to libtaos.so loaded via dlopen (taos-optin), behind one shared trait surface defined in taos-query, so application code written against TaosBuilder::from_dsn(...) works unchanged whichever backend feature flags select.

The crate covers the full surface a TDengine client needs: SQL query and exec, prepared-statement parameter binding (Stmt/Stmt2), schemaless writing, and TMQ data subscription (a Kafka-like consumer API for TDengine’s message queue). Optional features add connection pooling via r2d2 or deadpool, and TLS variants (rustls, native-tls) for the WebSocket transport. It is the primary way Rust services read from and write to a TDengine time-series database.

What You Get

• A unified Taos/TaosBuilder client that works identically over WebSocket or native transport, selected purely by Cargo feature flags
• Prepared-statement binding (Stmt and the newer Stmt2) with typed column views for high-throughput inserts
• A TMQ consumer API for subscribing to TDengine’s built-in message queue, similar in shape to a Kafka consumer
• Optional connection pooling via r2d2 or deadpool, and TLS backends (rustls, native-tls) for encrypted WebSocket connections
• A DSN parser (mdsn) and dedicated error type (taos-error) shared across every transport crate in the workspace

Common Use Cases

• Writing sensor or IoT telemetry into TDengine from a Rust ingestion service
• Running analytical SQL queries against time-series data from a Rust backend
• Streaming new rows in near-real-time via TMQ subscriptions instead of polling
• Bulk-loading data efficiently through parameter-bound batch inserts (Stmt2)

Under The Hood

Architecture The workspace is split into layered crates: taos-query defines the shared trait surface and data model (Queryable/AsyncQueryable, RawBlock, ColumnView, Value, the stmt/stmt2/tmq modules), and two independent transport crates implement those traits — taos-ws is a pure-Rust WebSocket protocol client, while taos-optin binds to the native libtaos.so via dlopen (hence “optin”: the native library is not linked at compile time). The top-level taos crate’s lib.rs uses #[cfg(feature = ...)] gating to re-export whichever backend(s) are enabled, so downstream code written against TaosBuilder::from_dsn(...) is transport-agnostic. Supporting crates (mdsn for DSN parsing, taos-error for a shared error type, taos-log/taos-macros for cross-cutting concerns) keep those concerns out of the transport implementations, giving the workspace a clean separation between protocol logic and public API surface.

Tech Stack A Rust 2021-edition Cargo workspace (rust-version 1.90) built on tokio for async execution (including a lazily-initialized global runtime for sync-context callers), async-trait for trait-level async methods, and futures for stream combinators. Serialization runs through serde/serde_json; optional pooling layers on r2d2 or deadpool; TLS for the WebSocket transport is pluggable between rustls and native-tls. Build-time metadata is captured with shadow-rs, structured logging goes through tracing, and the dev-dependency set includes criterion for benchmarking and clap for example binaries. The crate is published to crates.io and consumed by any Rust application connecting to a TDengine server or taosAdapter.

Code Quality Each workspace crate carries its own test suite: integration tests under taos/tests/ (pooling, TMQ, prepared statements, error handling), taos-optin/tests/ (native binding coverage), and taos-ws-sys/tests/ (TLS verification scenarios), alongside inline #[cfg(test)] unit tests in core modules like stmt.rs, stmt2.rs, and tmq.rs. CI runs on GitHub Actions with both clippy and rustfmt enabled and reports coverage through Codecov. Errors are represented through a dedicated taos-error crate rather than ad hoc string errors, giving callers a typed, catchable error surface across every transport.

API Design The public API centers on a single ergonomic entry point, TaosBuilder::from_dsn(dsn), that hides which transport is active behind one DSN string and one client type. Binding parameters, subscribing to TMQ, and running queries all follow consistent builder/async patterns, and the repository ships thirteen runnable examples covering binding, subscriptions, database creation, and both sync and async variants — lowering the gap between reading the API and writing working code against a live TDengine instance.