docs: tweaks related to recent ILP/HTTP changes (#57)

Author: amunra

README.md

@@ -4,7 +4,7 @@
 This library makes it easy to insert data into [QuestDB](https://questdb.io/).
 
 This client library implements the [InfluxDB Line Protocol](
-https://questdb.io/docs/reference/api/ilp/overview/) (ILP) over TCP.
+https://questdb.io/docs/reference/api/ilp/overview/) (ILP) over TCP or HTTP.
 
 * Implementation is in Rust, with no additional
   [run-time or link-time dependencies](doc/BUILD.md#pre-requisites-and-dependencies)
@@ -16,21 +16,21 @@ https://questdb.io/docs/reference/api/ilp/overview/) (ILP) over TCP.
 
 ## Insertion Protocols Overview
 
-Inserting data into QuestDB can be done via one of three protocols.
+Inserting data into QuestDB can be done in several ways.
+
+This library supports ILP/HTTP (default-recommended) and ILP/TCP (specific
+streaming use cases).
 
 | Protocol | Record Insertion Reporting | Data Insertion Performance |
 | -------- | -------------------------- | -------------------------- |
-| [ILP](https://questdb.io/docs/reference/api/ilp/overview/)| Errors in logs; Disconnect on error | **Best** |
+| **[ILP/HTTP](https://questdb.io/docs/reference/api/ilp/overview/)** | Transaction-level (on flush) | **Excellent** |
+| [ILP/TCP](https://questdb.io/docs/reference/api/ilp/overview/)| Errors in logs; Disconnect on error | **Best** (tolerates higher latency networks) |
 | [CSV Upload via HTTP](https://questdb.io/docs/reference/api/rest/#imp---import-data) | Configurable | Very Good |
 | [PostgreSQL](https://questdb.io/docs/reference/api/postgres/) | Transaction-level | Good |
 
-This library implements the **ILP protocol** and mitigates the lack of confirmation
-and error reporting by validating data ahead of time before any data is sent
-to the database instance.
-
-For example, the client library will report that a supplied string isn't encoded
-in UTF-8. Some issues unfortunately can't be caught by the library and require
-some [care and diligence to avoid data problems](doc/CONSIDERATIONS.md).
+Server errors are only reported back to the client for ILP/HTTP.
+See the [flush troubleshooting](doc/CONSIDERATIONS.md) docs for more details on
+how to debug ILP/TCP.
 
 For an overview and code examples, see the
 [ILP page of the developer docs](https://questdb.io/docs/develop/insert-data/#influxdb-line-protocol).

doc/CONSIDERATIONS.md

@@ -98,12 +98,22 @@ To determine the buffer size, call:
 
 ### Disconnections, Data Errors and troubleshooting
 
-A failure when flushing data gerally indicates that the network connection was
-dropped.
+#### ILP/HTTP
 
-The ILP protocol does not send errors back to the client. Instead, by design,
-it will disconnect a client if it encounters any insertion errors. This is to
-avoid errors going unnoticed.
+When using ILP/HTTP, server errors are reported back to the client from
+`flush` calls.
+
+#### ILP/TCP
+
+When using ILP/TCP, errors which cause disconnects can be found
+in the QuestDB server logs.
+
+When using TCP, failure when flushing data gerally indicates that the network
+connection was dropped.
+
+The ILP over TCP protocol does not send errors back to the client.
+Instead, by design, it will disconnect a client if it encounters any insertion
+errors. This is to avoid errors going unnoticed.
 
 As an example, if a client were to insert a `STRING` value into a `BOOLEAN`
 column, the QuestDB server would disconnect the client.

questdb-rs/README.md

@@ -46,6 +46,31 @@ fn main() -> Result<()> {
 }
 ```
 
+## Crate features
+
+This Rust crate supports a number of optional features.
+
+For example, if you want to work with ILP/HTTP and work with Chrono timestamps,
+use:
+
+```bash
+cargo add questdb-rs --features ilp-over-http chrono
+```
+
+### Default-enabled features
+
+* `tls-webpki-certs`: Use the `webpki-roots` crate for TLS cert verification.
+
+### Optional features
+
+These features are opt-in as they bring in additional downstream dependencies.
+
+* `ilp-over-http`: Enables ILP/HTTP support via the `ureq` crate.
+* `tls-native-certs`: Supports validating TLS certificates against the OS's
+  certificates store.
+* `insecure-skip-verify`: Allows skipping TLS validation.
+* `chrono_timestamp`: Allows specifying timestamps as `chrono::Datetime` objects.
+
 ## C, C++ and Python APIs
 
 This crate is also exposed as a C and C++ API and in turn exposed to Python.